browser.printing

Descripción

Usa la API de chrome.printing para enviar trabajos de impresión a las impresoras instaladas en la Chromebook.

Permisos

printing

Disponibilidad

Chrome 81 y versiones posteriores browser.* desde Chrome 148 Solo en ChromeOS

Todos los métodos y eventos de browser.printing requieren que declares el permiso "printing" en el manifiesto de la extensión. Por ejemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "printing"
  ],
  ...
}

Ejemplos

En los siguientes ejemplos, se muestra cómo usar cada uno de los métodos en el espacio de nombres de impresión. Este código se copia de api-samples/printing en el repositorio de GitHub extensions-samples o se basa en él.

cancelJob()

En este ejemplo, se usa el controlador onJobStatusChanged para ocultar un botón "Cancelar" cuando el jobStatus no es PENDING ni IN_PROGRESS. Ten en cuenta que, en algunas redes o cuando una Chromebook está conectada directamente a la impresora, estos estados pueden pasar demasiado rápido como para que el botón de cancelación esté visible el tiempo suficiente para que se lo llame. Este es un ejemplo de impresión muy simplificado.

browser.printing.onJobStatusChanged.addListener((jobId, status) => {
  const cancelButton = document.getElementById("cancelButton");
  cancelButton.addEventListener('click', () => {
    browser.printing.cancelJob(jobId).then((response) => {
      if (response !== undefined) {
        console.log(response.status);
      }
      if (browser.runtime.lastError !== undefined) {
        console.log(browser.runtime.lastError.message);
      }
    });
  });
  if (status !== "PENDING" && status !== "IN_PROGRESS") {
    cancelButton.style.visibility = 'hidden';
  } else {
    cancelButton.style.visibility = 'visible';
  }
}

getPrinters() and getPrinterInfo()

Se usa un solo ejemplo para estas funciones, ya que obtener información de la impresora requiere un ID de impresora, que se recupera llamando a getPrinters(). En este ejemplo, se registran el nombre y la descripción de la impresora predeterminada en la consola. Esta es una versión simplificada del ejemplo de impresión.

​​const printers = await browser.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
  const printerInfo = await browser.printing.getPrinterInfo(printer.id);
  return printerInfo.isDefault;
}
console.log(`Default printer: ${defaultPrinter.name}.\n\t${defaultPrinter.description}`);

submitJob()

El método submitJob() requiere tres elementos.

  • Es una estructura ticket que especifica qué funciones de la impresora se deben usar. Si el usuario necesita seleccionar entre las funciones disponibles, puedes recuperarlas para una impresora específica con getPrinterInfo().
  • Una estructura SubmitJobRequest, que especifica la impresora que se usará y el archivo o los datos que se imprimirán. Esta estructura contiene una referencia a la estructura ticket.
  • Un blob del archivo o los datos que se imprimirán

Cuando se llama a submitJob(), se activa un cuadro de diálogo en el que se le pide al usuario que confirme la impresión. Usa la marca PrintingAPIExtensionsAllowlist para omitir la confirmación.

Esta es una versión simplificada del ejemplo de impresión. Observa que el ticket se adjunta a la estructura SubmitJobRequest (línea 8) y que los datos que se imprimirán se convierten en un BLOB (línea 10). Obtener el ID de la impresora (línea 1) es más complicado en la muestra de lo que se muestra aquí.

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'
    });
  }
};

browser.printing.submitJob(submitJobRequest, (response) => {
  if (response !== undefined) {
    console.log(response.status);
  }
  if (browser.runtime.lastError !== undefined) {
    console.log(browser.runtime.lastError.message);
  }
});

Impresión en rollo

En este ejemplo, se muestra cómo compilar un ticket de impresora para la impresión continua (o en rollo), que se suele usar para imprimir recibos. El objeto submitJobRequest para la impresión en rollo es el mismo que se muestra en el ejemplo de submitJob().

