chrome.printing

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.printing per inviare processi di stampa alle stampanti installate su Chromebook.

Autorizzazioni

printing

Disponibilità

Chrome 81 e versioni successive Solo ChromeOS

Manifest

Tutti i metodi e gli eventi chrome.printing richiedono la dichiarazione dell'autorizzazione "printing" nel manifest dell'estensione. Ad esempio:

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

Esempi

Gli esempi riportati di seguito mostrano l'utilizzo di ciascuno dei metodi nello spazio dei nomi di stampa. Questo codice è copiato o basato su api-samples/printing nel repository GitHub extensions-samples.

cancelJob()

Questo esempio utilizza 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 rapidamente perché il pulsante di annullamento sia visibile abbastanza a lungo 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(). Questo esempio registra il nome e la descrizione della stampante predefinita 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 elementi.

  • Una struttura ticket che specifica quali funzionalità della stampante devono essere utilizzate. Se l'utente deve selezionare tra le funzionalità disponibili, puoi recuperarle per una stampante specifica utilizzando getPrinterInfo().
  • Una struttura SubmitJobRequest, che specifica la stampante da utilizzare e il file o la data da stampare. Questa struttura contiene un riferimento alla struttura ticket.
  • 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 PrintingAPIExtensionsAllowlist per bypassare la conferma.

Questa è una versione semplificata dell'esempio di stampa. Tieni presente 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 quanto 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 su rotolo

Questo esempio mostra come creare un ticket di stampa per la stampa continua (o su rotolo), spesso utilizzata per la stampa di scontrini. L'oggetto submitJobRequest per la stampa su rotolo è lo stesso mostrato per l'esempio submitJob().

Se devi modificare il valore predefinito per il taglio della carta, utilizza il tasto vendor_ticket_item. (L'impostazione predefinita varia da stampante a stampante). Se inclusa, questa chiave deve essere un array con un membro: un oggetto il cui id è 'finishings'. Il valore può essere 'trim' per le stampanti che tagliano il rotolo al termine della stampa o 'none' per le stampanti che richiedono lo strappo 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 determinare se la tua stampante lo fa, 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(). L'oggetto GetPrinterResponse restituito contiene un array di dimensioni dei supporti supportate in "media_size"."option". Scegli un'opzione il cui valore "is_continuous_feed" è true. Utilizza i valori di altezza e larghezza per il biglietto.

"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

    object facoltativo

    Funzionalità della stampante in formato CDD. La proprietà potrebbe non essere presente.

  • Lo stato della stampante.

JobStatus

Stato del processo di stampa.

Enum

"PENDING"
Il processo di stampa è stato ricevuto da 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.

"CANCELED"
Il processo di stampa è stato annullato dall'utente o tramite API.

"PRINTED"
Il processo di stampa è stato stampato senza errori.

Printer

Proprietà

  • descrizione

    stringa

    La descrizione della stampante leggibile da una persona.

  • id

    stringa

    L'identificatore della stampante, che è garantito essere univoco tra le stampanti sul dispositivo.

  • isDefault

    booleano

    Il flag che indica se la stampante è conforme alle regole DefaultPrinterSelection. Tieni presente che potrebbero essere segnalate più stampanti.

  • nome

    stringa

    Il nome della stampante.

  • recentlyUsedRank

    number optional

    Il valore che indica quanto di recente la stampante è stata utilizzata per la stampa da Chrome. Più basso è il valore, più recente è l'utilizzo della stampante. Il valore minimo è 0. Un valore mancante indica che la stampante non è stata utilizzata di recente. Questo valore è garantito come univoco tra le stampanti.

  • origine

    PrinterSource

    L'origine della stampante (configurata dall'utente o dalla policy).

  • 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 policy.

PrinterStatus

Lo stato della stampante.

Enum

"DOOR_OPEN"
Lo sportello della stampante è aperto. La stampante accetta comunque i processi di stampa.

"TRAY_MISSING"
Il vassoio della stampante non è presente. La stampante accetta comunque i processi di stampa.

