chrome.printing

Description

Utilisez l'API chrome.printing pour envoyer des tâches d'impression aux imprimantes installées sur le Chromebook.

Autorisations

printing

Disponibilité

Chrome (version 81 ou ultérieure) ChromeOS uniquement

Tous les événements et méthodes chrome.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 d'impression. Ce code est copié depuis ou basé sur api-samples/printing dans le dépôt GitHub extensions-samples.

cancelJob()

Cet exemple utilise le gestionnaire onJobStatusChanged pour masquer une instruction "cancel" (annuler). bouton lorsque jobStatus n'est ni PENDING, ni IN_PROGRESS. Notez que sur certains réseaux ou lorsqu'un Chromebook est directement connecté à l'imprimante, ces états peuvent passer trop rapidement pour que le bouton d'annulation reste visible suffisamment longtemps pour être appelé. Il s'agit d'un exemple d'impression considérablement simplifié.

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

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

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

  • Structure ticket spécifiant les fonctionnalités à utiliser de l'imprimante. Si l'utilisateur doit sélectionner les fonctionnalités disponibles, vous pouvez les récupérer pour une imprimante spécifique à l'aide de getPrinterInfo().
  • Structure SubmitJobRequest, qui spécifie l'imprimante à utiliser, ainsi que le fichier ou la date à 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 une boîte de dialogue demandant à l'utilisateur de confirmer l'impression. Utilisez PrintingAPIExtensionsAllowlist pour ignorer 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). Il est plus compliqué d'obtenir l'identifiant de l'imprimante (ligne 1) dans cet exemple que dans cet exemple.

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

Impression au rouleau

Cet exemple montre comment créer un ticket d'imprimante pour l'impression en continu (ou par rouleau), souvent utilisé pour imprimer des reçus. L'objet submitJobRequest pour l'impression par rouleau est identique à celui présenté dans l'exemple submitJob().

Si vous devez modifier la valeur par défaut pour la coupe de papier, utilisez la clé 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 le 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 dont la tâche d'impression doit être arrachée.

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 savoir 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(). Le GetPrinterResponse renvoyé contient un tableau des tailles de contenus multimédias 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 billet.

"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

    Capacités de l'imprimante au format CDD. L'établissement est peut-être manquant.

  • État de l'imprimante.

JobStatus

État de la tâche d'impression.

Énumération

"PENDING"
La tâche d'impression a bien été reçue côté Chrome, mais n'a pas encore été traitée.

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

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

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

"IMPRIMÉ"
La tâche d'impression a été imprimée sans erreur.

Printer

Propriétés

  • description

    chaîne

    Description lisible de l'imprimante.

  • id

    chaîne

    Identifiant de l'imprimante soient uniques parmi les imprimantes de l'appareil.

  • isDefault

    booléen

    Indicateur indiquant si l'imprimante correspond aux règles DefaultPrinterSelection. Notez que plusieurs imprimantes peuvent être signalées.

  • nom

    chaîne

    Nom de l'imprimante.

  • recentlyUsedRank

    numéro facultatif

    Valeur indiquant la dernière date d'utilisation de l'imprimante pour l'impression 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. L'unicité de cette valeur est garantie pour toutes les imprimantes.

  • source

    PrinterSource

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

  • uri

    chaîne

    URI de l'imprimante. Les extensions peuvent s'en servir pour choisir l'imprimante pour l'utilisateur.

PrinterSource

Source de l'imprimante.

Énumération

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

"POLICY"
L'imprimante a été ajoutée via une règle.

PrinterStatus

État de l'imprimante.

Énumération

"DOOR_OPEN"
Le couvercle de l'imprimante est ouvert. L'imprimante accepte toujours les tâches d'impression.

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

"OUT_OF_INK"
L'imprimante est à court 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 (le bac, par exemple) 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"
Problème d'ordre général. L'imprimante accepte toujours les tâches d'impression.

"STOPPED"
L'imprimante est arrêtée et ne lance pas d'impression, mais elle accepte toujours les tâches d'impression.

"ACCESSABLE"
L'imprimante est inaccessible et n'accepte pas les tâches d'impression.

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

"AVAILABLE"
L'imprimante est disponible.

SubmitJobRequest

Propriétés

  • job

    PrintJob

    Tâche d'impression à envoyer. Le seul type de contenu compatible est "application/pdf", et le Cloud Job Ticket ne doit pas inclure les champs FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem et VendorTicketItem, car ils ne sont pas pertinents pour l'impression native. Tous les autres champs doivent être présents.

SubmitJobResponse

Propriétés

  • jobId

    chaîne facultatif

    Identifiant 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 a été acceptée.

"USER_REJECTED"
La demande de tâche d'impression envoyée a été 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()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
)

Annule le job envoyé précédemment.

Paramètres

  • jobId

    chaîne

    Identifiant de la tâche d'impression à annuler. Il doit s'agir de l'ID que vous avez reçu dans une SubmitJobResponse.

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 100 et versions ultérieures

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getPrinterInfo()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

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

Paramètres

Renvoie

  • Promise&lt;GetPrinterInfoResponse&gt;

    Chrome 100 et versions ultérieures

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getPrinters()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.printing.getPrinters(
  callback?: function,
)

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

Paramètres

  • rappel

    function facultatif

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

    (printers: Printer[]) => void

Renvoie

  • Promesse<Imprimante[]>

    Chrome 100 et versions ultérieures

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

submitJob()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

Envoie le job 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 aucune promesse.

Paramètres

Renvoie

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100 et versions ultérieures

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

Événements

onJobStatusChanged

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

Événement déclenché lorsque l'état de la tâche est modifié. Il n'est déclenché que pour les jobs créés par cette extension.

Paramètres

  • rappel

    fonction

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

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