Description
Utilisez l'API chrome.printing
pour envoyer des tâches d'impression aux imprimantes installées sur le Chromebook.
Autorisations
printing
Garantie de disponibilité
Manifest
Toutes les méthodes et tous les événements chrome.printing
nécessitent de déclarer 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 dans l'espace de noms d'impression. Ce code est copié à partir du fichier api-samples/printing ou basé sur celui-ci, dans le dépôt GitHub Extensions-samples.
cancelJob()
Cet exemple utilise le gestionnaire onJobStatusChanged
pour masquer un bouton "Annuler" 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 assez 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 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 imprimé.
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.
- Une structure
ticket
spécifiant les fonctionnalités de l'imprimante à utiliser. Si l'utilisateur doit faire son choix parmi les fonctionnalités disponibles, vous pouvez les récupérer pour une imprimante spécifique à l'aide degetPrinterInfo()
. - Une structure
SubmitJobRequest
, qui spécifie l'imprimante à utiliser et le fichier ou la date à imprimer. Cette structure contient une référence à la structureticket
. - 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 contourner la confirmation.
Il s'agit d'une version simplifiée de l'exemple imprimé. Notez que ticket
est associé à la structure SubmitJobRequest
(ligne 8) et que les données à imprimer sont converties en blob (ligne 10). Obtenir l'ID de l'imprimante (ligne 1) est plus complexe 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'impression pour l'impression en continu (ou rouleau), souvent utilisé pour l'impression de reçus. L'objet submitJobRequest
pour l'impression au rouleau est identique à celui présenté dans l'exemple submitJob()
.
Si vous devez modifier la valeur par défaut pour le découpage du papier, utilisez la touche vendor_ticket_item
. (Le paramètre par défaut varie selon l'imprimante.) Lorsqu'elle est incluse, cette clé doit être 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 l'interruption de la tâche d'impression.
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 s'en charge, 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
Fonctionnalités de l'imprimante au format CDD L'établissement est peut-être manquant.
-
status
État de l'imprimante.
JobStatus
État de la tâche d'impression.
Enum
"PENDING"
La tâche d'impression a bien été reçue dans 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.
"IMPRIMÉE"
La tâche d'impression a été imprimée sans erreur.
Printer
Propriétés
-
description
chaîne
Description de l'imprimante dans un format lisible.
-
id
chaîne
Identifiant de l'imprimante (unique pour chaque imprimante de l'appareil).
-
isDefault
boolean
Indicateur indiquant si l'imprimante répond aux règles DefaultPrinterSelection. Notez que plusieurs imprimantes peuvent être signalées.
-
name
chaîne
Nom de l'imprimante.
-
recentlyUsedRank
numéro facultatif
Valeur indiquant la date d'utilisation récente 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
Source de l'imprimante (règle configurée par l'utilisateur ou la règle)
-
uri
chaîne
URI de l'imprimante. Il peut être utilisé par les extensions pour choisir l'imprimante pour l'utilisateur.
PrinterSource
Source de l'imprimante.
Enum
"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.
Enum
"DOOR_OPEN"
Le couvercle de l'imprimante est ouvert. L'imprimante accepte toujours les tâches d'impression.
"TRAY_MISSING"
Le bac de l'imprimante est introuvable. 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 est à court de papier. L'imprimante accepte toujours les tâches d'impression.
"OUTPUT_FULL"
La zone de sortie de l'imprimante est pleine. L'imprimante accepte toujours les tâches d'impression.
"PAPER_JAM"
L'imprimante est bloquée par 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.
"ARRÊTÉE"
L'imprimante est arrêtée et n'imprime pas des documents, mais elle accepte tout de même les tâches d'impression.
"UNREACHABLE"
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
Tâche d'impression à envoyer. Le seul type de contenu accepté est "application/pdf". La demande d'assistance Cloud Job ne doit pas inclure les champs
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
etVendorTicketItem
, car ils ne sont pas pertinents pour l'impression native. Tous les autres champs doivent être renseignés.
SubmitJobResponse
Propriétés
-
jobId
string facultatif
ID de la tâche d'impression créée. Il s'agit d'un identifiant unique parmi toutes les tâches d'impression de l'appareil. Si l'état n'est pas OK, la valeur JobId est nul.
-
status
État de la demande.
SubmitJobStatus
État de la requête submitJob
.
Enum
"OK"
La demande de tâche d'impression envoyée est acceptée.
"USER_REJECTED"
La requête de tâche d'impression envoyée a été rejetée par l'utilisateur.
Propriétés
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
Nombre maximal de fois que getPrinterInfo
peut être appelé par minute.
Valeur
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
Nombre maximal de fois que submitJob
peut être appelé par minute.
Valeur
40
Méthodes
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Annule le job précédemment envoyé.
Paramètres
-
jobId
chaîne
ID de la tâche d'impression à annuler. Il doit correspondre à l'ID reçu dans un
SubmitJobResponse
. -
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 100 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Renvoie l'état et les fonctionnalités de l'imprimante au format CDD. Cet appel échoue et renvoie une erreur d'exécution si aucune imprimante n'est installée avec l'ID indiqué.
Paramètres
-
printerId
chaîne
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(response: GetPrinterInfoResponse) => void
-
réponse
-
Renvoie
-
Promise<GetPrinterInfoResponse>
Chrome 100 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Affiche la liste des imprimantes disponibles sur l'appareil. Cela inclut les imprimantes ajoutées manuellement, d'entreprise et détectées.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(printers: Printer[]) => void
-
imprimantes
-
Renvoie
-
Promesse<Imprimante[]>
Chrome 100 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
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 aucune promesse.
Paramètres
-
request
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(response: SubmitJobResponse) => void
-
réponse
-
Renvoie
-
Promise<SubmitJobResponse>
Chrome 100 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
Événements
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
Événement déclenché lorsque l'état de la tâche est modifié. Ce déclencheur n'est déclenché que pour les tâches créées par cette extension.