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 ou mais recente Somente no ChromeOS

Todos os métodos e eventos chrome.printing exigem que você declare a permissão "printing" no manifesto da extensão. 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 de extensões-samples do GitHub.

cancelJob()

Este exemplo usa o gerenciador onJobStatusChanged para ocultar um botão "Cancelar" quando o 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 seja acionado. Este é um exemplo de impressão muito 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 obtenção de informações da impressora requer 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}`);

submitJob()

O método submitJob() requer três coisas.

  • Uma estrutura ticket que especifica quais recursos da impressora serão usados. Se o usuário precisar selecionar entre os recursos disponíveis, você poderá extraí-los para uma impressora específica usando getPrinterInfo().
  • Uma estrutura SubmitJobRequest, que especifica a impressora a ser usada e o arquivo ou a data a serem impressos. Essa estrutura contém uma referência à estrutura ticket.
  • Um blob do arquivo ou dos dados a serem impressos.

Chamar submitJob() aciona uma caixa de diálogo que solicita que o usuário confirme a impressão. Use PrintingAPIExtensionsAllowlist para ignorar a confirmação.

Esta é uma versão simplificada do exemplo de impressão. Observe que o ticket está anexado à estrutura SubmitJobRequest (linha 8) e que os dados a serem impressos são convertidos em um blob (linha 10). Conseguir o ID da impressora (linha 1) é mais complicado no exemplo do que 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 cartão de impressão para impressão contínua (ou em bobina), que é usado com frequência para impressão de recibos. O objeto submitJobRequest para impressão de rolo é o mesmo mostrado no exemplo de submitJob().

Se você precisar mudar o valor padrão do corte de papel, use a chave 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 com id igual a 'finishings'. O valor pode ser 'trim' para impressoras que cortam o rolo no final da impressão ou 'none' para impressoras que exigem que o trabalho de impressão seja rasgado.

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 determinar se a impressora tem essa capacidade, 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 ticket 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 aceitos em "media_size"."option". Escolha uma opção com o valor "is_continuous_feed" definido como 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.

Enumeração

"PENDING"
O job de impressão foi recebido no Chrome, mas ainda não foi processado.

"IN_PROGRESS"
O job de impressão foi enviado para impressão.

"FAILED"
O job de impressão foi interrompido devido a algum erro.

"CANCELED"
O job de impressão foi cancelado pelo usuário ou pela API.

"PRINTED"
O job 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, que precisa ser exclusivo entre as impressoras no dispositivo.

  • isDefault

    booleano

    A flag que mostra se a impressora se encaixa nas regras de DefaultPrinterSelection. Várias impressoras podem ser sinalizadas.

  • nome

    string

    O nome da impressora.

  • recentlyUsedRank

    número opcional

    O valor que mostra a data mais recente em que a impressora foi usada para impressão no Chrome. Quanto menor o valor, mais recente foi o uso da impressora. O valor mínimo é 0. O valor ausente indica que a impressora não foi usada recentemente. Esse valor é garantido como 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 do usuário.

PrinterSource

A origem da impressora.

Enumeração

"USER"
A impressora foi adicionada pelo usuário.

"POLÍTICA"
A impressora foi adicionada pela política.

PrinterStatus

O status da impressora.

Enumeração

"DOOR_OPEN"
A porta da impressora está aberta. A impressora ainda aceita trabalhos de impressão.

"TRAY_MISSING"
A bandeja da impressora está ausente. 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 congestionamento de papel. A impressora ainda aceita trabalhos de impressão.

"GENERIC_ISSUE"
Algum problema genérico. A impressora ainda aceita trabalhos de impressão.

"INTERROMPIDA"
A impressora está interrompida e não imprime, mas ainda aceita trabalhos de impressão.

"UNREACHABLE"
A impressora não pode ser acessada e não aceita trabalhos de impressão.

"EXPIRED_CERTIFICATE"
O certificado SSL expirou. A impressora aceita jobs, 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 cartão de job do Cloud não pode 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.

Enumeração

"OK"
A solicitação de impressão enviada foi aceita.

"USER_REJECTED"
A solicitação 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. Esse ID precisa ser o mesmo recebido em um SubmitJobResponse.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 100+

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getJobStatus()

Promessa Pendente
chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
)

Retorna o status do job de impressão. Essa chamada vai falhar com um erro de execução se o job de impressão com o jobId fornecido não existir. jobId: o ID do job de impressão para retornar o status. Esse ID precisa ser o mesmo recebido em um SubmitJobResponse.

Parâmetros

  • jobId

    string

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (status: JobStatus) => void

Retorna

  • Promise<JobStatus>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getPrinterInfo()

Promessa 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

Retorna o status e os recursos da impressora no formato CDD. Essa chamada vai falhar com um erro de execução se nenhuma impressora com o ID especificado estiver instalada.

Parâmetros

Retorna

  • Chrome 100+

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

getPrinters()

Promessa 
chrome.printing.getPrinters(
  callback?: function,
)

Retorna a lista de impressoras disponíveis no dispositivo. Isso inclui impressoras adicionadas manualmente, corporativas e descobertas.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (printers: Printer[]) => void

Retorna

  • Promise<Printer[]>

    Chrome 100+

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

submitJob()

Promessa 
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

Envia o job 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+

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

Eventos

onJobStatusChanged

chrome.printing.onJobStatusChanged.addListener(
  callback: function,
)

Evento acionado quando o status do job é alterado. Isso só é acionado para os jobs criados por essa extensão.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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