Descrição
Use a API chrome.printing
para enviar trabalhos de impressão para impressoras instaladas no Chromebook.
Permissões
printing
Disponibilidade
Todos os métodos e eventos chrome.printing
exigem que você declare a permissão "printing"
no manifesto de extensões. Exemplo:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Exemplos
Os exemplos abaixo demonstram o uso de cada um dos métodos no namespace de impressão. Este código é copiado ou baseado em api-samples/printing no repositório extensions-samples do GitHub.
cancelJob()
Este exemplo usa o gerenciador onJobStatusChanged
para ocultar um botão "Cancelar" quando jobStatus
não é PENDING
nem IN_PROGRESS
. Em algumas redes ou quando um Chromebook está conectado diretamente à impressora, esses estados podem passar muito rápido para que o botão de cancelamento fique visível por tempo suficiente para ser chamado. Esse é um exemplo de impressão bastante simplificado.
chrome.printing.onJobStatusChanged.addListener((jobId, status) => {
const cancelButton = document.getElementById("cancelButton");
cancelButton.addEventListener('click', () => {
chrome.printing.cancelJob(jobId).then((response) => {
if (response !== undefined) {
console.log(response.status);
}
if (chrome.runtime.lastError !== undefined) {
console.log(chrome.runtime.lastError.message);
}
});
});
if (status !== "PENDING" && status !== "IN_PROGRESS") {
cancelButton.style.visibility = 'hidden';
} else {
cancelButton.style.visibility = 'visible';
}
}
getPrinters() and getPrinterInfo()
Um único exemplo é usado para essas funções porque a coleta de informações exige um ID, que é recuperado chamando getPrinters()
. Este exemplo registra o nome e a descrição da impressora padrão no console. Esta é uma versão simplificada do exemplo de impressão.
const printers = await chrome.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
const printerInfo = await chrome.printing.getPrinterInfo(printer.id);
return printerInfo.isDefault;
}
console.log(`Default printer: ${defaultPrinter.name}.\n\t${defaultPrinter.description}`);
enviarJob()
O método submitJob()
requer três coisas.
- Uma estrutura
ticket
especificando quais recursos da impressora serão usados. Se o usuário precisar selecionar um dos recursos disponíveis, você poderá recuperá-los para uma impressora específica usandogetPrinterInfo()
. - Uma estrutura
SubmitJobRequest
, que especifica a impressora usada e o arquivo ou a data a ser impressa. Essa estrutura contém uma referência à estruturaticket
. - Um blob do arquivo ou dados a serem impressos.
Chamar submitJob()
aciona uma caixa de diálogo que solicita a confirmação da impressão do usuário. Use o PrintingAPIExtensionsAllowlist
para ignorar a confirmação.
Esta é uma versão simplificada do exemplo de impressão. Observe que o ticket
é anexado à estrutura SubmitJobRequest
(linha 8) e que os dados a serem impressos são convertidos em um blob (linha 10). Encontrar o código da impressora (linha 1) é mais complicado no exemplo do que o mostrado aqui.
const defaultPrinter = getDefaultPrinter();
const ticket = getPrinterTicket(defaultPrinter);
const arrayBuffer = getPrintData();
const submitJobRequest = {
job: {
printerId: defaultPrinter,
title: 'test job',
ticket: ticket,
contentType: 'application/pdf',
document: new Blob([new Uint8Array(arrayBuffer)], {
type: 'application/pdf'
});
}
};
chrome.printing.submitJob(submitJobRequest, (response) => {
if (response !== undefined) {
console.log(response.status);
}
if (chrome.runtime.lastError !== undefined) {
console.log(chrome.runtime.lastError.message);
}
});
Impressão em rolo
Este exemplo mostra como criar um tíquete de impressora para impressão contínua (ou rolo), que costuma ser usado com a impressão de recibos. O objeto submitJobRequest
para impressão com rolagem é o mesmo mostrado no exemplo submitJob()
.
Se você precisar alterar o valor padrão para o corte de papel, use a tecla vendor_ticket_item
. O padrão varia de acordo com a impressora. Para mudar o valor, forneça uma matriz com um membro: um objeto em que id
seja 'finishings'
. O valor pode ser 'trim'
para impressoras que cortam o rolo ao final da impressão ou 'none'
para impressoras que exigem a eliminação do trabalho de impressão.
const ticket = {
version: '1.0',
print: {
vendor_ticket_item: [{id: 'finishings', value: 'trim'}],
color: {type: 'STANDARD_MONOCHROME'},
duplex: {type: 'NO_DUPLEX'},
page_orientation: {type: 'PORTRAIT'},
copies: {copies: 1},
dpi: {horizontal_dpi: 300, vertical_dpi: 300},
media_size: {
width_microns: 72320,
height_microns: 100000
},
collate: {collate: false}
}
};
Algumas impressoras não são compatíveis com a opção "finishings"
. Para saber se a impressora tem, chame getPrinterInfo()
e procure um "display_name"
de "finishings/11"
.
"vendor_capability": [
{
"display_name": "finishings/11",
"id": "finishings/11",
"type": "TYPED_VALUE",
"typed_value_cap": {
"value_type": "BOOLEAN"
}
},
...
]
Os valores na chave media_size
de um bilhete são específicos para cada impressora. Para selecionar um tamanho adequado, chame getPrinterInfo()
. O GetPrinterResponse
retornado contém uma matriz de tamanhos de mídia compatíveis em "media_size"."option"
. Escolha uma opção cujo valor de "is_continuous_feed"
seja verdadeiro. Use os valores de altura e largura do ingresso.
"media_size": {
"option": [
{
"custom_display_name": "",
"is_continuous_feed": true,
"max_height_microns": 2000000,
"min_height_microns": 25400,
"width_microns": 50800
},
...
]
}
Tipos
GetPrinterInfoResponse
Propriedades
-
capabilities
objeto opcional
Recursos da impressora no formato CDD. A propriedade pode estar ausente.
-
status
O status da impressora.
JobStatus
Status do trabalho de impressão.
Tipo enumerado
"PENDENTE"
O trabalho de impressão foi recebido no lado do Chrome, mas ainda não foi processado.
"IN_PROGRESS"
O trabalho de impressão foi enviado para impressão.
"FALHA"
O trabalho de impressão foi interrompido devido a um erro.
"CANCELADO"
O trabalho de impressão foi cancelado pelo usuário ou pela API.
"PRINTED"
O trabalho de impressão foi impresso sem erros.
Printer
Propriedades
-
description
string
A descrição legível da impressora.
-
id
string
O identificador da impressora; com garantia de ser exclusivo entre as impressoras no dispositivo.
-
isDefault
boolean
A sinalização que mostra se a impressora atende às regras DefaultPrinterSelection. Observe que várias impressoras podem ser sinalizadas.
-
nome
string
O nome da impressora.
-
recentlyUsedRank
número opcional
O valor que mostra há quanto tempo a impressora foi usada para imprimir no Chrome. Quanto menor o valor, mais recente a impressora foi usada. O valor mínimo é 0. O valor ausente indica que a impressora não foi usada recentemente. Esse valor será exclusivo entre as impressoras.
-
source
A origem da impressora (usuário ou política configurada).
-
uri
string
O URI da impressora. Isso pode ser usado por extensões para escolher a impressora para o usuário.
PrinterSource
A origem da impressora.
Tipo enumerado
"USUÁRIO"
A impressora foi adicionada pelo usuário.
"POLICY"
A impressora foi adicionada por meio da política.
PrinterStatus
O status da impressora.
Tipo enumerado
"DOOR_OPEN"
A porta da impressora está aberta. A impressora ainda aceita trabalhos de impressão.
"TRAY_MISSING"
A bandeja da impressora não foi encontrada. A impressora ainda aceita trabalhos de impressão.
"OUT_OF_INK"
A impressora está sem tinta. A impressora ainda aceita trabalhos de impressão.
"OUT_OF_PAPER"
A impressora está sem papel. A impressora ainda aceita trabalhos de impressão.
"OUTPUT_FULL"
A área de saída da impressora (por exemplo, a bandeja) está cheia. A impressora ainda aceita trabalhos de impressão.
"PAPER_JAM"
A impressora tem um atolamento de papel. A impressora ainda aceita trabalhos de impressão.
"GENERIC_ISSUE"
Um problema genérico. A impressora ainda aceita trabalhos de impressão.
"STOPPED"
A impressora foi interrompida e não imprime, mas ainda aceita trabalhos de impressão.
"UNREACHABLE"
A impressora está inacessível e não aceita trabalhos de impressão.
"EXPIRED_CERTIFICATE"
O certificado SSL expirou. A impressora aceita trabalhos, mas eles falham.
"DISPONÍVEL"
A impressora está disponível.
SubmitJobRequest
Propriedades
-
job
O trabalho de impressão a ser enviado. O único tipo de conteúdo aceito é "application/pdf", e o Cloud Job Ticket não deve incluir os campos
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
eVendorTicketItem
, porque eles são irrelevantes para a impressão nativa. Todos os outros campos precisam estar presentes.
SubmitJobResponse
Propriedades
-
jobId
string opcional
O ID do trabalho de impressão criado. Esse é um identificador exclusivo entre todos os trabalhos de impressão no dispositivo. Se o status não for OK, o jobId será nulo.
-
status
O status da solicitação.
SubmitJobStatus
O status da solicitação submitJob
.
Tipo enumerado
"OK"
A solicitação de trabalho de impressão enviada foi aceita.
"USER_REJECTED"
A solicitação de trabalho de impressão enviada foi rejeitada pelo usuário.
Propriedades
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
O número máximo de vezes que getPrinterInfo
pode ser chamado por minuto.
Valor
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
O número máximo de vezes que submitJob
pode ser chamado por minuto.
Valor
40
Métodos
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Cancela o job enviado anteriormente.
Parâmetros
-
jobId
string
O ID do trabalho de impressão a ser cancelado. Precisa ser o mesmo ID recebido em um
SubmitJobResponse
. -
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 100 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Retorna o status e os recursos da impressora no formato CDD. Esta chamada falhará com um erro de tempo de execução se nenhuma impressora com o ID fornecido estiver instalada.
Parâmetros
-
printerId
string
-
callback
função optional
O parâmetro
callback
tem esta aparência:(response: GetPrinterInfoResponse) => void
-
resposta
-
Retorna
-
Promise<GetPrinterInfoResponse>
Chrome 100 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Retorna a lista de impressoras disponíveis no dispositivo. Isso inclui impressoras adicionadas manualmente, empresariais e descobertas.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(printers: Printer[]) => void
-
impressoras
-
Retorna
-
Prometer<impressora[]>
Chrome 100 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Envia o trabalho para impressão. Se a extensão não estiver listada na política PrintingAPIExtensionsAllowlist
, o usuário vai precisar aceitar o trabalho de impressão.
Antes do Chrome 120, essa função não retornava uma promessa.
Parâmetros
-
request
-
callback
função optional
O parâmetro
callback
tem esta aparência:(response: SubmitJobResponse) => void
-
resposta
-
Retorna
-
Promise<SubmitJobResponse>
Chrome 100 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.
Eventos
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
Evento acionado quando o status do job é alterado. Isso só é disparado para os jobs criados por esta extensão.