browser.printing

Beschrijving

Gebruik de chrome.printing API om afdruktaken naar printers te sturen die op de Chromebook zijn geïnstalleerd.

Rechten

printing

Beschikbaarheid

Chrome 81+ browser.* sinds Chrome 148 Alleen ChromeOS

Voor alle browser.printing-methoden en -gebeurtenissen moet je het recht "printing" definiëren in het extensiemanifest. Voorbeeld:

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

Voorbeelden

In de voorbeelden hieronder wordt elke methode in de naamruimte voor afdrukken gebruikt. Deze code is gekopieerd van of gebaseerd op de api-samples/printing in de Github-repository extensions-samples.

cancelJob()

In dit voorbeeld wordt de onJobStatusChanged-handler gebruikt om een annuleerknop te verbergen als de jobStatus niet PENDING of IN_PROGRESS is. Op sommige netwerken of als een Chromebook rechtstreeks op de printer is aangesloten, kunnen deze statussen te snel voorbijgaan om de annuleerknop lang genoeg zichtbaar te maken om te worden aangeroepen. Dit is een sterk vereenvoudigd afdrukvoorbeeld.

browser.printing.onJobStatusChanged.addListener((jobId, status) => {
  const cancelButton = document.getElementById("cancelButton");
  cancelButton.addEventListener('click', () => {
    browser.printing.cancelJob(jobId).then((response) => {
      if (response !== undefined) {
        console.log(response.status);
      }
      if (browser.runtime.lastError !== undefined) {
        console.log(browser.runtime.lastError.message);
      }
    });
  });
  if (status !== "PENDING" && status !== "IN_PROGRESS") {
    cancelButton.style.visibility = 'hidden';
  } else {
    cancelButton.style.visibility = 'visible';
  }
}

getPrinters() and getPrinterInfo()

Voor deze functies wordt één voorbeeld gebruikt, omdat je een printer-ID nodig hebt om printerinformatie op te halen. Deze ID wordt opgehaald door getPrinters() aan te roepen. In dit voorbeeld worden de naam en beschrijving van de standaardprinter geregistreerd in de console. Dit is een vereenvoudigde versie van het afdrukvoorbeeld.

​​const printers = await browser.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
  const printerInfo = await browser.printing.getPrinterInfo(printer.id);
  return printerInfo.isDefault;
}
console.log(`Default printer: ${defaultPrinter.name}.\n\t${defaultPrinter.description}`);

submitJob()

De methode submitJob() vereist 3 dingen.

  • Een ticket-structuur die aangeeft welke functies van de printer moeten worden gebruikt. Als de gebruiker een keuze moet maken uit de beschikbare mogelijkheden, kun je deze ophalen voor een specifieke printer met getPrinterInfo().
  • Een SubmitJobRequest-structuur die de te gebruiken printer en het bestand of de gegevens die moeten worden afgedrukt, specificeert. Deze structuur bevat een verwijzing naar de structuur ticket.
  • Een blob van het bestand of de gegevens die moeten worden afgedrukt.

Als je submitJob() aanroept, wordt er een dialoogvenster geactiveerd waarin de gebruiker wordt gevraagd het afdrukken te bevestigen. Gebruik de PrintingAPIExtensionsAllowlist om de bevestiging over te slaan.

Dit is een vereenvoudigde versie van het afdrukvoorbeeld. De ticket is gekoppeld aan de SubmitJobRequest-structuur (regel 8) en de gegevens die moeten worden afgedrukt, worden geconverteerd naar een blob (regel 10). De ID van de printer ophalen (regel 1) is in het voorbeeld ingewikkelder dan hier wordt getoond.

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'
    });
  }
};

browser.printing.submitJob(submitJobRequest, (response) => {
  if (response !== undefined) {
    console.log(response.status);
  }
  if (browser.runtime.lastError !== undefined) {
    console.log(browser.runtime.lastError.message);
  }
});

Rollen afdrukken

In dit voorbeeld wordt getoond hoe je een printerticket maakt voor continu afdrukken (of afdrukken op rol), wat vaak wordt gebruikt voor het afdrukken van bonnen. Het submitJobRequest-object voor rolprinten is hetzelfde als het object dat wordt getoond voor het voorbeeld submitJob().

