Opis
Do wysyłania zadań drukowania do drukarek zainstalowanych na Chromebooku używaj interfejsu API chrome.printing
.
Uprawnienia
printing
Dostępność
Wszystkie metody i zdarzenia chrome.printing
wymagają zadeklarowania uprawnień "printing"
w pliku manifestu rozszerzenia. Na przykład:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Przykłady
Poniższe przykłady pokazują korzystanie z każdej z metod w przestrzeni nazw drukowania. Ten kod został skopiowany z pliku api-samples/printing w repozytorium GitHub z przykładami rozszerzeń lub na podstawie tego kodu.
cancelJob()
W tym przykładzie użyto modułu obsługi onJobStatusChanged
do ukrycia elementu „cancel” gdy jobStatus
nie ma wartości PENDING
ani IN_PROGRESS
. Pamiętaj, że w niektórych sieciach lub gdy Chromebook jest podłączony bezpośrednio do drukarki, te stany mogą mijać zbyt szybko, by przycisk anulowania był widoczny dostatecznie długo, by można było wywołać przycisk. Jest to znacznie uproszczony przykład drukowania.
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()
Wykorzystano jeden przykład tych funkcji, ponieważ do uzyskania informacji o drukarce wymagany jest identyfikator drukarki, który jest pobierany przez wywołanie metody getPrinters()
. Ten przykład rejestruje nazwę i opis drukarki domyślnej w konsoli. To jest uproszczona wersja przykładu drukowania.
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()
Metoda submitJob()
wymaga 3 elementów.
- Struktura
ticket
określająca, które funkcje drukarki mają być używane. Jeśli użytkownik musi wybrać spośród dostępnych funkcji, możesz pobrać informacje dla konkretnej drukarki za pomocągetPrinterInfo()
. - Struktura
SubmitJobRequest
określająca drukarkę, która ma być użyta, oraz plik lub datę wydrukowania. Ta struktura zawiera odniesienie do strukturyticket
. - Blob pliku lub danych do wydrukowania.
Wywołanie submitJob()
powoduje wyświetlenie okna z prośbą o potwierdzenie drukowania. Użyj PrintingAPIExtensionsAllowlist
, aby pominąć potwierdzenie.
To jest uproszczona wersja przykładu drukowania. Zwróć uwagę, że obiekt ticket
jest dołączony do struktury SubmitJobRequest
(wiersz 8), a dane do wydrukowania zostały przekonwertowane na obiekt blob (wiersz 10). Uzyskanie identyfikatora drukarki (wiersz 1) jest bardziej skomplikowane w przykładzie niż w tym przykładzie.
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);
}
});
Drukowanie w rolce
Ten przykład pokazuje, jak utworzyć zgłoszenie drukarki do drukowania ciągłego (lub w rolce), które jest często używane w przypadku drukowania paragonów. Obiekt submitJobRequest
w przypadku drukowania w rolce jest taki sam jak w przykładzie dotyczącym submitJob()
.
Jeśli chcesz zmienić domyślną wartość wycinania papieru, użyj klucza vendor_ticket_item
. (Ustawienia domyślne różnią się w zależności od drukarki). Aby zmienić wartość, podaj tablicę z jednym elementem: obiekt, którego id
to 'finishings'
. Wartością może być 'trim'
w przypadku drukarek, które obcinają rolkę po zakończeniu drukowania, lub 'none'
w przypadku drukarek, które wymagają usunięcia zadania drukowania.
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}
}
};
Niektóre drukarki nie obsługują opcji "finishings"
. Aby to sprawdzić, zadzwoń pod numer getPrinterInfo()
i odszukaj "display_name"
o wartości "finishings/11"
.
"vendor_capability": [
{
"display_name": "finishings/11",
"id": "finishings/11",
"type": "TYPED_VALUE",
"typed_value_cap": {
"value_type": "BOOLEAN"
}
},
...
]
Wartości w kluczu media_size
zgłoszenia są unikalne dla każdej drukarki. Aby wybrać odpowiedni rozmiar, wywołaj getPrinterInfo()
. Zwrócony obiekt GetPrinterResponse
zawiera tablicę obsługiwanych rozmiarów multimediów w lokalizacji "media_size"."option"
. Wybierz opcję, której wartość "is_continuous_feed"
to true (prawda). Użyj wartości wysokości i szerokości biletu.
"media_size": {
"option": [
{
"custom_display_name": "",
"is_continuous_feed": true,
"max_height_microns": 2000000,
"min_height_microns": 25400,
"width_microns": 50800
},
...
]
}
Typy
GetPrinterInfoResponse
Właściwości
-
możliwości
obiekt opcjonalny
Funkcje drukarki w formacie CDD. Możliwe, że brakuje właściwości.
-
status
Stan drukarki.
JobStatus
Stan zadania drukowania.
Typ wyliczeniowy
„OCZEKUJE”
Odebrano zadanie drukowania po stronie Chrome, ale nie zostało jeszcze przetworzone.
"IN_PROGRESS"
Wysłano zadanie drukowania do drukowania.
„FAILED”
Zadanie drukowania zostało przerwane z powodu błędu.
„CANCELED”
Zadanie drukowania zostało anulowane przez użytkownika lub za pomocą interfejsu API.
"DRUKOWANO"
Zadanie drukowania zostało wydrukowane bez błędów.
Printer
Właściwości
-
opis
ciąg znaków
Zrozumiały dla człowieka opis drukarki.
-
id
ciąg znaków
identyfikator drukarki; musi być niepowtarzalna wśród wszystkich drukarek na urządzeniu.
-
isDefault
wartość logiczna
Flaga wskazująca, czy drukarka pasuje do reguł DefaultPrinterSelection. Pamiętaj, że mogło zostać oznaczonych kilka drukarek.
-
nazwa
ciąg znaków
Nazwa drukarki.
-
recentlyUsedRank
liczba opcjonalnie
Wartość wskazująca, jak ostatnio drukarka była używana do drukowania w Chrome. Niższa wartość oznacza, że drukarka była ostatnio używana. Wartość minimalna wynosi 0. Brak wartości oznacza, że drukarka nie była ostatnio używana. Ta wartość będzie unikalna wśród drukarek.
-
źródło
Źródło drukarki (skonfigurowane przez użytkownika lub zasady).
-
identyfikator URI
ciąg znaków
Identyfikator URI drukarki. Rozszerzenia mogą tego użyć, aby wybrać drukarkę dla użytkownika.
PrinterSource
Źródło drukarki.
Typ wyliczeniowy
"USER"
Drukarka została dodana przez użytkownika.
"POLICY"
Drukarka została dodana za pomocą zasady.
PrinterStatus
Stan drukarki.
Typ wyliczeniowy
"DOOR_OPEN"
Drzwiczki drukarki są otwarte. Drukarka nadal akceptuje zadania drukowania.
"TRAY_MISSING"
Brak zasobnika drukarki. Drukarka nadal akceptuje zadania drukowania.
"OUT_OF_INK"
W drukarce skończyło się tusz. Drukarka nadal akceptuje zadania drukowania.
"OUT_OF_PAPER"
W drukarce skończył się papier. Drukarka nadal akceptuje zadania drukowania.
"OUTPUT_FULL"
Obszar wyjściowy drukarki (np. podajnik) jest pełny. Drukarka nadal akceptuje zadania drukowania.
"PAPER_JAM"
W drukarce wystąpił zacięcie papieru. Drukarka nadal akceptuje zadania drukowania.
"GENERIC_ISSUE"
Typowy problem. Drukarka nadal akceptuje zadania drukowania.
„STOPPED”
Drukarka została zatrzymana i nie drukuje, ale wciąż przyjmuje zadania drukowania.
„UNREACHABLE”
Drukarka jest nieosiągalna i nie przyjmuje zadań drukowania.
"EXPIRED_CERTIFICATE"
Certyfikat SSL wygasł. Drukarka przyjmuje zadania, ale kończy się to niepowodzeniem.
"AVAILABLE"
Drukarka jest dostępna.
SubmitJobRequest
Właściwości
-
zadanie
Zadanie drukowania do przesłania. Jedyny obsługiwany typ treści to „application/pdf”, a Cloud Job Ticket nie powinien zawierać pól
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
iVendorTicketItem
, ponieważ nie mają one znaczenia w przypadku natywnego drukowania. Pozostałe pola muszą być wypełnione.
SubmitJobResponse
Właściwości
-
jobId
ciąg znaków opcjonalny
Identyfikator utworzonego zadania drukowania. Jest to unikalny identyfikator wśród wszystkich zadań drukowania na urządzeniu. Jeśli stan nie jest prawidłowy, identyfikator zadania ma wartość null.
-
status
Stan żądania.
SubmitJobStatus
Stan prośby submitJob
.
Typ wyliczeniowy
"OK"
Wysłane zadanie drukowania zostało zaakceptowane.
"USER_REJECTED"
Wysłane zadanie drukowania zostało odrzucone przez użytkownika.
Właściwości
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
Maksymalna liczba wywołań funkcji getPrinterInfo
w ciągu minuty.
Wartość
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
Maksymalna liczba wywołań funkcji submitJob
w ciągu minuty.
Wartość
40
Metody
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Anuluje wcześniej przesłane zadanie.
Parametry
-
jobId
ciąg znaków
Identyfikator zadania drukowania do anulowania. Powinien to być ten sam identyfikator otrzymany w
SubmitJobResponse
. -
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
Zwroty
-
Obietnica<void>
Chrome w wersji 100 lub nowszej .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Zwraca stan i możliwości drukarki w formacie CDD. Jeśli nie zostaną zainstalowane żadne drukarki o podanym identyfikatorze, to wywołanie zakończy się niepowodzeniem i wystąpi błąd środowiska wykonawczego.
Parametry
-
printerId
ciąg znaków
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(response: GetPrinterInfoResponse) => void
-
odpowiedź
-
Zwroty
-
Promise<GetPrinterInfoResponse>
Chrome w wersji 100 lub nowszej .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Zwraca listę drukarek dostępnych na urządzeniu. Obejmuje to drukarki dodane ręcznie, firmowe i wykryte.
Parametry
Zwroty
-
Obietnica<Drukarka[]>
Chrome w wersji 100 lub nowszej .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Przesyła zadanie do drukowania. Jeśli rozszerzenie nie jest wymienione w zasadzie PrintingAPIExtensionsAllowlist
, użytkownik zostanie poproszony o zaakceptowanie zadania drukowania.
Przed wersją Chrome 120 ta funkcja nie zwracała obietnicy.
Parametry
-
żądanie
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(response: SubmitJobResponse) => void
-
odpowiedź
-
Zwroty
-
Promise<SubmitJobResponse>
Chrome w wersji 100 lub nowszej .Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
Zdarzenie jest wywoływane po zmianie stanu zadania. Jest on wywoływany tylko dla zadań utworzonych przez to rozszerzenie.