chrome.printing

Beschreibung

Mit der chrome.printing API können Sie Druckaufträge an Drucker senden, die auf Chromebook installiert sind.

Berechtigungen

printing

Verfügbarkeit

Chrome (ab Version 81) Nur ChromeOS

Manifest

Für alle chrome.printing-Methoden und chrome.printing-Ereignisse müssen Sie die Berechtigung "printing" im Manifest der Erweiterung angeben. Beispiel:

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

Beispiele

Die folgenden Beispiele zeigen die Verwendung der einzelnen Methoden im Druck-Namespace. Dieser Code wurde aus api-samples/printing im GitHub-Repository „extensions-samples“ kopiert oder basiert darauf.

cancelJob()

In diesem Beispiel wird der onJobStatusChanged-Handler verwendet, um eine Schaltfläche „Abbrechen“ auszublenden, wenn jobStatus weder PENDING noch IN_PROGRESS ist. Beachten Sie, dass diese Status in einigen Netzwerken oder wenn ein Chromebook direkt mit dem Drucker verbunden ist, möglicherweise zu schnell übergeben wird, sodass die Schaltfläche zum Abbrechen nicht lange genug angezeigt wird, um aufgerufen zu werden. Dies ist ein stark vereinfachtes Druckbeispiel.

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()

Für diese Funktionen wird nur ein Beispiel verwendet, da zum Abrufen von Druckerinformationen eine Drucker-ID erforderlich ist, die durch Aufrufen von getPrinters() abgerufen wird. In diesem Beispiel werden der Name und die Beschreibung des Standarddruckers in der Konsole protokolliert. Dies ist eine vereinfachte Version des Druckbeispiels.

​​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()

Für die Methode submitJob() sind drei Dinge erforderlich.

  • Eine ticket-Struktur, die angibt, welche Funktionen des Druckers verwendet werden sollen. Wenn der Nutzer eine Auswahl aus den verfügbaren Funktionen treffen muss, können Sie sie für einen bestimmten Drucker mit getPrinterInfo() abrufen.
  • Eine SubmitJobRequest-Struktur, die den zu verwendenden Drucker und die Datei oder das Datum angibt, die bzw. das gedruckt werden soll. Diese Struktur enthält einen Verweis auf die Struktur ticket.
  • Ein Blob der Datei oder Daten, die gedruckt werden sollen.

Durch den Aufruf von submitJob() wird ein Dialogfeld ausgelöst, in dem der Nutzer aufgefordert wird, den Druckvorgang zu bestätigen. Mit PrintingAPIExtensionsAllowlist können Sie die Bestätigung überspringen.

Dies ist eine vereinfachte Version des Druckbeispiels. Beachten Sie, dass ticket an die SubmitJobRequest-Struktur (Zeile 8) angehängt ist und die zu druckenden Daten in ein Blob (Zeile 10) konvertiert werden. Im Beispiel ist es komplizierter, die ID des Druckers (Zeile 1) zu ermitteln, als hier gezeigt wird.

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);
  }
});

Rollendruck

In diesem Beispiel wird gezeigt, wie Sie ein Druckerticket für den kontinuierlichen (Rollen-)Druck erstellen, der häufig beim Drucken von Belegen verwendet wird. Das submitJobRequest-Objekt für den Rollendruck ist mit dem für das Beispiel submitJob() identisch.

Wenn Sie den Standardwert für das Ausschneiden auf Papier ändern möchten, verwenden Sie die Taste vendor_ticket_item. Die Standardeinstellung unterscheidet sich von Drucker zu Drucker. Wenn dieser Schlüssel enthalten ist, muss er ein Array mit einem Mitglied sein: ein Objekt, dessen id 'finishings' ist. Der Wert kann entweder 'trim' für Drucker sein, die die Rolle am Ende des Druckens abschneiden, oder 'none' für Drucker, bei denen der Druckauftrag abgerissen werden muss.

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}
  }
};