Als je de standaardwaarde voor papier snijden wilt wijzigen, gebruik je de toets vendor_ticket_item. (De standaardinstelling verschilt per printer.) Als je de waarde wilt wijzigen, voer je een matrix met één lid in: een object waarvan de id 'finishings' is. De waarde kan 'trim' zijn voor printers die de rol aan het einde van het afdrukken afsnijden of 'none' voor printers waarbij de afdruktaak moet worden afgescheurd.

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

Sommige printers ondersteunen de optie "finishings" niet. Als je wilt nagaan of je printer dit doet, bel je getPrinterInfo() en zoek je naar een "display_name" of "finishings/11".

"vendor_capability": [
  {
    "display_name": "finishings/11",
    "id": "finishings/11",
    "type": "TYPED_VALUE",
    "typed_value_cap": {
      "value_type": "BOOLEAN"
    }
  },
  ...
]

De waarden in de sleutel media_size van een ticket zijn specifiek voor elke printer. Selecteer een geschikt formaat getPrinterInfo(). De geretourneerde GetPrinterResponse bevat een matrix met ondersteunde mediaformaten bij "media_size"."option". Kies een optie waarvan de waarde "is_continuous_feed" waar is. Gebruik de hoogte- en breedtewaarden voor het ticket.

"media_size": {
  "option": [
  {
    "custom_display_name": "",
    "is_continuous_feed": true,
    "max_height_microns": 2000000,
    "min_height_microns": 25400,
    "width_microns": 50800
  },
  ...
  ]
}

Typen

GetPrinterInfoResponse

Eigenschappen

  • capabilities

    object optioneel

    Printermogelijkheden in CDD-indeling. De property ontbreekt misschien.

  • status

    PrinterStatus

    De status van de printer.

JobStatus

Status van de afdruktaak.

Enum

PENDING
De afdruktaak is ontvangen aan de Chrome-kant, maar is nog niet verwerkt.

IN_PROGRESS
De afdruktaak is verstuurd om te worden afgedrukt.

FAILED
De afdruktaak is onderbroken vanwege een fout.

CANCELED
De afdruktaak is geannuleerd door de gebruiker of via de API.

PRINTED
De afdruktaak is zonder fouten afgedrukt.

Printer

Eigenschappen

  • beschrijving

    tekenreeks

    De door mensen leesbare beschrijving van de printer.

  • id

    tekenreeks

    De ID van de printer. Deze is gegarandeerd uniek voor printers op het apparaat.

  • isDefault

    booleaans

    De markering die aangeeft of de printer voldoet aan de regels van DefaultPrinterSelection. Er kunnen meerdere printers worden gemarkeerd.

  • name

    tekenreeks

    De naam van de printer.

  • recentlyUsedRank

    number optioneel

    De waarde die aangeeft hoe recent de printer is gebruikt om af te drukken vanuit Chrome. Hoe lager de waarde, hoe recenter de printer is gebruikt. De minimumwaarde is 0. Als er geen waarde is, is de printer niet recent gebruikt. Deze waarde is gegarandeerd uniek voor alle printers.

  • source

    PrinterSource

    De bron van de printer (gebruiker of beleid ingesteld).

  • uri

    tekenreeks

    De printer-URI. Extensies kunnen dit gebruiken om de printer voor de gebruiker te kiezen.

PrinterSource

De bron van de printer.

Enum

USER
De printer is toegevoegd door de gebruiker.

POLICY
De printer is toegevoegd via beleid.

PrinterStatus

De status van de printer.

Enum

DOOR_OPEN
De klep van de printer staat open. De printer accepteert nog steeds afdruktaken.

TRAY_MISSING
De lade van de printer ontbreekt. De printer accepteert nog steeds afdruktaken.

OUT_OF_INK
De inkt van de printer is op. De printer accepteert nog steeds afdruktaken.

OUT_OF_PAPER
Het papier van de printer is op. De printer accepteert nog steeds afdruktaken.

"OUTPUT_FULL"
Het uitvoergebied van de printer (bijvoorbeeld de lade) is vol. De printer accepteert nog steeds afdruktaken.

