Beschreibung
Mit der chrome.printing
API kannst du Druckaufträge an Drucker senden, die auf deinem Chromebook installiert sind.
Berechtigungen
printing
Verfügbarkeit
Manifest
Für alle chrome.printing
-Methoden und -Ereignisse muss die Berechtigung "printing"
im Erweiterungsmanifest deklariert werden. Beispiel:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Beispiele
In den folgenden Beispielen wird die Verwendung der einzelnen Methoden im Drucker-Namespace veranschaulicht. Dieser Code wird aus oder basierend auf api-samples/printing im GitHub-Repository „extensions-Beispiele“ kopiert.
cancelJob()
In diesem Beispiel wird der onJobStatusChanged
-Handler verwendet, um die Schaltfläche „Abbrechen“ auszublenden, wenn jobStatus
weder PENDING
noch IN_PROGRESS
ist. Beachten Sie, dass diese Status in einigen Netzwerken oder bei direkter Verbindung eines Chromebooks mit dem Drucker zu schnell übertragen werden, sodass die Schaltfläche zum Abbrechen nicht lange genug sichtbar ist, 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 für das 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}`);
sendJob()
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 verfügbaren Funktionen treffen muss, können Sie diese mitgetPrinterInfo()
für einen bestimmten Drucker abrufen. - Eine
SubmitJobRequest
-Struktur, die den zu verwendenden Drucker und die Datei oder das Datum für den Druck angibt. Diese Struktur enthält einen Verweis auf dieticket
-Struktur. - Ein Blob der zu druckenden Datei oder der zu druckenden Daten.
Durch das Aufrufen von submitJob()
wird ein Dialogfeld ausgelöst, in dem der Nutzer aufgefordert wird, das Drucken zu bestätigen. Mit PrintingAPIExtensionsAllowlist
können Sie die Bestätigung umgehen.
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 konvertiert werden (Zeile 10). Das Abrufen der ID des Druckers (Zeile 1) ist im Beispiel komplizierter als hier gezeigt.
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 fortlaufenden Druck (bzw. auf Rollen) erstellen, das häufig für Belegdrucke verwendet wird. Das submitJobRequest
-Objekt für den Rollendruck ist dasselbe wie im submitJob()
-Beispiel.
Wenn Sie den Standardwert für das Papierschneiden ändern müssen, verwenden Sie den Schlüssel vendor_ticket_item
. (Die Standardeinstellung ist von Drucker zu Drucker unterschiedlich.) Wenn dieser Schlüssel enthalten ist, muss er ein Array mit einem Element sein: ein Objekt, dessen id
'finishings'
ist. Der Wert kann entweder 'trim'
für Drucker sein, die die Rolle am Ende des Druckens schneiden, oder 'none'
für Drucker, bei denen der Druckauftrag entfernt 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. Um herauszufinden, ob das bei Ihrem Drucker der Fall ist, 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. Rufen Sie getPrinterInfo()
auf, um eine geeignete Größe auszuwählen. Das zurückgegebene GetPrinterResponse
enthält ein Array unterstützter 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
Objekt optional
Druckerfunktionen im CDD-Format Möglicherweise fehlt die Property.
-
status
Der Status des Druckers.
JobStatus
Status des Druckauftrags.
Enum
"AUSSTEHEND"
Der Druckauftrag wurde in Chrome empfangen, wurde aber noch nicht verarbeitet.
"IN_PROGRESS"
Druckauftrag wurde zum Drucken gesendet.
"FAILED"
Der Druckauftrag wurde aufgrund eines Fehlers unterbrochen.
"ABGEBROCHEN"
Der Druckauftrag wurde vom Nutzer oder über die API abgebrochen.
"DRUCK"
Der Druckauftrag wurde ohne Fehler gedruckt.
Printer
Attribute
-
Beschreibung
String
Die visuell lesbare Beschreibung des Druckers.
-
id
String
Die Drucker-ID, die unter den Druckern auf dem Gerät eindeutig ist.
-
isDefault
boolean
Flag, das angibt, ob der Drucker den DefaultPrinterSelection-Regeln entspricht. Beachte, dass mehrere Drucker markiert wurden.
-
name
String
Der Name des Druckers.
-
recentlyUsedRank
Nummer optional
Der Wert, der angibt, wie aktuell der Drucker zum Drucken aus Chrome verwendet wurde. Je niedriger der Wert ist, desto länger wurde der Drucker verwendet. Der Mindestwert ist 0. Ein fehlender Wert weist darauf hin, dass der Drucker in letzter Zeit nicht verwendet wurde. Dieser Wert ist unter den Druckern garantiert eindeutig.
-
source
Die Quelle des Druckers (Nutzer oder Richtlinie konfiguriert).
-
uri
String
Der Drucker-URI. Damit kann von Erweiterungen der Drucker für den Nutzer ausgewählt werden.
PrinterSource
Die Quelle des Druckers.
Enum
"NUTZER"
Drucker wurde vom Nutzer hinzugefügt.
"POLICY"
Drucker wurde über eine Richtlinie hinzugefügt.
PrinterStatus
Der Status des Druckers.
Enum
"DOOR_OPEN"
Die Tür des Druckers ist offen. Der Drucker akzeptiert weiterhin Druckaufträge.
"TRAY_MISSING"
Das Fach des Druckers fehlt. Der Drucker akzeptiert weiterhin Druckaufträge.
"OUT_OF_INK"
Der Drucker hat keine Tinte mehr. Der Drucker akzeptiert weiterhin Druckaufträge.
"OUT_OF_PAPER"
Der Drucker hat kein Papier. Der Drucker akzeptiert weiterhin Druckaufträge.
"OUTPUT_FULL"
Der Ausgabebereich des Druckers (z.B. Fach) ist voll. Der Drucker akzeptiert weiterhin Druckaufträge.
"PAPER_JAM"
Der Drucker hat einen Papierstau. Der Drucker akzeptiert weiterhin Druckaufträge.
"GENERIC_ISSUE"
Ein allgemeines Problem. Der Drucker akzeptiert weiterhin Druckaufträge.
"ANGEHALTEN"
Der Drucker wurde 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 nimmt Aufträge an, sie schlagen jedoch fehl.
"AVAILABLE"
Der Drucker ist verfügbar.
SubmitJobRequest
Attribute
-
Job
Der zu sendende Druckauftrag. Der einzige unterstützte Inhaltstyp ist „application/pdf“ und das Cloud Job Ticket sollte keine Felder für
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
undVendorTicketItem
enthalten, da sie für das native Drucken nicht relevant sind. Alle anderen Felder müssen vorhanden sein.
SubmitJobResponse
Attribute
-
jobId
String optional
Die ID des erstellten Druckauftrags. Dies ist eine eindeutige Kennung unter allen Druckaufträgen auf dem Gerät. Wenn der Status nicht OK ist, ist jobId null.
-
status
Der Status der Anfrage.
SubmitJobStatus
Der Status der submitJob
-Anfrage.
Enum
"OK"
Die gesendete Druckauftragsanfrage wurde angenommen.
"USER_REJECTED"
Die gesendete Druckauftragsanfrage wurde vom Nutzer abgelehnt.
Attribute
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
Die maximale Häufigkeit, mit der getPrinterInfo
pro Minute aufgerufen werden kann.
Wert
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
Die maximale Häufigkeit, mit der submitJob
pro Minute aufgerufen werden kann.
Wert
40
Methoden
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Bricht den zuvor gesendeten Job ab.
Parameters
-
jobId
String
Die ID des Druckauftrags, der abgebrochen werden soll. Dies sollte mit der ID übereinstimmen, die Sie in einem
SubmitJobResponse
erhalten haben. -
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgaben
-
Promise<void>
Chrome 100 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Gibt den Status und die Funktionen des Druckers im CDD-Format zurück. Dieser Aufruf wird mit einem Laufzeitfehler fehlschlagen, wenn keine Drucker mit der angegebenen ID installiert sind.
Parameters
-
printerId
String
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(response: GetPrinterInfoResponse) => void
-
Antwort
-
Rückgaben
-
Promise<GetPrinterInfoResponse>
Chrome 100 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getPrinters()
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.
Parameters
Rückgaben
-
Promise<Drucker[]>
Chrome 100 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Sendet den Auftrag zum Drucken. Ist die Erweiterung nicht in der Richtlinie PrintingAPIExtensionsAllowlist
aufgeführt, wird der Nutzer aufgefordert, den Druckauftrag zu akzeptieren.
Vor Chrome 120 gab diese Funktion kein Versprechen zurück.
Parameters
-
Request
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(response: SubmitJobResponse) => void
-
Antwort
-
Rückgaben
-
Promise<SubmitJobResponse>
Chrome 100 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
Veranstaltungen
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
Das Ereignis wird ausgelöst, wenn sich der Status des Jobs ändert. Dieses Ereignis wird nur bei Jobs ausgelöst, die von dieser Erweiterung erstellt wurden.