chrome.printing

Opis

Użyj interfejsu API chrome.printing, aby wysyłać zadania drukowania do drukarek zainstalowanych na Chromebooku.

Uprawnienia

printing

Dostępność

Chrome 81 i nowsze Tylko ChromeOS

Plik manifestu

Wszystkie metody i zdarzenia chrome.printing wymagają zadeklarowania uprawnienia "printing" w pliku manifestu rozszerzenia. Na przykład:

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

Przykłady

Przykłady poniżej pokazują użycie każdej z metod w przestrzeni nazw drukowania. Ten kod został skopiowany z repozytorium GitHub api-samples/printing lub jest na nim oparty.

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 je pobrać 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 odwołanie do struktury ticket.
  • 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 uproszczona wersja przykładu drukowania. Zwróć uwagę, że element ticket jest dołączony do struktury SubmitJobRequest (wiersz 8), a dane do wydrukowania są konwertowane na blob (wiersz 10). W pliku sample uzyskanie identyfikatora drukarki (wiersz 1) jest bardziej skomplikowane 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 z rolki

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ść cięcia papieru, użyj klawisza vendor_ticket_item. (ustawienia domyślne różnią się w zależności od drukarki). Gdy ten klucz jest dołączony, musi być tablicą z jednym elementem: obiektem, którego obiekt 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 sprawdzić, czy Twoja drukarka obsługuje tę funkcję, zadzwoń pod numer getPrinterInfo() i szukaj "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ą specyficzne dla każdej drukarki. Aby wybrać odpowiedni rozmiar, wywołaj getPrinterInfo(). Zwrócona wartość GetPrinterResponse zawiera tablicę obsługiwanych rozmiarów multimediów w "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

    PrinterStatus

    Stan drukarki.

JobStatus

Stan zadania drukowania.

Typ wyliczeniowy

„Oczekujące”
Zlecenie zostało odebrane przez Chrome, ale nie zostało jeszcze przetworzone.

"IN_PROGRESS" 
Zadanie zostało wysłane do drukowania.

„FAILED” (Niepowodzenie)
Zadanie wydruku 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 spełnia reguły DefaultPrinterSelection. Pamiętaj, że mogło zostać oznaczonych kilka drukarek.

  • nazwa

    ciąg znaków

    Nazwa drukarki.

  • recentlyUsedRank

    liczba opcjonalnie

    Wartość pokazująca, jak dawno drukarka była używana do drukowania z Chrome. Im niższa wartość, tym krótszy czas od ostatniego użycia drukarki. Wartość minimalna wynosi 0. Brak wartości oznacza, że drukarka nie była ostatnio używana. Ta wartość jest gwarantowana jako unikalna wśród wszystkich drukarek.

  • źródło

    PrinterSource

    Ź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 przyjmuje zadania drukowania.

"OUT_OF_INK"
W drukarce skończył się tusz. Drukarka nadal przyjmuje zadania drukowania.

"OUT_OF_PAPER"
W drukarce skończył się papier. Drukarka nadal akceptuje zadania drukowania.

"OUTPUT_FULL"
Obszar odbioru drukarki (np. taca) jest pełny. Drukarka nadal akceptuje zadania drukowania.

"PAPER_JAM"
W drukarce wystąpił zacięcie papieru. Drukarka nadal przyjmuje zadania drukowania.

"GENERIC_ISSUE"
Typowy problem. Drukarka nadal przyjmuje 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.

"disableD_CERTIFICATE"
Certyfikat SSL wygasł. Drukarka przyjmuje zadania, ale kończy się to niepowodzeniem.

"AVAILABLE"
Drukarka jest dostępna.

SubmitJobRequest

Właściwości

  • zadanie

    PrintJob

    Zadanie drukowania do przesłania. Jedynym obsługiwanym typem treści jest „application/pdf”, a zgłoszenie zadania w chmurze nie powinno zawierać pól FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem ani VendorTicketItem, ponieważ są one nieistotne w przypadku 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 wśród wszystkich zadań drukowania na urządzeniu. Jeśli stan nie jest prawidłowy, identyfikator zadania ma wartość null.

  • 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 na minutę.

Wartość

40

Metody

cancelJob()

Obietnice 
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, który został otrzymany w ramach SubmitJobResponse.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 100+

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getPrinterInfo()

Obietnice 
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

Zwroty

  • Promise&lt;GetPrinterInfoResponse&gt;

    Chrome w wersji 100 lub nowszej

    Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

getPrinters()

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

Zwraca listę dostępnych drukarek na urządzeniu. Obejmuje to drukarki dodane ręcznie, firmowe i wykryte.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback ma postać:

    (printers: Printer[]) => void

Zwroty

  • Obietnica<Drukarka[]>

    Chrome w wersji 100 lub nowszej

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

submitJob()

Obietnica 
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

Przesyła zadanie do drukowania. Jeśli rozszerzenie nie znajduje się na liście zasad PrintingAPIExtensionsAllowlist, użytkownik jest proszony o zaakceptowanie zadania drukowania. Przed wersją Chrome 120 ta funkcja nie zwracała obietnicy.

Parametry

Zwroty

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100+

    Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onJobStatusChanged

chrome.printing.onJobStatusChanged.addListener(
  callback: function,
)

Zdarzenie jest wywoływane po zmianie stanu zadania. Jest ona wywoływana tylko w przypadku zadań utworzonych przez to rozszerzenie.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

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