Si necesitas cambiar el valor predeterminado para el corte de papel, usa la clave vendor_ticket_item. (El valor predeterminado varía según la impresora). Para cambiar el valor, proporciona un array con un miembro: un objeto cuyo id sea 'finishings'. El valor puede ser 'trim' para las impresoras que cortan el rollo al final de la impresión o 'none' para las impresoras que requieren que se corte el trabajo de impresión.

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}
  }
};

Algunas impresoras no admiten la opción "finishings". Para determinar si tu impresora lo hace, llama a getPrinterInfo() y busca un "display_name" de "finishings/11".

"vendor_capability": [
  {
    "display_name": "finishings/11",
    "id": "finishings/11",
    "type": "TYPED_VALUE",
    "typed_value_cap": {
      "value_type": "BOOLEAN"
    }
  },
  ...
]

Los valores de la clave media_size de un ticket son específicos de cada impresora. Para seleccionar un tamaño adecuado, llama a getPrinterInfo(). El GetPrinterResponse que se devuelve contiene un array de tamaños de medios admitidos en "media_size"."option". Elige una opción cuyo valor de "is_continuous_feed" sea verdadero. Usa sus valores de altura y ancho para el boleto.

"media_size": {
  "option": [
  {
    "custom_display_name": "",
    "is_continuous_feed": true,
    "max_height_microns": 2000000,
    "min_height_microns": 25400,
    "width_microns": 50800
  },
  ...
  ]
}

Tipos

GetPrinterInfoResponse

Propiedades

  • capabilities

    objeto opcional

    Son las capacidades de la impresora en formato CDD. Es posible que falte la propiedad.

  • estado

    PrinterStatus

    Es el estado de la impresora.

JobStatus

Es el estado del trabajo de impresión.

Enum

"PENDING"
Se recibe el trabajo de impresión en Chrome, pero aún no se procesó.

"IN_PROGRESS"
El trabajo de impresión se envía para su impresión.

"FAILED"
El trabajo de impresión se interrumpió debido a un error.

"CANCELED"
El usuario o la API cancelaron el trabajo de impresión.

"PRINTED"
El trabajo de impresión se imprimió sin errores.

Printer

Propiedades

  • descripción

    string

    Es la descripción legible por humanos de la impresora.

  • id

    string

    Es el identificador de la impresora, que se garantiza que es único entre las impresoras del dispositivo.

  • isDefault

    booleano

    Es el indicador que muestra si la impresora cumple con las reglas de DefaultPrinterSelection. Ten en cuenta que se podrían marcar varias impresoras.

  • nombre

    string

    Es el nombre de la impresora.

  • recentlyUsedRank

    number opcional

    Es el valor que muestra qué tan recientemente se usó la impresora para imprimir desde Chrome. Cuanto menor sea el valor, más recientemente se usó la impresora. El valor mínimo es 0. Si falta el valor, significa que la impresora no se usó recientemente. Se garantiza que este valor es único entre las impresoras.

  • source

    PrinterSource

    La fuente de la impresora (usuario o política configurada).

  • uri

    string

    Es el URI de la impresora. Las extensiones pueden usar este parámetro para elegir la impresora del usuario.

PrinterSource

La fuente de la impresora.

Enum

"USER"
El usuario agregó la impresora.

"POLICY"
La impresora se agregó a través de la política.

PrinterStatus

Es el estado de la impresora.

Enum

"DOOR_OPEN"
La puerta de la impresora está abierta. La impresora sigue aceptando trabajos de impresión.

"TRAY_MISSING"
Falta la bandeja de la impresora. La impresora sigue aceptando trabajos de impresión.

"OUT_OF_INK"
La impresora no tiene tinta. La impresora sigue aceptando trabajos de impresión.

"OUT_OF_PAPER"
La impresora no tiene papel. La impresora sigue aceptando trabajos de impresión.

"OUTPUT_FULL"
El área de salida de la impresora (p.ej., la bandeja) está llena. La impresora sigue aceptando trabajos de impresión.

"PAPER_JAM"
La impresora tiene un atasco de papel. La impresora sigue aceptando trabajos de impresión.