"OUT_OF_INK"
La stampante ha esaurito l'inchiostro. La stampante accetta comunque i processi di stampa.

"OUT_OF_PAPER"
La stampante ha esaurito la carta. La stampante accetta comunque i processi di stampa.

"OUTPUT_FULL"
L'area di uscita della stampante (ad es. il vassoio) è piena. La stampante accetta comunque i processi di stampa.

"PAPER_JAM"
La stampante ha un inceppamento della carta. La stampante accetta comunque i processi di stampa.

"GENERIC_ISSUE"
Un problema generico. La stampante accetta comunque i processi di stampa.

"STOPPED"
La stampante è stata arrestata e non stampa, ma accetta comunque i processi di stampa.

"UNREACHABLE"
La stampante non è raggiungibile e non accetta processi di stampa.

"EXPIRED_CERTIFICATE"
Il certificato SSL è scaduto. La stampante accetta i processi, ma non li esegue.

"AVAILABLE"
La stampante è disponibile.

SubmitJobRequest

Proprietà

  • job

    PrintJob

    Il processo di stampa da inviare. I tipi di contenuti supportati sono "application/pdf" e "image/png". Il Cloud Job Ticket non deve includere i campi FitToPageTicketItem, PageRangeTicketItem e ReverseOrderTicketItem, poiché non sono pertinenti per la stampa nativa. VendorTicketItem è facoltativo. Tutti gli altri campi devono essere presenti.

SubmitJobResponse

Proprietà

  • jobId

    stringa facoltativa

    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.

  • Lo stato della richiesta.

SubmitJobStatus

Lo stato della richiesta di submitJob.

Enum

"OK"
La richiesta di invio del processo di stampa è stata accettata.

"USER_REJECTED"
La richiesta di job di stampa inviata è stata rifiutata dall'utente.

Proprietà

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Il numero massimo di volte in cui getPrinterInfo può essere chiamato al minuto.

Valore

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Il numero massimo di volte in cui submitJob può essere chiamato al minuto.

Valore

40

Metodi

cancelJob()

Promise 
chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
): Promise<void>

Annulla il job inviato in precedenza.

Parametri

  • jobId

    stringa

    L'ID del processo di stampa da annullare. Deve essere lo stesso ID ricevuto in un SubmitJobResponse.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 100+

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getJobStatus()

Promise Chrome 135+ 
chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
): Promise<JobStatus>

Restituisce lo stato del processo di stampa. Questa chiamata non andrà a buon fine con un errore di runtime se il processo di stampa con l'ID jobId specificato non esiste. jobId: l'ID del processo di stampa di cui restituire lo stato. Deve essere lo stesso ID ricevuto in un SubmitJobResponse.

Parametri

  • jobId

    stringa

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (status: JobStatus) => void

Resi

  • Promise<JobStatus>

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getPrinterInfo()

Promise 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
): Promise<GetPrinterInfoResponse>

Restituisce lo stato e le funzionalità della stampante in formato CDD. Questa chiamata non andrà a buon fine con un errore di runtime se non sono installate stampanti con l'ID specificato.

Parametri

Resi

  • Chrome 100+

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getPrinters()

Promise 
chrome.printing.getPrinters(
  callback?: function,
): Promise<Printer[]>

Restituisce l'elenco delle stampanti disponibili sul dispositivo. Sono incluse le stampanti aggiunte manualmente, aziendali e rilevate.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (printers: Printer[]) => void

Resi

  • Promise<Printer[]>

    Chrome 100+

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

submitJob()

Promise 
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
): Promise<SubmitJobResponse>

Invia il job per la stampa. Se l'estensione non è elencata nella policy PrintingAPIExtensionsAllowlist, all'utente viene chiesto di accettare il processo di stampa. Prima di Chrome 120, questa funzione non restituiva una promise.

Parametri

Resi

  • Chrome 100+

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onJobStatusChanged

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

Evento attivato quando lo stato del job viene modificato. Viene attivato solo per i job creati da questa estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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