chrome.printing

refresh date: 2026-09-25 robots: noindex

Beschreibung

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

Berechtigungen

printing

Verfügbarkeit

Chrome 81 oder höher Nur ChromeOS

Manifest

Für alle chrome.printing-Methoden und -Ereignisse müssen Sie die Berechtigung "printing" im Erweiterungsmanifest deklarieren. Beispiel:

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

Beispiele

In den folgenden Beispielen wird die Verwendung der einzelnen Methoden im Namespace „printing“ veranschaulicht. Dieser Code wurde aus dem GitHub-Repository „extensions-samples“ aus api-samples/printing kopiert oder basiert darauf.

cancelJob()

In diesem Beispiel wird der Handler onJobStatusChanged verwendet, um eine Schaltfläche „Abbrechen“ auszublenden, wenn der jobStatus weder PENDING noch IN_PROGRESS ist. In einigen Netzwerken oder wenn ein Chromebook direkt mit dem Drucker verbunden ist, werden diese Status möglicherweise zu schnell durchlaufen, sodass die Schaltfläche zum Abbrechen nicht lange genug sichtbar ist, um sie aufzurufen. 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 ein einzelnes 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 aus den verfügbaren Funktionen auswählen muss, können Sie diese für einen bestimmten Drucker mit getPrinterInfo() abrufen.
  • Eine SubmitJobRequest-Struktur, die den zu verwendenden Drucker und die zu druckende Datei oder das zu druckende Datum angibt. Diese Struktur enthält einen Verweis auf die ticket-Struktur.
  • Ein Blob der Datei oder der 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. Verwenden Sie PrintingAPIExtensionsAllowlist, um die Bestätigung zu überspringen.

Dies ist eine vereinfachte Version des Druckbeispiels. Beachten Sie, dass ticket an die Struktur SubmitJobRequest (Zeile 8) angehängt ist und dass die zu druckenden Daten in ein Blob konvertiert werden (Zeile 10). Das Abrufen der ID des Druckers (Zeile 1) ist im Beispiel komplizierter als hier dargestellt.

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 ein Druckerticket für den Endlosdruck (oder Rollendruck) erstellt wird, der häufig beim Drucken von Belegen verwendet wird. Das submitJobRequest-Objekt für den Rollendruck ist mit dem im Beispiel submitJob() gezeigten Objekt identisch.

Wenn Sie den Standardwert für das Schneiden von Papier ändern möchten, verwenden Sie den Schlüssel vendor_ticket_item. Die Standardeinstellung variiert je nach 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 Druckvorgangs schneiden, 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 herausfinden 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 sind für jeden Drucker spezifisch. Rufen Sie getPrinterInfo() auf, um eine geeignete Größe auszuwählen. Die zurückgegebene GetPrinterResponse enthält ein Array der unterstützten Mediengrößen unter "media_size"."option". Wählen Sie eine Option aus, deren "is_continuous_feed"-Wert „true“ ist. Verwenden Sie die Werte für Höhe und Breite für das Ticket.

"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. Das Attribut fehlt möglicherweise.

  • Status

    PrinterStatus

    Der Status des Druckers.

JobStatus

Status des Druckauftrags.

Enum

PENDING
Der Druckauftrag wurde von Chrome empfangen, aber noch nicht verarbeitet.

"IN_PROGRESS"
Der Druckauftrag wurde zum Drucken gesendet.

"FAILED"
Der Druckauftrag wurde aufgrund eines Fehlers unterbrochen.

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

"PRINTED"
Der Druckauftrag wurde ohne Fehler gedruckt.

Printer

