chrome.printing

Importante: questa API funziona solo su ChromeOS.

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

Tutti i metodi ed eventi chrome.printing richiedono di dichiarare l'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 da o basato su api-samples/printing nel repository GitHub di extensions-samples.

cancelJob()

Questo esempio utilizza l'handler onJobStatusChanged per nascondere un pulsante "Annulla" quando jobStatus non è PENDING o 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 Annulla sia visibile per il tempo sufficiente per 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 una delle 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.

L'attivazione di submitJob() attiva una finestra di dialogo che chiede all'utente di confermare la stampa. Usa PrintingAPIExtensionsAllowlist per saltare la conferma.

Questa è una versione semplificata dell'esempio di stampa. Tieni presente che ticket è associato alla struttura SubmitJobRequest (riga 8) e che i dati da stampare vengono convertiti in un blob (riga 10). L'ottenimento dell'ID della stampante (riga 1) è più complicato nel sample 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 della stampante per la stampa continua (o in rotolo), che viene spesso utilizzata per la stampa delle ricevute. L'oggetto submitJobRequest per la stampa in 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. Il valore predefinito varia da una stampante all'altra. 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 rotolo alla fine della stampa o 'none' per le stampanti che richiedono di staccare il 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 sapere se la tua stampante supporta questa funzionalità, chiama 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"
    }
  },
  ...
]

Nota: a partire da Chrome 124, vendor_ticket_item consente tutti gli elementi di vendor_capabilities della stampante. Ad esempio, qualsiasi valore restituito da getPrinterInfo() è valido. In precedenza, era supportata solo la chiave finishings.

I valori nella chiave media_size di un ticket sono specifici per ogni stampante. Per selezionare una taglia appropriata, chiama getPrinterInfo(). Il valore GetPrinterResponse restituito contiene un array di dimensioni dei contenuti multimediali 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

  Oggetto facoltativo

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

• stato

  PrinterStatus

  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 job di stampa viene inviato per la stampa.

"NON RIUSCITO"
Il processo di stampa è stato interrotto a causa di un errore.

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

"STAMPATO"
Il job di stampa è stato stampato senza errori.

Printer

Proprietà

• descrizione

  stringa

  La descrizione leggibile della stampante.

• id

  stringa

  L'identificatore della stampante, garantito come univoco tra le stampanti sul dispositivo.

• isDefault

  booleano

  Il flag che indica se la stampante soddisfa le regole di DefaultPrinterSelection. Tieni presente che potrebbero essere segnalate diverse stampanti.

• nome

  stringa

  Il nome della stampante.

• recentlyUsedRank

  number facoltativo

  Il valore che indica quanto di recente è 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 è garantito come univoco tra le stampanti.

• origine

  PrinterSource

  L'origine della stampante (utente o criterio configurato).

• uri

  stringa

  L'URI della stampante. Questo valore può essere utilizzato dalle estensioni per scegliere la stampante per l'utente.

PrinterSource

L'origine della stampante.

Enum

"USER"
La stampante è stata aggiunta dall'utente.

"NORME"
La stampante è stata aggiunta tramite le norme.

PrinterStatus

Lo stato della stampante.

Enum

"DOOR_OPEN"
Lo sportello della stampante è aperto. La stampante continua ad accettare i processi di stampa.

"TRAY_MISSING"
Manca il vassoio della stampante. La stampante continua ad accettare i processi di stampa.

"OUT_OF_INK"
L'inchiostro della stampante è esaurito. La stampante continua ad accettare i processi di stampa.

"OUT_OF_PAPER"
La stampante ha esaurito la carta. La stampante continua ad accettare i processi di stampa.

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

"PAPER_JAM"
La stampante ha un foglio inceppato. La stampante continua ad accettare i processi di stampa.

"GENERIC_ISSUE"
Qualche problema generico. La stampante continua ad accettare i processi di stampa.

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

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

"EXPIRED_CERTIFICATE"
Il certificato SSL è scaduto. La stampante accetta i lavori, ma non riescono a essere completati.

"DISPONIBILE"
La stampante è disponibile.

SubmitJobRequest

Proprietà

• job

  PrintJob

  Il processo di stampa da inviare. L'unico tipo di contenuto supportato è"application/pdf" e il ticket di lavoro Cloud non deve includere i campi FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem e VendorTicketItem perché non sono pertinenti per la stampa nativa. 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 tutte le stampe sul dispositivo. Se lo stato non è OK, jobId sarà nullo.

• stato

  SubmitJobStatus

  Lo stato della richiesta.

SubmitJobStatus

Lo stato della richiesta submitJob.

Enum

"Ok"
La richiesta di processo di stampa inviata è stata accettata.

"USER_REJECTED"
La richiesta 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()

Promessa

chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
)

Annullamento del 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

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 100 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getJobStatus()

Promessa In attesa

chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
)

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 il valore 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

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (status: JobStatus) => void

  • stato

    JobStatus

Resi

• Promise<JobStatus>

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getPrinterInfo()

Promessa

chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

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

• printerId

  stringa

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (response: GetPrinterInfoResponse) => void

  • risposta

    GetPrinterInfoResponse

Resi

• Promise<GetPrinterInfoResponse>

  Chrome 100 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getPrinters()

Promessa

chrome.printing.getPrinters(
  callback?: function,
)

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

Parametri

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (printers: Printer[]) => void

  • stampanti

    Stampante[]

Resi

• Promise<Stampante[]>

  Chrome 100 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

submitJob()

Promessa

chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

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

Parametri

• richiesta

  SubmitJobRequest

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (response: SubmitJobResponse) => void

  • risposta

    SubmitJobResponse

Resi

• Promise<SubmitJobResponse>

  Chrome 100 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al 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

  • jobId

    stringa

  • stato

    JobStatus