תיאור
משתמשים ב-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()
, מחפשים "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
הסטטוס של משימת ההדפסה.
ספירה
PENDING
עבודת ההדפסה התקבלה בצד של Chrome, אבל עדיין לא עברה עיבוד.
"IN_PROGRESS"
עבודת ההדפסה נשלחת להדפסה.
FAILED
ההדפסה הופסקה בגלל שגיאה.
CANCELED
משימת ההדפסה בוטלה על ידי המשתמש או באמצעות API.
"PRINTED"
משימת ההדפסה הודפסה ללא שגיאות.
Printer
מאפיינים
-
תיאור
מחרוזת
תיאור המדפסת שקריא לאנשים.
-
id [מזהה]
מחרוזת
המזהה של המדפסת. המזהה הזה ייחודי בין כל המדפסות במכשיר.
-
isDefault
בוליאני
הסימון שמראה אם המדפסת מתאימה לכללים של DefaultPrinterSelection. שימו לב: יכול להיות שיוצג סימון לגבי כמה מדפסות.
-
שם
מחרוזת
שם המדפסת.
-
recentlyUsedRank
מספר אופציונלי
הערך שמראה מתי לאחרונה נעשה שימוש במדפסת להדפסה מ-Chrome. ככל שהערך נמוך יותר, כך נעשה שימוש במדפסת לאחרונה. הערך המינימלי הוא 0. ערך חסר מציין שלא נעשה שימוש במדפסת לאחרונה. הערך הזה מובטח להיות ייחודי בין המדפסות.
-
source
המקור של המדפסת (המשתמש או כללי המדיניות שהוגדרו).
-
uri
מחרוזת
ה-URI של המדפסת. תוספים יכולים להשתמש בערך הזה כדי לבחור את המדפסת בשביל המשתמש.
PrinterSource
המקור של המדפסת.
ספירה
USER
המשתמש הוסיף מדפסת.
מדיניות
המדפסת נוספה דרך מדיניות.
PrinterStatus
הסטטוס של המדפסת.
ספירה
"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
.
ספירה
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,
)
האירוע מופעל כשסטטוס העבודה משתנה. האירוע הזה מופעל רק עבור המשימות שנוצרו על ידי התוסף הזה.