chrome.printing

Descrição

Use a API chrome.printing para enviar trabalhos de impressão para impressoras instaladas no Chromebook.

Permissões

printing

Disponibilidade

Chrome 81+ Apenas no ChromeOS

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 usando getPrinterInfo().
  • Uma estrutura SubmitJobRequest, que especifica a impressora usada e o arquivo ou a data a ser impressa. Essa estrutura contém uma referência à estrutura ticket.
  • 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. Quando incluída, essa chave precisa ser uma matriz com um membro: um objeto em que id é '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

    PrinterStatus

    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

  • descrição

    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.

  • name

    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

    PrinterSource

    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

    PrintJob

    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 e VendorTicketItem, 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.

  • 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()

Promessa 
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 recente

    Promessas 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()

Promessa 
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

Retorna

  • Chrome 100 ou mais recente

    Promessas 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()

Promessa 
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

Retorna

  • Prometer<impressora[]>

    Chrome 100 ou mais recente

    Promessas 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()

Promessa 
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

Retorna

  • Chrome 100 ou mais recente

    Promessas 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.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (jobId: string,status: JobStatus)=>void