Einige Drucker unterstützen die Option "finishings" nicht. Wenn Sie wissen möchten, ob Ihr Drucker diese Funktion unterstützt, rufen Sie getPrinterInfo() auf und suchen Sie nach einem "display_name" von "finishings/11".

"vendor_capability": [
  {
    "display_name": "finishings/11",
    "id": "finishings/11",
    "type": "TYPED_VALUE",
    "typed_value_cap": {
      "value_type": "BOOLEAN"
    }
  },
  ...
]

Die Werte im Schlüssel media_size eines Tickets gelten für jeden Drucker. Um eine geeignete Größe auszuwählen, drücken Sie die Taste getPrinterInfo(). Das zurückgegebene GetPrinterResponse enthält ein Array der unterstützten Mediengrößen bei "media_size"."option". Wählen Sie eine Option aus, deren "is_continuous_feed"-Wert „wahr“ ist. Verwenden Sie die Werte für Höhe und Breite des Tickets.

"media_size": {
  "option": [
  {
    "custom_display_name": "",
    "is_continuous_feed": true,
    "max_height_microns": 2000000,
    "min_height_microns": 25400,
    "width_microns": 50800
  },
  ...
  ]
}

Typen

GetPrinterInfoResponse

Attribute

  • capabilities

    Objekt (optional)

    Druckerfunktionen im CDD-Format. Die Property fehlt möglicherweise.

  • Status

    PrinterStatus

    Der Status des Druckers.

JobStatus

Status des Druckjobs.

Enum

„AUSSTEHEND“
Der Druckauftrag wurde in Chrome empfangen, aber noch nicht verarbeitet.

"IN_PROGRESS"
Der Druckauftrag wird zum Drucken gesendet.

„FAILED“ 
Der Druckauftrag wurde aufgrund eines Fehlers unterbrochen.

"CANCELED"
Der Druckauftrag wurde vom Nutzer oder über die API abgebrochen.

„AUSGEDRUCHT“
Der Druckauftrag wurde ohne Fehler gedruckt.

Printer

Attribute

  • Beschreibung

    String

    Die visuell lesbare Beschreibung des Druckers.

  • id

    String

    Die Kennung des Druckers, die garantiert eindeutig ist.

  • isDefault

    boolean

    Gibt an, ob der Drucker den Regeln für die DefaultPrinterSelection entspricht. Beachten Sie, dass mehrere Drucker gekennzeichnet werden können.

  • name

    String

    Der Name des Druckers.

  • recentlyUsedRank

    number optional

    Der Wert, der angibt, wann zuletzt der Drucker zum Drucken über Chrome verwendet wurde. Je niedriger der Wert, desto aktueller wurde der Drucker verwendet. Der Mindestwert ist 0. Ein fehlender Wert gibt an, dass der Drucker in letzter Zeit nicht verwendet wurde. Dieser Wert ist unter den Druckern garantiert eindeutig.

  • source

    PrinterSource

    Die Quelle des Druckers (vom Nutzer oder durch eine Richtlinie konfiguriert).

  • uri

    String

    Der Drucker-URI. Erweiterungen können diese Informationen verwenden, um den Drucker für den Nutzer auszuwählen.

PrinterSource

Die Quelle des Druckers.

Enum

„USER“
Der Drucker wurde vom Nutzer hinzugefügt.

"POLICY"
Drucker wurde über eine Richtlinie hinzugefügt.

PrinterStatus

Der Status des Druckers.

Enum

„DOOR_OPEN“
Die Druckerklappe ist geöffnet. Der Drucker nimmt weiterhin Druckaufträge an.

"TRAY_MISSING"
Das Fach des Druckers fehlt. Der Drucker nimmt weiterhin Druckaufträge an.

„OUT_OF_INK“
Im Drucker ist keine Tinte mehr vorhanden. Der Drucker akzeptiert weiterhin Druckaufträge.