PAPER_JAM
Het papier is vastgelopen in de printer. De printer accepteert nog steeds afdruktaken.

GENERIC_ISSUE
Een algemeen probleem. De printer accepteert nog steeds afdruktaken.

STOPPED
De printer is gestopt en drukt niet af, maar accepteert nog wel afdruktaken.

UNREACHABLE
De printer is onbereikbaar en accepteert geen afdruktaken.

EXPIRED_CERTIFICATE
Het SSL-certificaat is verlopen. De printer accepteert taken, maar deze mislukken.

AVAILABLE
De printer is beschikbaar.

SubmitJobRequest

Eigenschappen

  • baan

    PrintJob

    De afdruktaak die moet worden ingediend. Ondersteunde contenttypen zijn application/pdf en image/png. De Cloud-taakticket mag de velden FitToPageTicketItem, PageRangeTicketItem en ReverseOrderTicketItem niet bevatten, omdat deze niet relevant zijn voor systeemeigen afdrukken. VendorTicketItem is optioneel. Alle andere velden moeten aanwezig zijn.

SubmitJobResponse

Eigenschappen

  • jobId

    tekenreeks optioneel

    De ID van de gemaakte afdruktaak. Dit is een unieke ID voor alle afdruktaken op het apparaat. Als de status niet OK is, is jobId null.

  • De status van het verzoek.

SubmitJobStatus

De status van het verzoek van submitJob.

Enum

OK
Het verzoek voor de afdruktaak is geaccepteerd.

"USER_REJECTED"
Het verzoek voor de verzonden afdruktaak is geweigerd door de gebruiker.

Eigenschappen

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Het maximale aantal keren dat getPrinterInfo per minuut kan worden aangeroepen.

Waarde

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Het maximale aantal keren dat submitJob per minuut kan worden aangeroepen.

Waarde

40

Methoden

cancelJob()

browser.printing.cancelJob(
  jobId: string,
): Promise<void>

Annuleert een eerder ingediende taak.

Parameters

  • jobId

    tekenreeks

    De ID van de afdruktaak die moet worden geannuleerd. Dit moet dezelfde ID zijn als de ID die je hebt gekregen in een SubmitJobResponse.

Retourzendingen

  • Promise<void>

    Chrome 100+ browser.* sinds Chrome 148

getJobStatus()

Chrome 135+ browser.* sinds Chrome 148 
browser.printing.getJobStatus(
  jobId: string,
): Promise<JobStatus>

Retourneert de status van de afdruktaak. Deze aanroep mislukt met een runtimefout als de afdruktaak met de opgegeven jobId niet bestaat. jobId: De ID van de afdruktaak waarvan de status moet worden geretourneerd. Dit moet dezelfde ID zijn als de ID die je hebt gekregen in een SubmitJobResponse.

Parameters

  • jobId

    tekenreeks

Retourzendingen

getPrinterInfo()

browser.printing.getPrinterInfo(
  printerId: string,
): Promise<GetPrinterInfoResponse>

Retourneert de status en mogelijkheden van de printer in CDD-indeling. Deze aanroep mislukt met een runtimefout als er geen printers met de opgegeven ID zijn geïnstalleerd.

Parameters

  • printerId

    tekenreeks

Retourzendingen

getPrinters()

browser.printing.getPrinters(): Promise<Printer[]>

Retourneert de lijst met beschikbare printers op het apparaat. Dit omvat handmatig toegevoegde, zakelijke en gevonden printers.

Retourzendingen

  • Promise<Printer[]>

    Chrome 100+ browser.* sinds Chrome 148

submitJob()

browser.printing.submitJob(
  request: SubmitJobRequest,
): Promise<SubmitJobResponse>

Dient de taak in voor afdrukken. Als de extensie niet wordt vermeld in het beleid PrintingAPIExtensionsAllowlist, wordt de gebruiker gevraagd de afdruktaak te accepteren. Vóór Chrome 120 retourneerde deze functie geen promise.

Parameters

Retourzendingen

Evenementen

onJobStatusChanged

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

Gebeurtenis die wordt geactiveerd als de status van de taak wordt gewijzigd. Dit wordt alleen geactiveerd voor de taken die door deze extensie zijn gemaakt.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

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