chrome.printing

Ważne: ten interfejs API działa tylko w ChromeOS.

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 wersje Tylko w 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 extensions-samples-printing lub jest na nim oparty.

cancelJob()

W tym przykładzie używany jest obciążnik onJobStatusChanged, aby ukryć przycisk „Anuluj”, gdy jobStatus nie jest równe PENDING ani IN_PROGRESS. Pamiętaj, że w niektórych sieciach lub gdy Chromebook jest połączony bezpośrednio z drukarką te stany mogą się zmieniać zbyt szybko, aby przycisk anulowania był widoczny przez wystarczająco długi czas, aby można było go wywołać. To bardzo 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()

W przypadku tych funkcji użyto jednego przykładu, ponieważ uzyskanie informacji o drukarce wymaga identyfikatora drukarki, który można pobrać, wywołując funkcję getPrinters(). W tym przykładzie do konsoli zapisywane są nazwa i opis domyślnego drukarki. To 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, która określa drukarkę do użycia oraz plik lub datę drukowania. 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. Aby pominąć potwierdzenie, użyj PrintingAPIExtensionsAllowlist.

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ć zlecenie drukowania ciągłego (lub z rolki), które jest często używane do drukowania paragonów. Obiekt submitJobRequest do drukowania z rolki jest taki sam jak w przykładzie 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). Jeśli jest podany, ten klucz musi być tablicą z jednym elementem: obiektem, którego wartość id to 'finishings'. Wartość może być 'trim' w przypadku drukarek, które tną rolkę po zakończeniu drukowania, lub 'none' w przypadku drukarek, które wymagają oderwania 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, zadzwoń pod numer 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 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

• możliwości

  object opcjonalne

  Możliwości drukarki w formacie CDD. Może brakować właściwości.

• status

  PrinterStatus

  Stan drukarki.

JobStatus

Stan zadania drukowania.

Typ wyliczeniowy

„PENDING” (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.

„ANNULLED” (ANNULLED – anulowane)
Zadanie drukowania zostało anulowane przez użytkownika lub za pomocą interfejsu API.

„WYDRUKOWANO”
Zadanie 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ć unikalny wśród wszystkich drukarek na urządzeniu.

• isDefault

  wartość logiczna

  Flaga, która wskazuje, czy drukarka spełnia reguły DefaultPrinterSelection. Pamiętaj, że może zostać oznaczonych kilka drukarek.

• nazwa

  ciąg znaków

  Nazwa drukarki.

• recentlyUsedRank

  number opcjonalny

  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. Minimalna wartość to 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 (konfigurowany użytkownik lub zasady).

• uri

  ciąg znaków

  Identyfikator URI drukarki. Rozszerzenia mogą używać tego parametru do wyboru drukarki dla użytkownika.

PrinterSource

Źródło drukarki.

Typ wyliczeniowy

„USER”
Drukarka została dodana przez użytkownika.

"POLICY"
Drukarka została dodana na podstawie zasad.

PrinterStatus

Stan drukarki.

Typ wyliczeniowy

"DOOR_OPEN"
Drzwiczki drukarki są otwarte. Drukarka nadal przyjmuje zadania drukowania.

"TRAY_MISSING"
Brak tacy 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 przyjmuje zadania drukowania.

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

„PAPER_JAM”
W drukarce zaciął się papier. Drukarka nadal przyjmuje zadania drukowania.

"GENERIC_ISSUE"
Niektóre ogólne problemy. Drukarka nadal przyjmuje zadania drukowania.

„STOPPED” (Zatrzymano)
Drukarka jest zatrzymana i nie drukuje, ale nadal przyjmuje zadania drukowania.

„UNREACHABLE” (nieosiągalna)
drukarka jest nieosiągalna i nie przyjmuje zadań drukowania.

"EXPIRED_CERTIFICATE"
Certyfikat SSL wygasł. Drukarka akceptuje zadania, ale nie są one realizowane.

„DOSTĘPNA”
Drukarka jest dostępna.

SubmitJobRequest

Właściwości

• zadanie

  PrintJob

  Zadanie drukowania, które ma zostać przesłane. 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

  string opcjonalny

  Identyfikator utworzonego zadania drukowania. Jest to unikalny identyfikator wśród wszystkich zadań drukowania na urządzeniu. Jeśli stan nie jest OK, identyfikator zadania będzie miał wartość null.

• status

  SubmitJobStatus

  Stan prośby.

SubmitJobStatus

Stan prośby submitJob.

Typ wyliczeniowy

„OK”
Wysłane żądanie wydruku zostało zaakceptowane.

"USER_REJECTED"
Użytkownik odrzucił wysłane żądanie wydruku.

Właściwości

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Maksymalna liczba wywołań funkcji getPrinterInfo na minutę.

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

  function opcjonalny

  Parametr callback ma postać:

  () => void

Zwroty

• Obietnica<void>

  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.

getJobStatus()

Obietnica Oczekuje

chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
)

Zwraca stan zadania drukowania. Jeśli zadanie drukowania o danym identyfikatorze jobId nie istnieje, wywołanie zakończy się błędem czasu wykonywania. jobId: identyfikator zadania drukowania, którego stan ma zostać zwrócony. Powinien to być ten sam identyfikator, który został otrzymany w ramach SubmitJobResponse.

Parametry

• jobId

  ciąg znaków

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (status: JobStatus) => void

  • status

    JobStatus

Zwroty

• Obietnica<JobStatus>

  Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy 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 ma zainstalowanych drukarek o danym identyfikatorze, wywołanie zakończy się błędem czasu wykonywania.

Parametry

• printerId

  ciąg znaków

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (response: GetPrinterInfoResponse) => void

  • odpowiedź

    GetPrinterInfoResponse

Zwroty

• Promise<GetPrinterInfoResponse>

  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.

getPrinters()

Obietnice

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

Zwraca listę dostępnych drukarek na urządzeniu. Dotyczy to drukarek dodanych ręcznie, firmowych i wykrytych.

Parametry

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (printers: Printer[]) => void

  • drukarki

    Drukarka[]

Zwroty

• Promise<Printer[]>

  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.

submitJob()

Obietnice

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

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

Parametry

• żądanie

  SubmitJobRequest

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (response: SubmitJobResponse) => void

  • odpowiedź

    SubmitJobResponse

Zwroty

• Obietnica<SubmitJobResponse>

  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 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 ma postać:

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

  • jobId

    ciąg znaków

  • status

    JobStatus