תיאור
אפשר להשתמש ב-API של chrome.printing
כדי לשלוח משימות הדפסה למדפסות שמותקנות ב-Chromebook.
הרשאות
printing
זמינות
כל האירועים והשיטות של chrome.printing
מחייבים להצהיר על ההרשאה "printing"
במניפסט של התוסף. למשל:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
דוגמאות
בדוגמאות הבאות אפשר לראות את השימוש בכל אחת מהשיטות במרחב השמות של ההדפסה. הקוד הזה מועתק מ-api-samples/printing במאגר של 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}`);
sendJob()
השיטה submitJob()
דורשת שלושה דברים.
- מבנה
ticket
שמציין את היכולות של המדפסת שבהן רוצים להשתמש. אם המשתמש צריך לבחור מתוך היכולות הזמינות, אפשר לאחזר אותן עבור מדפסת ספציפית באמצעותgetPrinterInfo()
. - מבנה
SubmitJobRequest
, שמציין את המדפסת שבה יש להשתמש ואת הקובץ או התאריך להדפסה. המבנה הזה מכיל הפניה למבנהticket
. - blob של הקובץ או הנתונים להדפסה.
קריאה ל-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()
ולחפש את הערך "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
תכונות
-
capabilities
אובייקט אופציונלי
יכולות של מדפסת בפורמט CDD. יכול להיות שהנכס חסר.
-
status
הסטטוס של המדפסת.
JobStatus
הסטטוס של עבודת ההדפסה.
טיפוסים בני מנייה (enum)
"בהמתנה"
משימת ההדפסה התקבלה בצד של Chrome, אבל היא עוד לא עברה עיבוד.
"IN_PROGRESS"
משימת ההדפסה נשלחה להדפסה.
"נכשל"
משימת ההדפסה הופסקה עקב שגיאה כלשהי.
"בוטל"
משימת ההדפסה בוטלה על ידי המשתמש או באמצעות API.
"הדפסה"
עבודת ההדפסה הודפסה ללא שגיאות.
Printer
תכונות
-
תיאור
string
תיאור קריא (לבני אדם) של המדפסת.
-
id
string
מזהה המדפסת. מובטח שיהיה ייחודי בין המדפסות שבמכשיר.
-
isDefault
boolean
הדגל שמציין אם המדפסת מתאימה לכללי DefaultPrinterSelection. לתשומת ליבכם: יכול להיות שיש כמה מדפסות שסומנו.
-
name
string
שם המדפסת.
-
recentlyUsedRank
מספר אופציונלי
הערך שמראה מתי הייתה הפעם האחרונה שבה נעשה שימוש במדפסת להדפסה מ-Chrome. ככל שהערך נמוך יותר, כך נעשה שימוש במדפסת מהזמן האחרון. הערך המינימלי הוא 0. ערך חסר מציין שלא נעשה שימוש במדפסת לאחרונה. מובטח שיהיה ייחודי בין המדפסות.
-
source
מקור המדפסת (הגדרת המשתמש או מדיניות).
-
uri
string
ה-URI של המדפסת. תוספים יכולים להשתמש באפשרות הזו כדי לבחור את המדפסת עבור המשתמש.
PrinterSource
מקור המדפסת.
טיפוסים בני מנייה (enum)
"USER"
המדפסת נוספה על ידי המשתמש.
"POLICY"
המדפסת נוספה באמצעות מדיניות.
PrinterStatus
הסטטוס של המדפסת.
טיפוסים בני מנייה (enum)
"DOOR_OPEN"
הדלת של המדפסת פתוחה. המדפסת עדיין מקבלת משימות הדפסה.
"TRAY_MISSING"
מגש המדפסת חסר. המדפסת עדיין מקבלת משימות הדפסה.
"OUT_OF_INK"
הדיו במדפסת נגמר. המדפסת עדיין מקבלת משימות הדפסה.
"OUT_OF_PAPER"
הנייר במדפסת נגמר. המדפסת עדיין מקבלת משימות הדפסה.
"OUTPUT_Full"
אזור הפלט של המדפסת (למשל המגש) מלא. המדפסת עדיין מקבלת משימות הדפסה.
"PAPER_JAM"
במדפסת יש חסימת נייר. המדפסת עדיין מקבלת משימות הדפסה.
"GENEric_ISSUE"
בעיה כללית. המדפסת עדיין מקבלת משימות הדפסה.
"STOPPED"
המדפסת הפסיקה ולא מדפיסה, אבל עדיין מקבלת משימות הדפסה.
"UNREACHABLE"
אין גישה למדפסת והיא לא מקבלת משימות הדפסה.
"EXPIRED_CERTIFICATE"
פג התוקף של אישור ה-SSL. המדפסת מקבלת משימות אבל הן נכשלות.
"AVAILABLE"
המדפסת זמינה.
SubmitJobRequest
תכונות
-
משימה
עבודת ההדפסה שמיועדת לשליחה. סוג התוכן היחיד הנתמך הוא " application/pdf", וכרטיס העבודה ב-Cloud לא יכול לכלול את השדות
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
ו-VendorTicketItem
מכיוון שהם לא רלוונטיים להדפסה מקורית. כל שאר השדות חייבים להופיע.
SubmitJobResponse
תכונות
-
jobId
מחרוזת אופציונלי
המזהה של עבודת ההדפסה שנוצרה. זהו מזהה ייחודי בין כל משימות ההדפסה במכשיר. אם הסטטוס לא תקין, ה-JobId יהיה null.
-
status
סטטוס הבקשה.
SubmitJobStatus
הסטטוס של הבקשה submitJob
.
טיפוסים בני מנייה (enum)
"אישור"
הבקשה שנשלחה לביצוע משימת הדפסה אושרה.
"USER_REJECTED"
הבקשה למשימת הדפסה שנשלחה נדחתה על ידי המשתמש.
תכונות
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
מספר הפעמים המקסימלי שאפשר להתקשר אל getPrinterInfo
בדקה.
ערך
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
מספר הפעמים המקסימלי שאפשר להתקשר אל submitJob
בדקה.
ערך
40
שיטות
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
ביטול המשימה שנשלחה בעבר.
פרמטרים
-
jobId
string
המזהה של עבודת ההדפסה שיש לבטל. הוא אמור להיות זהה למזהה שהתקבל ב-
SubmitJobResponse
. -
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome מגרסה 100 ואילךיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
מחזירה את הסטטוס והיכולות של המדפסת בפורמט CDD. אם לא מותקנות מדפסות עם המזהה הנתון, הקריאה הזו תיכשל ותוצג שגיאת זמן ריצה.
פרמטרים
-
printerId
string
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(response: GetPrinterInfoResponse) => void
-
תשובה
-
החזרות
-
Promise<GetPrinterInfoResponse>
Chrome מגרסה 100 ואילךיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
מחזירה את רשימת המדפסות הזמינות במכשיר. זה כולל מדפסות שנוספו באופן ידני, מדפסות ארגוניות ומדפסות שנמצאו.
פרמטרים
החזרות
-
הבטחה<מדפסת[]>
Chrome מגרסה 100 ואילךיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
שולח את העבודה להדפסה. אם התוסף לא מופיע במדיניות PrintingAPIExtensionsAllowlist
, המשתמש מתבקש לאשר את משימת ההדפסה.
לפני גרסה 120 של Chrome, הפונקציה הזו לא החזירה הבטחה.
פרמטרים
-
בקשה
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(response: SubmitJobResponse) => void
-
תשובה
-
החזרות
-
Promise<SubmitJobResponse>
Chrome מגרסה 100 ואילךיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
אירועים
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
האירוע הופעל כשהסטטוס של המשימה השתנה. אפשרות זו מופעלת רק עבור משימות שנוצרו על ידי התוסף הזה.