תיאור
משתמשים ב-chrome.printing
API כדי לשלוח משימות הדפסה למדפסות שמותקנות ב-Chromebook.
הרשאות
printing
זמינות
כדי להשתמש בכל השיטות והאירועים של chrome.printing
, צריך להצהיר על ההרשאה "printing"
במניפסט התוסף. לדוגמה:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
דוגמאות
בדוגמאות הבאות מוסבר איך להשתמש בכל אחת מהשיטות במרחב השמות של ההדפסה. הקוד הזה מועתק מ-api-samples/printing במאגר extensions-samples ב-GitHub או מבוסס עליו.
cancelJob()
בדוגמה הזו נעשה שימוש ב-handler onJobStatusChanged
כדי להסתיר את הלחצן 'ביטול' אם הערך של jobStatus
הוא לא PENDING
ולא IN_PROGRESS
. שימו לב: ברשתות מסוימות או כש-Chromebook מחובר ישירות למדפסת, יכול להיות שהמצבים האלה יעברו מהר מדי, כך שהלחצן 'ביטול' לא יוצג מספיק זמן כדי שאפשר יהיה ללחוץ עליו. זוהי דוגמה פשוטה מאוד להדפסה.
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()
השתמשנו בדוגמה אחת לפונקציות האלה כי כדי לקבל מידע על מדפסת צריך מזהה מדפסת, שאפשר לאחזר באמצעות קריאה לפונקציה getPrinters()
. בדוגמה הזו, השם והתיאור של מדפסת ברירת המחדל נרשמים במסוף. זוהי גרסה פשוטה של דוגמת ההדפסה.
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()
השיטה submitJob()
דורשת שלושה דברים.
- מבנה
ticket
שמציין באילו יכולות של המדפסת יש להשתמש. אם המשתמש צריך לבחור מתוך היכולות הזמינות, אפשר לאחזר אותן עבור מדפסת ספציפית באמצעותgetPrinterInfo()
. - מבנה
SubmitJobRequest
, שמציין את המדפסת שבה יש להשתמש ואת הקובץ או התאריך להדפסה. המבנה הזה מכיל הפניה למבנהticket
. - בלוב של הקובץ או הנתונים להדפסה.
הפעלת הפונקציה submitJob()
תציג תיבת דו-שיח שבה המשתמש יתבקש לאשר את ההדפסה. אפשר להשתמש בPrintingAPIExtensionsAllowlist
כדי לדלג על האישור.
זוהי גרסה פשוטה של דוגמת ההדפסה. שימו לב שה-ticket
מצורף למבנה SubmitJobRequest
(שורה 8) והנתונים להדפסה מומרים ל-blob (שורה 10). השגת מזהה המדפסת (שורה 1) היא מורכבת יותר בדוגמה ממה שמוצג כאן.
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);
}
});
הדפסה בגליל
בדוגמה הזו מוצג איך ליצור כרטיס מדפסת להדפסה רציפה (או הדפסה בגליל), שמשמשת לעיתים קרובות להדפסת קבלות. אובייקט submitJobRequest
להדפסה בגליל זהה לזה שמוצג בדוגמה submitJob()
.
אם אתם צריכים לשנות את ערך ברירת המחדל לחיתוך נייר, משתמשים במקש vendor_ticket_item
. (ברירת המחדל משתנה ממדפסת למדפסת). כדי לשנות את הערך, צריך לספק מערך עם רכיב אחד: אובייקט שבו id
הוא 'finishings'
. הערך יכול להיות 'trim'
למדפסות שחותכות את הגליל בסיום ההדפסה או 'none'
למדפסות שדורשות לקרוע את משימת ההדפסה.
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}
}
};
חלק מהמדפסות לא תומכות באפשרות "finishings"
. כדי לבדוק אם המדפסת שלכם תומכת ב-getPrinterInfo()
, חפשו � of ."display_name"
"finishings/11"
"vendor_capability": [
{
"display_name": "finishings/11",
"id": "finishings/11",
"type": "TYPED_VALUE",
"typed_value_cap": {
"value_type": "BOOLEAN"
}
},
...
]
הערכים במפתח media_size
של כרטיס הם ספציפיים לכל מדפסת. כדי לבחור גודל מתאים, מתקשרים אל getPrinterInfo()
. הערך המוחזר GetPrinterResponse
מכיל מערך של גדלי מדיה נתמכים ב-"media_size"."option"
. בוחרים באפשרות שהערך שלה "is_continuous_feed"
הוא true. משתמשים בערכי הגובה והרוחב שלו בכרטיס.
"media_size": {
"option": [
{
"custom_display_name": "",
"is_continuous_feed": true,
"max_height_microns": 2000000,
"min_height_microns": 25400,
"width_microns": 50800
},
...
]
}
סוגים
GetPrinterInfoResponse
מאפיינים
-
יכולות
אובייקט אופציונלי
יכולות המדפסת בפורמט CDD. יכול להיות שהמאפיין חסר.
-
status
הסטטוס של המדפסת.
JobStatus
הסטטוס של עבודת ההדפסה.
Enum
PENDING
עבודת ההדפסה התקבלה בצד של Chrome, אבל עדיין לא עברה עיבוד.
IN_PROGRESS
עבודת ההדפסה נשלחת להדפסה.
FAILED
עבודת ההדפסה הופסקה בגלל שגיאה.
CANCELED
משימת ההדפסה בוטלה על ידי המשתמש או באמצעות API.
"PRINTED"
משימת ההדפסה הודפסה ללא שגיאות.
Printer
מאפיינים
-
תיאור
מחרוזת
תיאור המדפסת שקריא לאנשים.
-
id [מזהה]
מחרוזת
המזהה של המדפסת. המזהה הזה הוא ייחודי בין המדפסות במכשיר.
-
isDefault
בוליאני
הסימון שמראה אם המדפסת מתאימה לכללים של DefaultPrinterSelection. שימו לב: יכול להיות שיוצג סימון לגבי כמה מדפסות.
-
שם
מחרוזת
שם המדפסת.
-
recentlyUsedRank
מספר אופציונלי
הערך שמראה כמה זמן עבר מאז שהמדפסת הייתה בשימוש להדפסה מ-Chrome. ככל שהערך נמוך יותר, כך נעשה שימוש במדפסת לאחרונה. הערך המינימלי הוא 0. ערך חסר מציין שלא נעשה שימוש במדפסת לאחרונה. הערך הזה מובטח להיות ייחודי בין המדפסות.
-
source
המקור של המדפסת (המשתמש או כללי המדיניות שהוגדרו).
-
uri
מחרוזת
ה-URI של המדפסת. תוספים יכולים להשתמש בהגדרה הזו כדי לבחור את המדפסת בשביל המשתמש.
PrinterSource
המקור של המדפסת.
Enum
USER
המשתמש הוסיף מדפסת.
מדיניות
המדפסת נוספה באמצעות מדיניות.
PrinterStatus
הסטטוס של המדפסת.
Enum
"DOOR_OPEN"
הדלת של המדפסת פתוחה. המדפסת עדיין מקבלת משימות הדפסה.
"TRAY_MISSING"
המגש של המדפסת חסר. המדפסת עדיין מקבלת משימות הדפסה.
"OUT_OF_INK"
נגמר הדיו במדפסת. המדפסת עדיין מקבלת משימות הדפסה.
"OUT_OF_PAPER"
אזל הנייר במדפסת. המדפסת עדיין מקבלת משימות הדפסה.
OUTPUT_FULL
אזור הפלט של המדפסת (למשל מגש) מלא. המדפסת עדיין מקבלת משימות הדפסה.
"PAPER_JAM"
יש נייר תקוע במדפסת. המדפסת עדיין מקבלת משימות הדפסה.
"GENERIC_ISSUE"
בעיה כללית. המדפסת עדיין מקבלת משימות הדפסה.
'הופסקה'
המדפסת הופסקה והיא לא מדפיסה, אבל היא עדיין מקבלת משימות הדפסה.
UNREACHABLE"
לא ניתן להתחבר למדפסת והיא לא מקבלת משימות הדפסה.
EXPIRED_CERTIFICATE
פג התוקף של אישור ה-SSL. המדפסת מקבלת עבודות אבל הן נכשלות.
'זמין'
המדפסת זמינה.
SubmitJobRequest
מאפיינים
-
משימה
משימת ההדפסה שרוצים לשלוח. סוגי התוכן הנתמכים הם application/pdf ו-image/png. כרטיס העבודה ב-Cloud לא צריך לכלול את השדות
FitToPageTicketItem
,PageRangeTicketItem
ו-ReverseOrderTicketItem
כי הם לא רלוונטיים להדפסה מקומית. הערךVendorTicketItem
הוא אופציונלי. כל שאר השדות חייבים להיות נוכחים.
SubmitJobResponse
מאפיינים
-
jobId
מחרוזת אופציונלי
המזהה של עבודת ההדפסה שנוצרה. זהו מזהה ייחודי בין כל עבודות ההדפסה במכשיר. אם הסטטוס הוא לא OK, הערך של jobId יהיה null.
-
status
הסטטוס של הבקשה.
SubmitJobStatus
הסטטוס של הבקשה submitJob
.
Enum
OK
בקשת עבודת ההדפסה שנשלחה אושרה.
USER_REJECTED
המשתמש דחה את הבקשה לשליחת עבודת הדפסה.
מאפיינים
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
מספר הפעמים המקסימלי שאפשר להתקשר אל getPrinterInfo
בדקה.
ערך
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
מספר הפעמים המקסימלי שאפשר להתקשר אל submitJob
בדקה.
ערך
40
Methods
cancelJob()
chrome.printing.cancelJob(
jobId: string,
): Promise<void>
ביטול משימה שנשלחה קודם.
פרמטרים
-
jobId
מחרוזת
המזהה של משימת ההדפסה שרוצים לבטל. המזהה הזה צריך להיות זהה למזהה שמתקבל ב-
SubmitJobResponse
.
החזרות
-
Promise<void>
Chrome 100 ואילך
getJobStatus()
chrome.printing.getJobStatus(
jobId: string,
): Promise<JobStatus>
הפונקציה מחזירה את הסטטוס של משימת ההדפסה. הקריאה הזו תיכשל עם שגיאת זמן ריצה אם משימת ההדפסה עם הערך jobId
שצוין לא קיימת. jobId
: המזהה של עבודת ההדפסה שרוצים לקבל את הסטטוס שלה. המזהה הזה צריך להיות זהה למזהה שמתקבל ב-SubmitJobResponse
.
פרמטרים
-
jobId
מחרוזת
החזרות
-
Promise<JobStatus>
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
): Promise<GetPrinterInfoResponse>
הפונקציה מחזירה את הסטטוס והיכולות של המדפסת בפורמט CDD. הקריאה הזו תיכשל עם שגיאת זמן ריצה אם לא מותקנות מדפסות עם המזהה הנתון.
פרמטרים
-
printerId
מחרוזת
החזרות
-
Promise<GetPrinterInfoResponse>
Chrome 100 ואילך
getPrinters()
chrome.printing.getPrinters(): Promise<Printer[]>
מחזירה את רשימת המדפסות הזמינות במכשיר. הפעולה הזו כוללת מדפסות שהוספתם באופן ידני, מדפסות ארגוניות ומדפסות שזוהו.
החזרות
-
Promise<Printer[]>
Chrome 100 ואילך
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
): Promise<SubmitJobResponse>
שליחת העבודה להדפסה. אם התוסף לא מופיע במדיניות PrintingAPIExtensionsAllowlist
, המשתמש יתבקש לאשר את משימת ההדפסה.
לפני Chrome 120, הפונקציה הזו לא החזירה הבטחה.
פרמטרים
-
בקשה
החזרות
-
Promise<SubmitJobResponse>
Chrome 100 ואילך
אירועים
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
האירוע מופעל כשסטטוס העבודה משתנה. האירוע הזה מופעל רק עבור המשימות שנוצרו על ידי התוסף הזה.