Descripción
Usa la API de chrome.printing
para enviar trabajos de impresión a las impresoras instaladas en la Chromebook.
Permisos
printing
Disponibilidad
Todos los métodos y eventos de 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 desde api-samples/printing, o se basa en esta, en el repositorio de GitHub extensions-samples.
cancelJob()
En este ejemplo, se usa el controlador onJobStatusChanged
para ocultar un elemento "cancel" cuando el jobStatus
no es PENDING
ni IN_PROGRESS
. Ten en cuenta que en algunas redes o cuando una Chromebook se conecta directamente a la impresora, estos estados pueden pasar demasiado rápido para que el botón Cancelar esté 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 la obtención de información de la impresora requiere un ID de impresora, que se recupera llamando a getPrinters()
. Este ejemplo 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 cosas.
- Una estructura
ticket
que especifica qué capacidades de la impresora se deben usar. Si el usuario necesita seleccionar entre las funciones disponibles, puedes recuperarlas para una impresora específica congetPrinterInfo()
. - 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
. - Un BLOB del archivo o los datos que se imprimirán.
Llamar a submitJob()
activa un cuadro de diálogo que 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
está adjunto 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 el ejemplo 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'
});
}
};
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 imprimir de forma continua (o en rollo), que a menudo se usa con la impresión de recibos. El objeto submitJobRequest
para la impresión de 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 tecla vendor_ticket_item
. (La configuración predeterminada varía de una impresora a otra). 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 quite 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 muestra contiene un array de tamaños de contenido multimedia compatibles en "media_size"."option"
. Elige una opción cuyo valor "is_continuous_feed"
sea verdadero. Usa sus valores de altura y ancho para la entrada.
"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
Funciones de la impresora en formato CDD. Es posible que falte la propiedad.
-
estado
El estado de la impresora.
JobStatus
Estado del trabajo de impresión.
Enum
"PENDING"
Se recibió el trabajo de impresión en Chrome, pero aún no se procesó.
"IN_PROGRESS"
El trabajo de impresión se envió a imprimir.
"ERROR"
Se interrumpió el trabajo de impresión debido a un error.
"CANCELED"
El usuario o la API canceló el trabajo de impresión.
"PRINTED"
El trabajo de impresión se imprimió sin errores.
Printer
Propiedades
-
descripción
string
Es una descripción legible de la impresora.
-
id
string
El identificador de la impresora. garantizadas sean únicas entre las impresoras del dispositivo.
-
isDefault
boolean
La marca que muestra si la impresora cumple con las reglas de DefaultPrinterSelection. Ten en cuenta que podrían estar marcadas varias impresoras.
-
nombre
string
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á el uso de la impresora. El valor mínimo es 0. Un valor faltante indica que la impresora no se usó recientemente. Se garantiza que este valor es único entre las impresoras.
-
source
La fuente de la impresora (usuario o política configurados)
-
uri
string
El URI de la impresora. Las extensiones pueden usar esta opción para elegir la impresora para el usuario.
PrinterSource
Es la fuente de la impresora.
Enum
"USER"
El usuario agregó la impresora.
"POLICY"
La impresora se agregó mediante la política.
PrinterStatus
El estado de la impresora.
Enum
"DOOR_OPEN"
La puerta de la impresora está abierta. La impresora aún acepta trabajos de impresión.
"TRAY_MISSING"
Falta la bandeja de la impresora. La impresora aún acepta trabajos de impresión.
"OUT_OF_INK"
La impresora se quedó sin tinta. La impresora aún acepta trabajos de impresión.
"OUT_OF_PAPER"
La impresora no tiene papel. La impresora aún acepta trabajos de impresión.
"OUTPUT_FULL"
El área de salida de la impresora (p.ej., la bandeja) está llena. La impresora aún acepta trabajos de impresión.
"PAPER_JAM"
La impresora está atascada de papel. La impresora aún acepta trabajos de impresión.
"GENERIC_ISSUE"
Hubo un problema genérico. La impresora aún acepta trabajos de impresión.
"STOPPED"
La impresora está detenida y no imprime, pero aún acepta 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 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 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
-
ID de tarea
string opcional
El ID del trabajo de impresión creado. Es un identificador único entre todos los trabajos de impresión del dispositivo. Si el estado no es OK, jobId será nulo.
-
estado
El estado de la solicitud.
SubmitJobStatus
El estado de la solicitud submitJob
.
Enum
"OK"
Se aceptó la solicitud de trabajo de impresión enviado.
"USER_REJECTED"
El usuario rechazó la solicitud de trabajo de impresión enviada.
Propiedades
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
La cantidad máxima de veces que se puede llamar a getPrinterInfo
por minuto.
Valor
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
La cantidad máxima de veces que se puede llamar a submitJob
por minuto.
Valor
40
Métodos
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Cancela el trabajo enviado anteriormente.
Parámetros
-
ID de tarea
string
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
Muestra
-
Promesa<void>
Chrome 100 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución 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 instalan impresoras con ese ID.
Parámetros
-
printerId
string
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(response: GetPrinterInfoResponse) => void
-
respuesta
-
Muestra
-
Promise<GetPrinterInfoResponse>
Chrome 100 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Muestra la lista de impresoras disponibles en el dispositivo. Esto incluye las impresoras que se agregaron manualmente, las empresariales y las descubiertas.
Parámetros
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(printers: Printer[]) => void
-
impresoras
-
Muestra
-
Promesa<Impresora[]>
Chrome 100 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Envía el trabajo para imprimirlo. 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
-
Muestra
-
Promise<SubmitJobResponse>
Chrome 100 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
Eventos
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
El evento se activa cuando cambia el estado del trabajo. Esto solo se activa para los trabajos que crea esta extensión.