chrome.printing

Descrição

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

Permissões

printing

Disponibilidade

Chrome 81 ou superior Somente ChromeOS

Todos os métodos e eventos de 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. Esse código é copiado de ou baseado em api-samples/printing no repositório extensions-samples do GitHub.

cancelJob()

Este exemplo usa o gerenciador onJobStatusChanged para ocultar um valor "cancel". quando o jobStatus não for PENDING nem IN_PROGRESS. Em algumas redes ou quando um Chromebook está conectado diretamente à impressora, esses estados podem passar rápido demais para que o botão de cancelamento fique visível por tempo suficiente para ser chamado. Este é 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 da impressora requer um ID da impressora, 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 um dos recursos disponíveis, use getPrinterInfo() para buscar uma impressora específica.
  • Uma estrutura SubmitJobRequest, que especifica a impressora a ser usada e o arquivo ou a data a ser impressa. 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 solicitando 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 a ticket está anexada à estrutura SubmitJobRequest (linha 8) e que os dados a serem mostrados são convertidos em um blob (linha 10). Encontrar 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

Neste exemplo, mostramos como criar um tíquete de impressora para impressão contínua (ou em rolo), que geralmente é usada com a impressão de recibos. O objeto submitJobRequest para a impressão em rolo é o mesmo mostrado no exemplo submitJob().

Se você precisar alterar o valor padrão para cortar papel, use a tecla vendor_ticket_item. O padrão varia de acordo com a impressora. Para alterar 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 remoçã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 determinar se ela faz isso, 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 tíquete são específicos de 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 em que o valor de "is_continuous_feed" seja verdadeiro. Use os valores de altura e largura para o 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

    Status da impressora.

JobStatus

Status do trabalho de impressão.

Enumeração

"PENDENTE"
O trabalho de impressão é recebido pelo Chrome, mas ainda não foi processado.

"IN_PROGRESS"
O trabalho de impressão é enviado para impressão.

"FALHA"
O trabalho de impressão foi interrompido devido a um erro.

"CANCELED"
O trabalho de impressão foi cancelado pelo usuário ou por meio de uma API.

"IMPRESSO"
A tarefa de impressão foi impressa sem erros.

Printer

Propriedades

  • descrição

    string

    A descrição legível da impressora.

  • id

    string

    O identificador da impressora. é exclusiva entre as impressoras do dispositivo.

  • isDefault

    booleano

    A sinalização que mostra se a impressora se encaixa nas regras DefaultPrinterSelection. É possível que várias impressoras sejam sinalizadas.

  • nome

    string

    O nome da impressora.

  • recentlyUsedRank

    número opcional

    O valor que indica há quanto tempo a impressora foi usada para impressão 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 é 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 fonte da impressora.

Enumeração

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

"POLICY"
A impressora foi adicionada usando a política.

PrinterStatus

Status da impressora.

Enumeração

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

"TRAY_MISSING"
A bandeja da impressora está ausente. Ela ainda aceita trabalhos de impressão.

"OUT_OF_INK"
A impressora está sem tinta. Ela ainda aceita trabalhos de impressão.

"OUT_OF_PAPER"
A impressora está sem papel. Ela ainda aceita trabalhos de impressão.

"OUTPUT_FULL"
A área de saída da impressora (por exemplo, a bandeja) está cheia. Ela ainda aceita trabalhos de impressão.

"PAPER_JAM"
A impressora tem um atolamento de papel. Ela ainda aceita trabalhos de impressão.

"GENERIC_ISSUE"
Algum problema genérico. Ela 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 os trabalhos, mas eles falham.

"DISPONÍVEL"
A impressora está disponível.

SubmitJobRequest

Propriedades

  • job

    PrintJob

    A tarefa de impressão a ser enviada. O único tipo de conteúdo aceito é "application/pdf", e o Cloud Job Ticket 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 do 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 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 uma SubmitJobResponse.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 100 ou mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 determinado ID estiver instalada.

Parâmetros

Retorna

  • Promise&lt;GetPrinterInfoResponse&gt;

    Chrome 100 ou mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getPrinters()

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

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (printers: Printer[]) => void

Retorna

  • Promessa<Printer[]>

    Chrome 100 ou mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 receberá uma solicitação para aceitar o trabalho de impressão. Antes do Chrome 120, essa função não retornava uma promessa.

Parâmetros

Retorna

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100 ou mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onJobStatusChanged

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

Evento disparado quando o status do trabalho é alterado. Isso só é disparado para as vagas criadas por essa extensão.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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