Opis
Używaj interfejsu chrome.printing
API, aby wysyłać zadania drukowania do drukarek zainstalowanych na Chromebooku.
Uprawnienia
printing
Dostępność
Wszystkie metody i zdarzenia chrome.printing
wymagają zadeklarowania uprawnienia "printing"
w pliku manifestu rozszerzenia. Na przykład:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Przykłady
Poniższe przykłady pokazują korzystanie z poszczególnych metod w przestrzeni nazw drukowania. Ten kod jest kopiowany z interfejsu api-samples/printing lub oparty na nim w repozytorium na GitHubie z przykładami rozszerzeń.
cancelJob()
W tym przykładzie użyto modułu obsługi onJobStatusChanged
do ukrycia przycisku „Anuluj”, gdy jobStatus
nie ma wartości PENDING
ani IN_PROGRESS
. W niektórych sieciach lub gdy Chromebook jest podłączony bezpośrednio do drukarki, stany te mogą przechodzić za szybko, aby przycisk anulowania był widoczny na tyle długo, by można go było wywołać. To jest przykład bardzo uproszczonego 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()
W przypadku tych funkcji używany jest jeden przykład, ponieważ uzyskiwanie informacji o drukarce wymaga identyfikatora drukarki, który jest pobierany przez wywołanie metody getPrinters()
. Ten przykład powoduje zapisanie w konsoli nazwy i opisu drukarki domyślnej. 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}`);
prześlij zadanie()
Metoda submitJob()
wymaga 3 czynników.
- Struktura
ticket
określająca funkcje drukarki, które mają zostać użyte. Jeśli użytkownik musi wybrać jedną z dostępnych funkcji, możesz je pobrać dla konkretnej drukarki, korzystając z usługigetPrinterInfo()
. - Struktura
SubmitJobRequest
, która określa drukarkę, która ma zostać użyta, oraz plik lub datę wydrukowania. Ta struktura zawiera odniesienie do strukturyticket
. - Blob pliku lub dane 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ż na ilustracji.
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 na rolce
Ten przykład pokazuje, jak utworzyć bilet na drukarkę do drukowania w rolce, co jest często używane do drukowania paragonów. Obiekt submitJobRequest
do drukowania w rolce jest taki sam jak w przykładzie submitJob()
.
Jeśli chcesz zmienić domyślną wartość opcji wycinania papieru, użyj klucza vendor_ticket_item
. (Wartość domyślna różni się w zależności od drukarki). Aby zmienić wartość, podaj tablicę z jednym elementem – obiektem, którego id
to 'finishings'
. Może mieć wartość 'trim'
w przypadku drukarek, które obcinają rolkę na końcu drukowania, lub 'none'
w przypadku drukarek, które wymagają przerwania 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 sprawdzić, czy drukarka działa, wywołaj getPrinterInfo()
i sprawdź wartość "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ą inne dla każdej drukarki. Aby wybrać odpowiedni rozmiar wywołania getPrinterInfo()
. Zwracany element GetPrinterResponse
zawiera tablicę obsługiwanych rozmiarów multimediów w wartości "media_size"."option"
. Wybierz opcję, której wartość "is_continuous_feed"
to prawda. Użyj wartości wysokości i szerokości dla 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
-
capabilities
obiekt opcjonalnie
Funkcje drukarek w formacie CDD. Możliwe, że brakuje właściwości.
-
status
Stan drukarki.
JobStatus
Stan zadania drukowania.
Typ wyliczeniowy
"PENDING"
Zadanie drukowania zostało odebrane po stronie Chrome, ale nie zostało jeszcze przetworzone.
"IN_PROGRESS"
Zadanie drukowania zostało wysłane do drukowania.
„FAILED”
Zadanie drukowania zostało przerwane z powodu błędu.
„CANCELED”
Zadanie drukowania zostało anulowane przez użytkownika lub przez interfejs API.
„printED”
Zadanie drukowania zostało wydrukowane bez błędów.
Printer
Właściwości
-
opis
string,
Zrozumiały dla człowieka opis drukarki.
-
id
string,
Identyfikator drukarki, który jest niepowtarzalny wśród drukarek na urządzeniu.
-
isDefault
boolean
Flaga wskazująca, czy drukarka pasuje do reguł DefaultPrinterSelection. Pamiętaj, że kilka drukarek może zostać oznaczonych.
-
nazwa
string,
Nazwa drukarki.
-
recentlyUsedRank
Liczba opcjonalnie
Wartość wskazująca, kiedy drukarka była ostatnio używana do drukowania z Chrome. Im niższa wartość, tym ostatnio była używana drukarka. Wartość minimalna to 0. Brak wartości oznacza, że drukarka nie była ostatnio używana. Ta wartość jest gwarantowana niepowtarzalna wśród drukarek.
-
source
Źródło drukarki (skonfigurowane konto użytkownika lub zasada).
-
uri
string,
Identyfikator URI drukarki. Dzięki temu rozszerzenia mogą wybrać drukarkę dla użytkownika.
PrinterSource
Źródło drukarki.
Typ wyliczeniowy
„USER”
Drukarka została dodana przez użytkownika.
"ZASADY"
Drukarka została dodana przez zasady.
PrinterStatus
Stan drukarki.
Typ wyliczeniowy
"DOOR_OPEN"
Drzwiy drukarki są otwarte. Drukarka nadal akceptuje zadania drukowania.
"TRAY_MISSING"
Brak zasobnika drukarki. Drukarka nadal akceptuje zadania drukowania.
"OUT_OF_INK"
Skończyło się tusz w drukarce. Drukarka nadal akceptuje zadania drukowania.
"OUT_OF_PAPER"
Skończyło się papier w drukarce. Drukarka nadal akceptuje zadania drukowania.
"OUTPUT_FULL"
Obszar wyjściowy drukarki (np. tacka) jest pełny. Drukarka nadal akceptuje zadania drukowania.
"PAPER_JAM"
W drukarce wystąpiło zacięcie papieru. Drukarka nadal akceptuje zadania drukowania.
"GENERIC_ISSUE"
Problem ogólny. Drukarka nadal akceptuje zadania drukowania.
„STOPPED”
Drukarka została zatrzymana i nie drukuje, ale nadal akceptuje zadania drukowania.
„UNREACHABLE”
Drukarka jest nieosiągalna i nie przyjmuje zadań drukowania.
"SCHEDULED_CERTIFICATE"
Certyfikat SSL wygasł. Drukarka akceptuje zadania, ale kończą się one niepowodzeniem.
"AVAILABLE"
Drukarka jest dostępna.
SubmitJobRequest
Właściwości
-
zadanie
Zadanie drukowania, które ma zostać przesłane. Jedyny obsługiwany typ treści to „application/pdf”, a Cloud Job Ticket nie powinien zawierać pól
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
aniVendorTicketItem
, ponieważ nie są one potrzebne do drukowania natywnego. Wszystkie pozostałe pola muszą być obecne.
SubmitJobResponse
Właściwości
-
jobId
ciąg znaków opcjonalny
Identyfikator utworzonego zadania drukowania. Jest to unikalny identyfikator spośród wszystkich zadań drukowania na urządzeniu. Jeśli stan jest inny, identyfikator zadania będzie miał wartość null.
-
status
Stan żądania.
SubmitJobStatus
Stan prośby submitJob
.
Typ wyliczeniowy
"OK"
Wysłane żądanie zadania drukowania zostało zaakceptowane.
"USER_REJECTED"
Użytkownik odrzucił wysłane żądanie zadania drukowania.
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 przesłane wcześniej zadanie.
Parametry
-
jobId
string,
Identyfikator zadania drukowania do anulowania. Powinien to być ten sam identyfikator, który został przesłany w
SubmitJobResponse
. -
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 100 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 są zainstalowane żadne drukarki o podanym identyfikatorze, to wywołanie zakończy się błędem środowiska wykonawczego.
Parametry
-
printerId
string,
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(response: GetPrinterInfoResponse) => void
-
odpowiedź
-
Zwroty
-
Promise<GetPrinterInfoResponse>
Chrome 100 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 100 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Przesyłam zadanie do drukowania. Jeśli rozszerzenia nie ma na liście zasad PrintingAPIExtensionsAllowlist
, użytkownik zostanie poproszony o zaakceptowanie zadania drukowania.
Przed wersją Chrome 120 ta funkcja nie zwracała obietnicy.
Parametry
-
Poproś
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(response: SubmitJobResponse) => void
-
odpowiedź
-
Zwroty
-
Promise<SubmitJobResponse>
Chrome 100 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
Zdarzenie wywoływane po zmianie stanu zadania. To rozszerzenie jest uruchamiane tylko w przypadku zadań utworzonych przez to rozszerzenie.