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() 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()

ל-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. המדפסת מקבלת משימות אבל הן נכשלות.

"AVAILABLE"
המדפסת זמינה.

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()

הבטחה 
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+

    הבטחות נתמכות רק במניפסט מגרסה 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, המשתמש יתבקש לאשר את משימת ההדפסה. לפני Chrome 120, הפונקציה הזו לא החזירה הבטחה.

פרמטרים

החזרות

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100+

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

אירועים

onJobStatusChanged

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

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

פרמטרים

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

    פונקציה

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

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