browser.printing

Description

Utilisez l'API chrome.printing pour envoyer des travaux d'impression aux imprimantes installées sur un Chromebook.

Autorisations

printing

Disponibilité

Chrome 81 et versions ultérieures browser.* depuis Chrome 148 ChromeOS uniquement

Toutes les méthodes et tous les événements browser.printing nécessitent que vous déclariez l'autorisation "printing" dans le fichier manifeste de l'extension. Exemple :

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

Exemples

Les exemples ci-dessous illustrent l'utilisation de chacune des méthodes de l'espace de noms "printing". Ce code est copié ou basé sur api-samples/printing dans le dépôt GitHub extensions-samples.

cancelJob()

Cet exemple utilise le gestionnaire onJobStatusChanged pour masquer un bouton "Annuler" lorsque l'état jobStatus n'est ni PENDING, ni IN_PROGRESS. Notez que sur certains réseaux ou lorsqu'un Chromebook est connecté directement à l'imprimante, ces états peuvent passer trop rapidement pour que le bouton d'annulation soit visible assez longtemps pour être appelé. Il s'agit d'un exemple d'impression très simplifié.

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

Un seul exemple est utilisé pour ces fonctions, car l'obtention d'informations sur l'imprimante nécessite un ID d'imprimante, qui est récupéré en appelant getPrinters(). Cet exemple consigne le nom et la description de l'imprimante par défaut dans la console. Il s'agit d'une version simplifiée de l'exemple d'impression.

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

La méthode submitJob() nécessite trois éléments.

  • Structure ticket spécifiant les fonctionnalités de l'imprimante à utiliser. Si l'utilisateur doit sélectionner des fonctionnalités disponibles, vous pouvez les récupérer pour une imprimante spécifique à l'aide de getPrinterInfo().
  • Une structure SubmitJobRequest, qui spécifie l'imprimante à utiliser, ainsi que le fichier ou les données à imprimer. Cette structure contient une référence à la structure ticket.
  • Blob du fichier ou des données à imprimer.

L'appel de submitJob() déclenche l'affichage d'une boîte de dialogue demandant à l'utilisateur de confirmer l'impression. Utilisez PrintingAPIExtensionsAllowlist pour contourner la confirmation.

Il s'agit d'une version simplifiée de l'exemple d'impression. Notez que ticket est associé à la structure SubmitJobRequest (ligne 8) et que les données à imprimer sont converties en blob (ligne 10). L'obtention de l'ID de l'imprimante (ligne 1) est plus complexe dans l'exemple que ce qui est présenté ici.

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(submit>JobRequest, (response) = {
  if (response !== undefined) {
    console.log(response.status);
  }
  if (browser.runtime.lastError !== undefined) {
    console.log(browser.runtime.lastError.message);
  }
});

Impression sur rouleau

Cet exemple montre comment créer un ticket d'impression pour une impression continue (ou sur rouleau), souvent utilisée pour l'impression de reçus. L'objet submitJobRequest pour l'impression en rouleau est identique à celui de l'exemple submitJob().

Si vous devez modifier la valeur par défaut pour la découpe du papier, utilisez la touche vendor_ticket_item. (La valeur par défaut varie d'une imprimante à l'autre.) Pour modifier la valeur, fournissez un tableau avec un membre : un objet dont la valeur id est 'finishings'. La valeur peut être 'trim' pour les imprimantes qui coupent le rouleau à la fin de l'impression ou 'none' pour les imprimantes qui nécessitent de déchirer le papier.

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

Certaines imprimantes ne sont pas compatibles avec l'option "finishings". Pour déterminer si votre imprimante est compatible, appelez getPrinterInfo() et recherchez un "display_name" de "finishings/11".

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

Les valeurs de la clé media_size d'un ticket sont spécifiques à chaque imprimante. Pour sélectionner une taille appropriée, appelez getPrinterInfo(). L'objet GetPrinterResponse renvoyé contient un tableau des tailles de supports compatibles dans "media_size"."option". Choisissez une option dont la valeur "is_continuous_feed" est "true". Utilisez ses valeurs de hauteur et de largeur pour le ticket.

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

Types

GetPrinterInfoResponse

Propriétés

  • capabilities

    objet facultatif

    Fonctionnalités de l'imprimante au format CDD. La propriété est peut-être manquante.

  • État de l'imprimante.

JobStatus

État de la tâche d'impression.

Énumération

"PENDING"
La demande d'impression a été reçue par Chrome, mais n'a pas encore été traitée.

"IN_PROGRESS"
La tâche d'impression est envoyée pour impression.

"FAILED"
La tâche d'impression a été interrompue en raison d'une erreur.

"CANCELED"
La tâche d'impression a été annulée par l'utilisateur ou via l'API.

"PRINTED"
Le travail d'impression a été imprimé sans erreur.

Printer

