Descrizione
Usa l'API chrome.printing
per inviare processi di stampa alle stampanti installate su Chromebook.
Autorizzazioni
printing
Disponibilità
Tutti i metodi e gli eventi chrome.printing
richiedono di dichiarare l'autorizzazione "printing"
nel manifest delle estensioni. Ad esempio:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Esempi
Gli esempi riportati di seguito mostrano l'utilizzo di ciascuno dei metodi dello spazio dei nomi di stampa. Questo codice viene copiato o basato su api-samples/printing nel repository GitHub di Extensions-samples.
cancelJob()
In questo esempio viene utilizzato il gestore onJobStatusChanged
per nascondere un pulsante "Annulla" quando jobStatus
non è né PENDING
né IN_PROGRESS
. Tieni presente che su alcune reti o quando un Chromebook è collegato direttamente alla stampante, questi stati potrebbero passare troppo velocemente perché il pulsante Annulla diventi visibile per un tempo sufficiente da essere chiamato. Questo è un esempio di stampa molto semplificato.
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()
Per queste funzioni viene utilizzato un singolo esempio perché per ottenere le informazioni sulla stampante è necessario un ID stampante, che viene recuperato chiamando getPrinters()
. In questo esempio il nome e la descrizione della stampante predefinita vengono registrati nella console. Questa è una versione semplificata dell'esempio di stampa.
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()
Il metodo submitJob()
richiede tre passaggi.
- Una struttura
ticket
che specifica quali funzionalità della stampante utilizzare. Se l'utente deve selezionare le funzionalità disponibili, puoi recuperarle per una stampante specifica utilizzandogetPrinterInfo()
. - Una struttura
SubmitJobRequest
, che specifica la stampante da utilizzare e il file o la data da stampare. Questa struttura contiene un riferimento alla strutturaticket
. - Un blob del file o dei dati da stampare.
La chiamata a submitJob()
attiva una finestra di dialogo che chiede all'utente di confermare la stampa. Utilizza il PrintingAPIExtensionsAllowlist
per ignorare la conferma.
Questa è una versione semplificata dell'esempio di stampa. Nota che ticket
è collegato alla struttura SubmitJobRequest
(riga 8) e che i dati da stampare vengono convertiti in un blob (riga 10). Ottenere l'ID della stampante (riga 1) è più complicato nell'esempio rispetto a quello mostrato qui.
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);
}
});
Stampa in rotolo
Questo esempio mostra come creare un ticket stampante per la stampa continua (o in rotolo), che viene spesso utilizzata con la stampa di ricevute. L'oggetto submitJobRequest
per la stampa in rotolo è uguale a quello mostrato nell'esempio submitJob()
.
Se devi modificare il valore predefinito per il taglio della carta, utilizza la chiave vendor_ticket_item
. L'impostazione predefinita varia a seconda della stampante. Per modificare il valore, fornisci un array con un membro: un oggetto il cui id
è 'finishings'
. Il valore può essere 'trim'
per le stampanti che tagliano il rullo alla fine della stampa o 'none'
per le stampanti che richiedono la rimozione del processo di stampa.
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}
}
};
Alcune stampanti non supportano l'opzione "finishings"
. Per stabilire se la tua stampante funziona, chiama il numero getPrinterInfo()
e cerca un "display_name"
di "finishings/11"
.
"vendor_capability": [
{
"display_name": "finishings/11",
"id": "finishings/11",
"type": "TYPED_VALUE",
"typed_value_cap": {
"value_type": "BOOLEAN"
}
},
...
]
I valori nella chiave media_size
di un ticket sono specifici per ogni stampante. Per selezionare una dimensione appropriata, chiama getPrinterInfo()
. Il valore GetPrinterResponse
restituito contiene un array di dimensioni dei contenuti multimediali supportate nel formato "media_size"."option"
. Scegli un'opzione il cui valore "is_continuous_feed"
sia true. Utilizza i relativi valori di altezza e larghezza per il ticket.
"media_size": {
"option": [
{
"custom_display_name": "",
"is_continuous_feed": true,
"max_height_microns": 2000000,
"min_height_microns": 25400,
"width_microns": 50800
},
...
]
}
Tipi
GetPrinterInfoResponse
Proprietà
-
capabilities
oggetto facoltativo
Funzionalità della stampante in formato CDD. La proprietà potrebbe non essere presente.
-
status
Lo stato della stampante.
JobStatus
Stato del processo di stampa.
Enum
"IN ATTESA"
Il processo di stampa è stato ricevuto sul lato Chrome, ma non è stato ancora elaborato.
"IN_PROGRESS"
Il processo di stampa è stato inviato per la stampa.
"FAILED"
Il processo di stampa è stato interrotto a causa di un errore.
"ANNULLATO"
Il processo di stampa è stato annullato dall'utente o tramite API.
"STAMPATO"
Il processo di stampa è stato stampato senza errori.
Printer
Proprietà
-
descrizione
stringa
La descrizione leggibile della stampante.
-
id
stringa
Identificatore della stampante; deve essere univoco tra le stampanti del dispositivo.
-
isDefault
boolean
Il flag che mostra se la stampante è conforme alle regole DefaultPrinterSelection. Tieni presente che potrebbero essere state segnalate diverse stampanti.
-
nome
stringa
Il nome della stampante.
-
recentlyUsedRank
numero facoltativo
Il valore che indica da quanto tempo è stata utilizzata la stampante per la stampa da Chrome. Più basso è il valore, più recente è stata utilizzata la stampante. Il valore minimo è 0. Un valore mancante indica che la stampante non è stata utilizzata di recente. Questo valore garantisce che sia univoco tra le stampanti.
-
source
L'origine della stampante (utente o criterio configurato).
-
uri
stringa
L'URI della stampante. Questa opzione può essere utilizzata dalle estensioni per scegliere la stampante per l'utente.
PrinterSource
L'origine della stampante.
Enum
"USER"
La stampante è stata aggiunta dall'utente.
"POLICY"
La stampante è stata aggiunta tramite le norme.
PrinterStatus
Lo stato della stampante.
Enum
"DOOR_OPEN"
Lo sportello della stampante è aperto. La stampante accetta comunque i processi di stampa.
"TRAY_MISSING"
Vassoio della stampante mancante. La stampante accetta comunque i processi di stampa.
"OUT_OF_INK"
La stampante ha finito l'inchiostro. La stampante accetta comunque i processi di stampa.
"OUT_OF_PAPER"
La carta della stampante è esaurita. La stampante accetta comunque i processi di stampa.
"OUTPUT_FULL"
L'area di uscita della stampante (ad esempio il vassoio) è piena. La stampante accetta comunque i processi di stampa.
"PAPER_JAM"
La stampante presenta un inceppamento carta. La stampante accetta comunque i processi di stampa.
"GENERIC_ISSUE"
Un problema generico. La stampante accetta comunque i processi di stampa.
"INTERROTTA"
La stampante è stata arrestata e non stampa, ma accetta comunque i processi di stampa.
"NON RAGGIUNGIBILE"
La stampante non è raggiungibile e non accetta processi di stampa.
"EXPIRED_CERTIFICATE"
Il certificato SSL è scaduto. La stampante accetta i processi, ma non riescono.
"AVAILABLE"
La stampante è disponibile.
SubmitJobRequest
Proprietà
-
job
Il processo di stampa da inviare. L'unico tipo di contenuto supportato è"application/pdf" e Cloud Job Ticket non deve includere i campi
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
eVendorTicketItem
poiché non sono pertinenti per la stampa nativa. Devono essere presenti tutti gli altri campi.
SubmitJobResponse
Proprietà
-
jobId
stringa facoltativo
L'ID del processo di stampa creato. Si tratta di un identificatore univoco tra tutti i processi di stampa sul dispositivo. Se lo stato non è OK, jobId sarà null.
-
status
Lo stato della richiesta.
SubmitJobStatus
Lo stato della richiesta submitJob
.
Enum
"OK"
La richiesta di processo di stampa inviata è accettata.
"USER_REJECTED"
La richiesta di processo di stampa inviato è stata rifiutata dall'utente.
Proprietà
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
Il numero massimo di chiamate di getPrinterInfo
al minuto.
Valore
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
Il numero massimo di chiamate di submitJob
al minuto.
Valore
40
Metodi
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Annulla il job inviato in precedenza.
Parametri
-
jobId
stringa
L'ID del processo di stampa da annullare. Deve essere lo stesso ID ricevuto in una
SubmitJobResponse
. -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 100 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Restituisce lo stato e le funzionalità della stampante in formato CDD. Questa chiamata avrà esito negativo con un errore di runtime se non sono installate stampanti con l'ID specificato.
Parametri
-
printerId
stringa
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(response: GetPrinterInfoResponse) => void
-
risposta
-
Ritorni
-
Promise<GetPrinterInfoResponse>
Chrome 100 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Restituisce l'elenco delle stampanti disponibili sul dispositivo. Sono incluse le stampanti aggiunte manualmente, aziendali e rilevate.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(printers: Printer[]) => void
-
stampanti
-
Ritorni
-
Promessa<Stampante[]>
Chrome 100 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Invia il processo per la stampa. Se l'estensione non è presente nell'elenco dei criteri PrintingAPIExtensionsAllowlist
, all'utente viene chiesto di accettare il processo di stampa.
Prima di Chrome 120, questa funzione non ha restituito una promessa.
Parametri
-
richiesta
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(response: SubmitJobResponse) => void
-
risposta
-
Ritorni
-
Promise<SubmitJobResponse>
Chrome 100 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
Eventi
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
L'evento viene attivato quando lo stato del job viene modificato. Viene attivato solo per i job creati da questa estensione.