Attribute

  • Beschreibung

    String

    Die menschenlesbare Beschreibung des Druckers.

  • id

    String

    Die Kennung des Druckers, die unter den Druckern auf dem Gerät eindeutig ist.

  • isDefault

    boolean

    Das Flag, das angibt, ob der Drucker den Regeln für DefaultPrinterSelection entspricht. Es können mehrere Drucker gekennzeichnet werden.

  • name

    String

    Der Name des Druckers.

  • recentlyUsedRank

    number optional

    Der Wert, der angibt, wie lange es her ist, dass der Drucker zum Drucken über Chrome verwendet wurde. Je niedriger der Wert, desto kürzer liegt die letzte Verwendung des Druckers zurück. Der Mindestwert beträgt 0. Ein fehlender Wert bedeutet, dass der Drucker in letzter Zeit nicht verwendet wurde. Dieser Wert ist für jeden Drucker eindeutig.

  • Quelle

    PrinterSource

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

  • uri

    String

    Der Drucker-URI. Diese Einstellung kann von Erweiterungen verwendet werden, um den Drucker für den Nutzer auszuwählen.

PrinterSource

Die Quelle des Druckers.

Enum

"USER"
Der Drucker wurde vom Nutzer hinzugefügt.

RICHTLINIE
Der Drucker wurde über eine Richtlinie hinzugefügt.

PrinterStatus

Der Status des Druckers.

Enum

"DOOR_OPEN"
Die Tür des Druckers ist offen. Der Drucker nimmt weiterhin Druckaufträge an.

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

"OUT_OF_INK"
Die Tinte des Druckers ist leer. Der Drucker nimmt weiterhin Druckaufträge an.

"OUT_OF_PAPER"
Der Drucker hat kein Papier mehr. Der Drucker nimmt weiterhin Druckaufträge an.

"OUTPUT_FULL"
Der Ausgabebereich des Druckers (z.B. das Fach) ist voll. Der Drucker nimmt weiterhin Druckaufträge an.

"PAPER_JAM"
Der Drucker hat einen Papierstau. Der Drucker nimmt weiterhin Druckaufträge an.

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

„STOPPED“
Der Drucker ist angehalten und druckt nicht, akzeptiert aber weiterhin Druckaufträge.

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

"EXPIRED_CERTIFICATE"
Das SSL-Zertifikat ist abgelaufen. Der Drucker akzeptiert Aufträge, aber sie schlagen fehl.

VERFÜGBAR
Der Drucker ist verfügbar.

SubmitJobRequest

Attribute

  • Job

    PrintJob

    Der zu sendende Druckauftrag. Unterstützte Inhaltstypen sind „application/pdf“ und „image/png“. Das Cloud-Jobticket sollte die Felder FitToPageTicketItem, PageRangeTicketItem und ReverseOrderTicketItem nicht enthalten, da sie für das native Drucken irrelevant sind. VendorTicketItem ist optional. Alle anderen Felder müssen vorhanden sein.

SubmitJobResponse

Attribute

  • jobId

    String optional

    Die ID des erstellten Druckauftrags. Dies ist 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 Anfrage von submitJob.

Enum

OK
Die gesendete Druckauftragsanfrage wurde akzeptiert.

"USER_REJECTED"
Die gesendete 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,
): Promise<void>

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

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 100 oder höher

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

getJobStatus()

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

Gibt den Status des Druckauftrags zurück. Dieser Aufruf schlägt mit einem Laufzeitfehler fehl, wenn der Druckauftrag mit der angegebenen jobId nicht vorhanden ist. jobId: Die ID des Druckauftrags, dessen Status zurückgegeben werden soll. Dies sollte dieselbe ID sein, die in einer SubmitJobResponse empfangen wurde.

Parameter

  • jobId

    String

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (status: JobStatus) => void

Ausgabe

  • Promise<JobStatus>

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

getPrinterInfo()

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

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

Ausgabe

  • Chrome 100 oder höher

    Promises 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,
): Promise<Printer[]>

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

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (printers: Printer[]) => void

Ausgabe

  • Promise<Printer[]>

    Chrome 100 oder höher

    Promises 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,
): Promise<SubmitJobResponse>

Sendet den Auftrag zum Drucken. Wenn die Erweiterung nicht in der Richtlinie PrintingAPIExtensionsAllowlist aufgeführt ist, wird der Nutzer aufgefordert, den Druckauftrag zu akzeptieren. Vor Chrome 120 hat diese Funktion kein Promise zurückgegeben.

Parameter

Ausgabe

  • Chrome 100 oder höher

    Promises 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. Dies wird nur für die von dieser Erweiterung erstellten Jobs ausgelöst.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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