Propriétés

  • description

    chaîne

    Description de l'imprimante lisible par l'humain.

  • id

    chaîne

    Identifiant de l'imprimante, qui doit être unique parmi les imprimantes de l'appareil.

  • isDefault

    booléen

    Indicateur qui indique si l'imprimante respecte les règles DefaultPrinterSelection. Notez que plusieurs imprimantes peuvent être signalées.

  • nom

    chaîne

    Nom de l'imprimante.

  • recentlyUsedRank

    number facultatif

    Valeur indiquant la date de la dernière utilisation de l'imprimante pour imprimer depuis Chrome. Plus la valeur est faible, plus l'imprimante a été utilisée récemment. La valeur minimale est 0. Une valeur manquante indique que l'imprimante n'a pas été utilisée récemment. Cette valeur est unique pour chaque imprimante.

  • source

    PrinterSource

    Source de l'imprimante (configurée par l'utilisateur ou par une règle).

  • uri

    chaîne

    URI de l'imprimante. Les extensions peuvent l'utiliser pour choisir l'imprimante de l'utilisateur.

PrinterSource

Source de l'imprimante.

Énumération

"USER"
L'imprimante a été ajoutée par l'utilisateur.

"RÈGLE"
L'imprimante a été ajoutée via une règle.

PrinterStatus

État de l'imprimante.

Énumération

"DOOR_OPEN"
La porte de l'imprimante est ouverte. L'imprimante accepte toujours les tâches d'impression.

"TRAY_MISSING"
Le bac de l'imprimante est manquant. L'imprimante accepte toujours les tâches d'impression.

"OUT_OF_INK"
L'imprimante n'a plus d'encre. L'imprimante accepte toujours les tâches d'impression.

"OUT_OF_PAPER"
L'imprimante n'a plus de papier. L'imprimante accepte toujours les tâches d'impression.

"OUTPUT_FULL"
La zone de sortie de l'imprimante (par exemple, le bac) est pleine. L'imprimante accepte toujours les tâches d'impression.

"PAPER_JAM"
L'imprimante présente un bourrage papier. L'imprimante accepte toujours les tâches d'impression.

"GENERIC_ISSUE"
Un problème générique. L'imprimante accepte toujours les tâches d'impression.

"STOPPED"
L'imprimante est arrêtée et n'imprime pas, mais elle accepte toujours les travaux d'impression.

"UNREACHABLE"
L'imprimante est inaccessible et n'accepte pas les travaux d'impression.

"EXPIRED_CERTIFICATE"
Le certificat SSL a expiré. L'imprimante accepte les tâches, mais elles échouent.

"AVAILABLE"
L'imprimante est disponible.

SubmitJobRequest

Propriétés

  • job

    PrintJob

    La tâche d'impression à envoyer. Les types de contenu acceptés sont "application/pdf" et "image/png". Le Cloud Job Ticket ne doit pas inclure les champs FitToPageTicketItem, PageRangeTicketItem et ReverseOrderTicketItem, car ils ne sont pas pertinents pour l'impression native. VendorTicketItem est facultatif. Tous les autres champs doivent être présents.

SubmitJobResponse

Propriétés

  • jobId

    chaîne facultatif

    ID de la tâche d'impression créée. Il s'agit d'un identifiant unique parmi toutes les tâches d'impression sur l'appareil. Si l'état n'est pas OK, jobId sera nul.

  • État de la demande.

SubmitJobStatus

État de la requête submitJob.

Énumération

"OK"
La demande de tâche d'impression envoyée est acceptée.

"USER_REJECTED"
La demande de tâche d'impression envoyée est refusée par l'utilisateur.

Propriétés

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Nombre maximal d'appels de getPrinterInfo par minute.

Valeur

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Nombre maximal d'appels de submitJob par minute.

Valeur

40

Méthodes

cancelJob()

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

Annule un job précédemment envoyé.

Paramètres

  • jobId

    chaîne

    ID de la tâche d'impression à annuler. Il doit s'agir du même ID que celui reçu dans un SubmitJobResponse.

Renvoie

  • Promise<void>

    Chrome 100+ browser.* depuis Chrome 148

getJobStatus()

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

Renvoie l'état de la tâche d'impression. Cet appel échouera avec une erreur d'exécution si le job d'impression avec l'jobId donné n'existe pas. jobId : ID de la tâche d'impression dont l'état doit être renvoyé. Il doit s'agir du même ID que celui reçu dans un SubmitJobResponse.

Paramètres

  • jobId

    chaîne

Renvoie

getPrinterInfo()

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

Renvoie l'état et les fonctionnalités de l'imprimante au format CDD. Cet appel échouera avec une erreur d'exécution si aucune imprimante avec l'ID indiqué n'est installée.

Paramètres

  • printerId

    chaîne

Renvoie

getPrinters()

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

Renvoie la liste des imprimantes disponibles sur l'appareil. Cela inclut les imprimantes ajoutées manuellement, les imprimantes d'entreprise et les imprimantes détectées.

Renvoie

  • Promise<Printer[]>

    Chrome 100+ browser.* depuis Chrome 148

submitJob()

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

Envoie la tâche pour impression. Si l'extension ne figure pas dans la règle PrintingAPIExtensionsAllowlist, l'utilisateur est invité à accepter la tâche d'impression. Avant Chrome 120, cette fonction ne renvoyait pas de promesse.

Paramètres

Renvoie

Événements

onJobStatusChanged

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

Événement déclenché lorsque l'état du job est modifié. Il n'est déclenché que pour les jobs créés par cette extension.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (jobId: string, status: JobStatus) =& gt;void