chrome.printing

חשוב: ה-API הזה פועל רק ב-ChromeOS.

תיאור

אפשר להשתמש ב-API של chrome.printing כדי לשלוח משימות הדפסה למדפסות שמותקנות ב-Chromebook.

הרשאות

printing

זמינות

Chrome 81 ומעלה ChromeOS בלבד

כל האירועים והשיטות של 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

  PrinterStatus

  הסטטוס של המדפסת.

JobStatus

הסטטוס של עבודת ההדפסה.

טיפוסים בני מנייה (enum)

"בהמתנה"
משימת ההדפסה התקבלה בצד של Chrome, אבל היא עוד לא עברה עיבוד.

"IN_PROGRESS"
משימת ההדפסה נשלחה להדפסה.

"נכשל"
משימת ההדפסה הופסקה עקב שגיאה כלשהי.

"בוטל"
משימת ההדפסה בוטלה על ידי המשתמש או באמצעות API.

"הדפסה"
עבודת ההדפסה הודפסה ללא שגיאות.

Printer

תכונות

• תיאור

  מחרוזת

  תיאור קריא (לבני אדם) של המדפסת.

• id

  מחרוזת

  מזהה המדפסת. מובטח שיהיה ייחודי בין המדפסות שבמכשיר.

• isDefault

  boolean

  הדגל שמציין אם המדפסת מתאימה לכללי DefaultPrinterSelection. לתשומת ליבכם: יכול להיות שיש כמה מדפסות שסומנו.

• name

  מחרוזת

  שם המדפסת.

• recentlyUsedRank

  מספר אופציונלי

  הערך שמראה מתי הייתה הפעם האחרונה שבה נעשה שימוש במדפסת להדפסה מ-Chrome. ככל שהערך נמוך יותר, כך נעשה שימוש במדפסת מהזמן האחרון. הערך המינימלי הוא 0. ערך חסר מציין שלא נעשה שימוש במדפסת לאחרונה. מובטח שיהיה ייחודי בין המדפסות.

• source

  PrinterSource

  מקור המדפסת (הגדרת המשתמש או מדיניות).

• uri

  מחרוזת

  ה-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

תכונות

• משימה

  PrintJob

  עבודת ההדפסה שמיועדת לשליחה. סוג התוכן היחיד הנתמך הוא " application/pdf", וכרטיס העבודה ב-Cloud לא יכול לכלול את השדות FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem ו-VendorTicketItem מכיוון שהם לא רלוונטיים להדפסה מקורית. כל שאר השדות חייבים להופיע.

SubmitJobResponse

תכונות

• jobId

  מחרוזת אופציונלי

  המזהה של עבודת ההדפסה שנוצרה. זהו מזהה ייחודי בין כל משימות ההדפסה במכשיר. אם הסטטוס לא תקין, ה-JobId יהיה null.

• status

  SubmitJobStatus

  סטטוס הבקשה.

SubmitJobStatus

הסטטוס של הבקשה submitJob.

טיפוסים בני מנייה (enum)

"אישור"
הבקשה שנשלחה לביצוע משימת הדפסה אושרה.

"USER_REJECTED"
הבקשה למשימת הדפסה שנשלחה נדחתה על ידי המשתמש.

תכונות

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

מספר הפעמים המקסימלי שאפשר להתקשר אל getPrinterInfo בדקה.

Value

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

מספר הפעמים המקסימלי שאפשר להתקשר אל submitJob בדקה.

Value

40

שיטות

cancelJob()

הבטחה

chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
)

ביטול המשימה שנשלחה בעבר.

פרמטרים

• jobId

  מחרוזת

  המזהה של עבודת ההדפסה שיש לבטל. הוא אמור להיות זהה למזהה שהתקבל ב-SubmitJobResponse.

• קריאה חוזרת (callback)

  פונקציה אופציונלי

  הפרמטר callback נראה כך:

  ()=>void

החזרות

• Promise<void>

  Chrome מגרסה 100 ואילך

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

getPrinterInfo()

הבטחה

chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

מחזירה את הסטטוס והיכולות של המדפסת בפורמט CDD. אם לא מותקנות מדפסות עם המזהה הנתון, הקריאה הזו תיכשל ותוצג שגיאת זמן ריצה.

פרמטרים

• printerId

  מחרוזת

• קריאה חוזרת (callback)

  פונקציה אופציונלי

  הפרמטר callback נראה כך:

  (response: GetPrinterInfoResponse)=>void

  • תשובה

    GetPrinterInfoResponse

החזרות

• Promise<GetPrinterInfoResponse>

  Chrome מגרסה 100 ואילך

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

getPrinters()

הבטחה

chrome.printing.getPrinters(
  callback?: function,
)

מחזירה את רשימת המדפסות הזמינות במכשיר. זה כולל מדפסות שנוספו באופן ידני, מדפסות ארגוניות ומדפסות שנמצאו.

פרמטרים

• קריאה חוזרת (callback)

  פונקציה אופציונלי

  הפרמטר callback נראה כך:

  (printers: Printer[])=>void

  • מדפסות

    מדפסת[]

החזרות

• הבטחה<מדפסת[]>

  Chrome מגרסה 100 ואילך

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

submitJob()

הבטחה

chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

שולח את העבודה להדפסה. אם התוסף לא מופיע במדיניות PrintingAPIExtensionsAllowlist, המשתמש מתבקש לאשר את משימת ההדפסה. לפני גרסה 120 של Chrome, הפונקציה הזו לא החזירה הבטחה.

פרמטרים

• בקשה

  SubmitJobRequest

• קריאה חוזרת (callback)

  פונקציה אופציונלי

  הפרמטר callback נראה כך:

  (response: SubmitJobResponse)=>void

  • תשובה

    SubmitJobResponse

החזרות

• Promise<SubmitJobResponse>

  Chrome מגרסה 100 ואילך

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

אירועים

onJobStatusChanged

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

האירוע הופעל כשהסטטוס של המשימה השתנה. אפשרות זו מופעלת רק עבור משימות שנוצרו על ידי התוסף הזה.

פרמטרים

• קריאה חוזרת (callback)

  פונקציה

  הפרמטר callback נראה כך:

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

  • jobId

    מחרוזת

  • status

    JobStatus