chrome.printing

.

Opis

Do wysyłania zadań drukowania do drukarek zainstalowanych na Chromebooku używaj interfejsu API chrome.printing.

Uprawnienia

printing

Dostępność

Chrome 81 i nowsze Tylko ChromeOS

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

    PrinterStatus

    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

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

    PrintJob

    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 i VendorTicketItem, 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.

  • 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()

Obietnica .
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()

Obietnica .
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 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()

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

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

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (printers: Printer[]) => void

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()

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

Zwroty

  • Promise&lt;SubmitJobResponse&gt;

    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.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

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