chrome.printing

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

Opis

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

Uprawnienia

printing

Dostępność

Chrome 81 i nowsze wersje

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ługi getPrinterInfo().
• Struktura SubmitJobRequest, która określa drukarkę, która ma zostać użyta, oraz plik lub datę wydrukowania. Ta struktura zawiera odniesienie do struktury ticket.
• 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). Gdy ten klucz jest uwzględniony, musi być tablicą z 1 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

  PrinterStatus

  Stan drukarki.

JobStatus

Stan zadania drukowania.

Enum

"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

  PrinterSource

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

Enum

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

"ZASADY"
Drukarka została dodana przez zasady.

PrinterStatus

Stan drukarki.

Enum

"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

  PrintJob

  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 ani VendorTicketItem, 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

  SubmitJobStatus

  Stan żądania.

SubmitJobStatus

Stan prośby submitJob.

Enum

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

Obietnica

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

Akcje powrotne

• Promise<void>

  Chrome 100 i nowsze wersje

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

Obietnica

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ź

    GetPrinterInfoResponse

Akcje powrotne

• Promise<GetPrinterInfoResponse>

  Chrome 100 i nowsze wersje

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

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 opcjonalnie

  Parametr callback wygląda tak:

  (printers: Printer[])=>void

  • drukarki

    Drukarka[]

Akcje powrotne

• Obietnica<drukarka[]>

  Chrome 100 i nowsze wersje

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

Obietnica

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ś

  SubmitJobRequest

• wywołanie zwrotne

  funkcja opcjonalnie

  Parametr callback wygląda tak:

  (response: SubmitJobResponse)=>void

  • odpowiedź

    SubmitJobResponse

Akcje powrotne

• Promise<SubmitJobResponse>

  Chrome 100 i nowsze wersje

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

Parametry

• wywołanie zwrotne

  funkcja

  Parametr callback wygląda tak:

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

  • jobId

    string,

  • status

    JobStatus