„OUT_OF_PAPER“
Im Drucker ist kein Papier mehr vorhanden. Der Drucker akzeptiert weiterhin Druckaufträge.

„OUTPUT_FULL“
Der Ausgabebereich des Druckers (z. B. das Fach) ist voll. Der Drucker akzeptiert weiterhin Druckaufträge.

„PAPER_JAM“
Im Drucker ist ein Papierstau aufgetreten. Der Drucker akzeptiert weiterhin Druckaufträge.

"GENERIC_ISSUE"
Ein allgemeines Problem. Der Drucker nimmt weiterhin Druckaufträge an.

"STOPPED"
Der Drucker wurde angehalten und druckt nicht, akzeptiert aber weiterhin Druckaufträge.

„UNREACHABLE“
Der Drucker ist nicht erreichbar und nimmt keine Druckaufträge an.

"EXPIRED_CERTIFICATE"
Das SSL-Zertifikat ist abgelaufen. Der Drucker nimmt die Aufträge an, schlagen jedoch fehl.

"AVAILABLE"
Der Drucker ist verfügbar.

SubmitJobRequest

Attribute

  • Job

    PrintJob

    Der Druckauftrag, der gesendet werden soll. Der einzige unterstützte Inhaltstyp ist „application/pdf“. Das Cloud Job Ticket sollte keine Felder FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem und VendorTicketItem enthalten, da diese für das native Drucken nicht relevant sind. Alle anderen Felder müssen vorhanden sein.

SubmitJobResponse

Attribute

  • jobId

    String optional

    Die ID des erstellten Druckjobs. Hierbei handelt es sich um eine eindeutige Kennung für alle Druckaufträge auf dem Gerät. Wenn der Status nicht „OK“ ist, ist „jobId“ null.

  • Der Status der Anfrage.

SubmitJobStatus

Der Status der submitJob-Anfrage.

Enum

"OK"
Die gesendete Druckauftragsanfrage wurde akzeptiert.

USER_REJECTED
Der gesendeten Druckauftragsanfrage wurde vom Nutzer abgelehnt.

Attribute

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Die maximale Anzahl von Aufrufen von getPrinterInfo pro Minute.

Wert

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Die maximale Anzahl von Aufrufen von submitJob pro Minute.

Wert

40 
 

Methoden

cancelJob()

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

Bricht einen zuvor gesendeten Job ab.

Parameter

  • jobId

    String

    Die ID des Druckauftrags, der abgebrochen werden soll. Dies sollte dieselbe ID sein, die in einer SubmitJobResponse empfangen wurde.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 100 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getPrinterInfo()

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

Gibt den Status und die Funktionen des Druckers im CDD-Format zurück. Dieser Aufruf schlägt mit einem Laufzeitfehler fehl, wenn keine Drucker mit der angegebenen ID installiert sind.

Parameter

Gibt Folgendes zurück:

  • Chrome 100+

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getPrinters()

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

Gibt die Liste der auf dem Gerät verfügbaren Drucker zurück. Dazu gehören manuell hinzugefügte, Unternehmensdrucker und erkannte Drucker.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (printers: Printer[]) => void

Gibt Folgendes zurück:

  • Promise<Drucker[]>

    Chrome 100 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

submitJob()

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

Der Job wird zum Drucken gesendet. Wenn die Erweiterung nicht in der PrintingAPIExtensionsAllowlist-Richtlinie aufgeführt ist, wird der Nutzer aufgefordert, den Druckauftrag zu akzeptieren. Vor Chrome 120 gab diese Funktion kein Promise zurück.

Parameter

Gibt Folgendes zurück:

  • Chrome 100+

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onJobStatusChanged

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

Ereignis, das ausgelöst wird, wenn sich der Status des Jobs ändert. Dieser wird nur für Jobs ausgelöst, die von dieser Erweiterung erstellt wurden.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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