Descripción
Usa la API de chrome.printing
para enviar trabajos de impresión a las impresoras instaladas en la Chromebook.
Permisos
printing
Disponibilidad
Manifest
Todos los métodos y eventos chrome.printing
requieren que declares el permiso "printing"
en el manifiesto de extensión. Por ejemplo:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Ejemplos
En los siguientes ejemplos, se demuestra el uso de cada uno de los métodos en el espacio de nombres de impresión. Este código se copia del repositorio api-samples/printing o se basa en ellos, en el repositorio de GitHub extensions-samples.
cancelJob()
En este ejemplo, se usa el controlador onJobStatusChanged
para ocultar un botón "cancelar" cuando jobStatus
no es PENDING
ni IN_PROGRESS
. Ten en cuenta que, en algunas redes o cuando una Chromebook se conecta directamente a la impresora, es posible que estos estados pasen demasiado rápido como para que el botón Cancelar sea visible durante el tiempo suficiente para llamarlo. Este es un ejemplo de impresión muy 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()
Se usa un solo ejemplo para estas funciones porque para obtener la información de la impresora se requiere un ID de impresora, que se recupera llamando a getPrinters()
. En este ejemplo, se registra 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 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()
El método submitJob()
requiere tres elementos.
- Una estructura
ticket
que especifica qué capacidades de la impresora se usarán. Si el usuario necesita seleccionar entre las funciones disponibles, puedes recuperarlas para una impresora específica mediantegetPrinterInfo()
. - Una estructura
SubmitJobRequest
, que especifica la impresora que se usará y el archivo o la fecha que se imprimirá. Esta estructura contiene una referencia a la estructuraticket
. - Es un BLOB del archivo o los datos para imprimir.
La llamada a submitJob()
activa un cuadro de diálogo en el que se le solicita al usuario que confirme la impresión. Usa PrintingAPIExtensionsAllowlist
para omitir la confirmación.
Esta es una versión simplificada del ejemplo de impresión. Ten en cuenta que ticket
se adjunta a la estructura SubmitJobRequest
(línea 8) y que los datos para imprimir se convierten en un BLOB (línea 10). Obtener el ID de la impresora (línea 1) es más complicado en la muestra que 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'
});
}
};
chrome.printing.submitJob(submitJobRequest, (response) => {
if (response !== undefined) {
console.log(response.status);
}
if (chrome.runtime.lastError !== undefined) {
console.log(chrome.runtime.lastError.message);
}
});
Impresión en rollo
En este ejemplo, se muestra cómo crear un ticket de impresora para la impresión continua (o en rollo), que a menudo se usa con la impresión de recibos. El objeto submitJobRequest
para la impresión por rollo es el mismo que se muestra en el ejemplo submitJob()
.
Si necesitas cambiar el valor predeterminado para el corte de papel, usa la tecla vendor_ticket_item
. (La configuración predeterminada varía de una impresora a otra). Cuando se incluya, esta clave debe ser un array con un miembro: un objeto cuyo id
sea 'finishings'
. El valor puede ser 'trim'
para las impresoras que quitan el rollo al final de la impresión o 'none'
para las impresoras que requieren que se arranque 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 funciona, 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 en la clave media_size
de un ticket son específicos de cada impresora. Para seleccionar un tamaño adecuado, llama a getPrinterInfo()
. El elemento GetPrinterResponse
que se muestra contiene un array de tamaños multimedia compatibles en "media_size"."option"
. Elige una opción cuyo valor "is_continuous_feed"
sea verdadero. Usa los 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
Capacidades de las impresoras en formato CDD Es posible que falte la propiedad.
-
status
Es el estado de la impresora.
JobStatus
Estado del trabajo de impresión.
Enum
"PENDING"
El trabajo de impresión se recibe del lado de Chrome, pero todavía no se procesó.
"IN_PROGRESS"
El trabajo de impresión se envía para su impresión.
"FAILED"
Se interrumpió el trabajo de impresión debido a un error.
"CANCELED"
El usuario canceló el trabajo de impresión o mediante la API.
"PRINTED"
El trabajo de impresión se imprimió sin errores.
Printer
Propiedades
-
descripción
cadena
Es la descripción legible de la impresora.
-
id
cadena
El identificador de la impresora; se garantiza que es único entre las impresoras del dispositivo.
-
isDefault
boolean
La marca que muestra si la impresora se ajusta a las reglas de DefaultPrinterSelection. Ten en cuenta que se podrían marcar varias impresoras.
-
name
cadena
Es el nombre de la impresora.
-
recentlyUsedRank
número opcional
El valor que muestra qué tan reciente se usó la impresora para imprimir desde Chrome. Cuanto más bajo sea el valor, más reciente será que se haya usado la impresora. El valor mínimo es 0. Si falta un valor, significa que la impresora no se usó recientemente. Se garantiza que este valor sea único entre las impresoras.
-
source
La fuente de la impresora (usuario o política configurado).
-
uri
cadena
El URI de la impresora. Esto se puede usar con extensiones para elegir la impresora para el usuario.
PrinterSource
La fuente de la impresora.
Enum
"USER"
El usuario agregó la impresora.
"POLICY"
Se agregó la impresora mediante la política.
PrinterStatus
Es el estado de la impresora.
Enum
"DOOR_OPEN"
La puerta de la impresora está abierta. La impresora seguirá aceptando trabajos de impresión.
"TRAY_MISSING"
Falta la bandeja de la impresora. La impresora seguirá aceptando trabajos de impresión.
"OUT_OF_INK"
La impresora no tiene tinta. La impresora seguirá aceptando trabajos de impresión.
"OUT_OF_PAPER"
La impresora no tiene papel. La impresora seguirá aceptando trabajos de impresión.
"OUTPUT_FULL"
La zona de salida de la impresora (p.ej., la bandeja) está llena. La impresora seguirá aceptando trabajos de impresión.
"PAPER_JAM"
La impresora tiene papel atascado. La impresora seguirá aceptando trabajos de impresión.
"GENERIC_ISSUE"
Hay un problema genérico. La impresora seguirá 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 está vencido. La impresora acepta trabajos, pero estos fallan.
"AVAILABLE"
La impresora está disponible.
SubmitJobRequest
Propiedades
-
trabajo
El trabajo de impresión que se enviará. El único tipo de contenido admitido es "application/pdf" y el Cloud Job Ticket no debe incluir los campos
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
niVendorTicketItem
, ya que son irrelevantes para la impresión nativa. Todos los demás campos deben estar presentes.
SubmitJobResponse
Propiedades
-
jobId
cadena opcional
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.
-
status
Estado de la solicitud.
SubmitJobStatus
Estado de la solicitud submitJob
.
Enum
"OK"
Se acepta la solicitud de trabajo de impresión enviada.
"USER_REJECTED"
El usuario rechaza la solicitud de trabajo de impresión enviada.
Propiedades
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
La cantidad máxima de veces por minuto que se puede llamar a getPrinterInfo
.
Valor
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
La cantidad máxima de veces por minuto que se puede llamar a submitJob
.
Valor
40
Métodos
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Cancela el trabajo enviado con anterioridad.
Parámetros
-
jobId
cadena
El ID del trabajo de impresión que se cancelará. Debe ser el mismo ID recibido en un
SubmitJobResponse
. -
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 100 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Muestra el estado y las capacidades de la impresora en formato CDD. Esta llamada fallará y mostrará un error de tiempo de ejecución si no se instala ninguna impresora con ese ID.
Parámetros
-
printerId
cadena
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(response: GetPrinterInfoResponse) => void
-
respuesta
-
Devuelve
-
Promise<GetPrinterInfoResponse>
Chrome 100 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Muestra la lista de impresoras disponibles en el dispositivo. Esto incluye las impresoras agregadas manualmente, las empresariales y descubiertas.
Parámetros
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(printers: Printer[]) => void
-
impresoras
-
Devuelve
-
Promesa<Impresora[]>
Chrome 100 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Envía el trabajo de impresión. Si la extensión no aparece en la política PrintingAPIExtensionsAllowlist
, se le solicitará al usuario que acepte el trabajo de impresión.
Antes de Chrome 120, esta función no mostraba ninguna promesa.
Parámetros
-
request
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(response: SubmitJobResponse) => void
-
respuesta
-
Devuelve
-
Promise<SubmitJobResponse>
Chrome 100 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
Eventos
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
El evento se activa cuando cambia el estado del trabajo. Solo se activa para los trabajos que crea esta extensión.