"GENERIC_ISSUE"
Un problema genérico. La impresora sigue aceptando trabajos de impresión.

"STOPPED"
La impresora está detenida y no imprime, pero sigue aceptando trabajos de impresión.

"UNREACHABLE"
No se puede acceder a la impresora y no acepta trabajos de impresión.

"EXPIRED_CERTIFICATE"
El certificado SSL venció. La impresora acepta trabajos, pero estos fallan.

"AVAILABLE"
La impresora está disponible.

SubmitJobRequest

Propiedades

  • trabajo

    PrintJob

    Es el trabajo de impresión que se enviará. Los tipos de contenido admitidos son "application/pdf" e "image/png". El ticket de trabajo de Cloud no debe incluir los campos FitToPageTicketItem, PageRangeTicketItem ni ReverseOrderTicketItem, ya que no son relevantes para la impresión nativa. VendorTicketItem es opcional. Todos los demás campos deben estar presentes.

SubmitJobResponse

Propiedades

  • ID de tarea

    string opcional

    Es el ID del trabajo de impresión creado. Este es un identificador único entre todos los trabajos de impresión del dispositivo. Si el estado no es OK, jobId será nulo.

  • Es el estado de la solicitud.

SubmitJobStatus

El estado de la solicitud de submitJob.

Enum

"OK"
Se aceptó la solicitud de trabajo de impresión enviada.

"USER_REJECTED"
El usuario rechazó la solicitud de trabajo de impresión enviada.

Propiedades

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Es la cantidad máxima de veces que se puede llamar a getPrinterInfo por minuto.

Valor

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Es la cantidad máxima de veces que se puede llamar a submitJob por minuto.

Valor

40

Métodos

cancelJob()

browser.printing.cancelJob(
  jobId: string,
): Promise<void>

Cancela el trabajo enviado anteriormente.

Parámetros

  • ID de tarea

    string

    Es el ID del trabajo de impresión que se cancelará. Debe ser el mismo ID que se recibió en un SubmitJobResponse.

Muestra

  • Promise<void>

    Chrome 100 y versiones posteriores del navegador* desde Chrome 148

getJobStatus()

Chrome 135 y versiones posteriores browser.* desde Chrome 148 
browser.printing.getJobStatus(
  jobId: string,
): Promise<JobStatus>

Muestra el estado del trabajo de impresión. Esta llamada fallará con un error de tiempo de ejecución si no existe el trabajo de impresión con el jobId determinado. jobId: Es el ID del trabajo de impresión del que se devolverá el estado. Debe ser el mismo ID que se recibió en un SubmitJobResponse.

Parámetros

  • ID de tarea

    string

Muestra

getPrinterInfo()

browser.printing.getPrinterInfo(
  printerId: string,
): Promise<GetPrinterInfoResponse>

Muestra el estado y las capacidades de la impresora en formato CDD. Esta llamada fallará con un error de tiempo de ejecución si no hay impresoras instaladas con el ID proporcionado.

Parámetros

  • printerId

    string

Muestra

getPrinters()

browser.printing.getPrinters(): Promise<Printer[]>

Devuelve la lista de impresoras disponibles en el dispositivo. Esto incluye las impresoras agregadas manualmente, las empresariales y las descubiertas.

Muestra

  • Promise<Printer[]>

    Chrome 100 y versiones posteriores del navegador* desde Chrome 148

submitJob()

browser.printing.submitJob(
  request: SubmitJobRequest,
): Promise<SubmitJobResponse>

Envía el trabajo para imprimirlo. Si la extensión no aparece en la política PrintingAPIExtensionsAllowlist, se le solicita al usuario que acepte el trabajo de impresión. Antes de Chrome 120, esta función no devolvía una promesa.

Parámetros

Muestra

  • Chrome 100 y versiones posteriores del navegador* desde Chrome 148

Eventos

onJobStatusChanged

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

Es el evento que se activa cuando cambia el estado del trabajo. Esto solo se activa para los trabajos que crea esta extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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