chrome.printing

תיאור

אפשר להשתמש ב-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() ו-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()‎

ל-method 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

מאפיינים

  • יכולות

    אובייקט אופציונלי

    יכולות מדפסת בפורמט CDD. יכול להיות שהנכס חסר.

  • status

    PrinterStatus

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

JobStatus

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

Enum

'בהמתנה'
משימה להדפסה התקבלה בצד Chrome אבל עדיין לא עובדו.

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

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

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

'דפוס'
משימת ההדפסה הודפסה ללא שגיאות.

Printer

מאפיינים

  • תיאור

    מחרוזת

    התיאור הקריא של המדפסת.

  • id [מזהה]

    מחרוזת

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

  • isDefault

    בוליאני

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

  • שם

    מחרוזת

    שם המדפסת.

  • 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"
המדפסת מופסקת, לא מדפיסה אבל עדיין מקבלת משימות הדפסה.

'לא ניתנת להתאמה'
לא ניתן לגשת למדפסת והיא לא מקבלת משימות הדפסה.

"EXPIRED_CERTIFICATE"
פג התוקף של אישור ה-SSL. המדפסת מקבלת משימות אבל הן נכשלות.

'זמינה'
המדפסת זמינה.

SubmitJobRequest

מאפיינים

  • משימה

    PrintJob

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

SubmitJobResponse

מאפיינים

  • jobId

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

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

  • סטטוס הבקשה.

SubmitJobStatus

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

Enum

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

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

מאפיינים

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

ערך

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

ערך

40

שיטות

cancelJob()

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

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

פרמטרים

  • jobId

    מחרוזת

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 100+

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

getPrinterInfo()

הבטחה 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

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

פרמטרים

החזרות

  • Promise&lt;GetPrinterInfoResponse&gt;

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

    יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getPrinters()

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

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

פרמטרים

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

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

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

    (printers: Printer[]) => void

החזרות

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

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

    יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

submitJob()

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

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

פרמטרים

החזרות

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100+

    יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

onJobStatusChanged

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

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

פרמטרים

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

    פונקציה

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

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