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 81 und höher Nur ChromeOS

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

In den folgenden Beispielen wird die Verwendung der einzelnen Methoden im Druck-Namespace veranschaulicht. 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. 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 „Abbrechen“ nicht lange genug sichtbar ist, um aufgerufen zu werden. Dies ist ein stark vereinfachtes Beispiel für das Drucken.

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 aus den verfügbaren Funktionen auswählen muss, können Sie sie mit getPrinterInfo() für einen bestimmten Drucker 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.

Wenn Sie submitJob() aufrufen, wird ein Dialogfeld angezeigt, in dem der Nutzer den Druck bestätigen muss. Mit PrintingAPIExtensionsAllowlist können Sie die Bestätigung überspringen.

Dies ist eine vereinfachte Version des Druckbeispiels. Beachten Sie, dass ticket an die Struktur SubmitJobRequest angehängt ist (Zeile 8) und dass die zu druckenden Daten in einen Blob umgewandelt werden (Zeile 10). Die ID des Druckers (Zeile 1) wird im Beispiel komplizierter ermittelt 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 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 Schneiden von Papier ändern möchten, verwenden Sie die Taste vendor_ticket_item. (Die Standardeinstellung variiert je nach Drucker.) Wenn Sie den Wert ändern möchten, geben Sie ein Array mit einem Element an: 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 media_size-Schlüssel eines Tickets sind für jeden Drucker spezifisch. Um eine geeignete Größe auszuwählen, drücken Sie die Taste getPrinterInfo(). Die zurückgegebene GetPrinterResponse enthält ein Array mit unterstützten Mediengrößen unter "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 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

    object 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 von 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 für Menschen 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. Es können mehrere Drucker gemeldet werden.

  • name

    String

    Der Name des Druckers.

  • recentlyUsedRank

    number optional

    Der Wert gibt an, wie lange es her ist, dass der Drucker zum Drucken über Chrome verwendet wurde. Je niedriger der Wert, desto kürzer ist die Zeitspanne seit der letzten Nutzung des Druckers. 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

    Die 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.

„RICHTLINIE“
Der 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 Papierfach des Druckers fehlt. Der Drucker nimmt weiterhin Druckaufträge an.

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

„OUT_OF_PAPER“
Im Drucker ist kein Papier mehr vorhanden. 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“
Im Drucker ist ein Papierstau aufgetreten. Der Drucker nimmt weiterhin Druckaufträge an.

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

„ANGEHALTEN“
Der Drucker ist angehalten und druckt nicht, nimmt aber weiterhin Druckaufträge an.

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

"EXPIRED_CERTIFICATE"
Das SSL-Zertifikat ist abgelaufen. Der Drucker nimmt Jobs an, die aber fehlschlagen.

„VERFÜGBAR“
Der Drucker ist verfügbar.

SubmitJobRequest

Attribute

  • Job

    PrintJob

    Der zu sendende Druckauftrag. Der einzige unterstützte Inhaltstyp ist „application/pdf“. Das Cloud-Jobticket darf keine Felder vom Typ FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem und VendorTicketItem enthalten, da diese für den nativen Druck irrelevant sind. Alle anderen Felder müssen vorhanden sein.

SubmitJobResponse

Attribute

  • jobId

    String optional

    Die ID des erstellten Druckjobs. Dies ist eine eindeutige Kennung unter allen Druckjobs auf dem Gerät. Wenn der Status nicht „OK“ ist, ist „jobId“ null.

  • Der Status der Anfrage.

SubmitJobStatus

Der Status der Anfrage submitJob.

Enum

„OK“
Der gesendeten Druckauftragsanfrage wurde stattgegeben.

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 mit der ID übereinstimmen, die in einer SubmitJobResponse empfangen wurde.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 100+

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getJobStatus()

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

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

Parameter

  • jobId

    String

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (status: JobStatus) => void

Ausgabe

  • Promise<JobStatus>

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getPrinterInfo()

Promise 
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

Ausgabe

  • Chrome 100+

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getPrinters()

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

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<Drucker[]>

    Chrome 100+

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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

Ausgabe

  • Chrome 100+

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

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