browser.printing

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

תיאור

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

הרשאות

printing

זמינות

‫Chrome 81 ואילך ‫browser.* ‎ החל מגרסה 148 של Chrome ChromeOS בלבד

כדי להשתמש בכל ה-methods והאירועים של browser.printing, צריך להצהיר על ההרשאה "printing" במניפסט של התוסף. לדוגמה:

{
  "name": "My extension",
  ...
  "permissions": [
    "printing"
  ],
  ...
}

דוגמאות

הדוגמאות הבאות ממחישות את השימוש בכל אחת מהשיטות במרחב השמות של ההדפסה. הקוד הזה מועתק מ-api-samples/printing במאגר extensions-samples ב-GitHub, או מבוסס עליו.

cancelJob()‎

בדוגמה הזו נעשה שימוש ב-handler‏ onJobStatusChanged כדי להסתיר את הלחצן "ביטול" כשהערך של jobStatus הוא לא PENDING או IN_PROGRESS. שימו לב שברשתות מסוימות, או כש-Chromebook מחובר ישירות למדפסת, יכול להיות שהמצבים האלה יעברו מהר מדי, וכפתור הביטול לא יוצג מספיק זמן כדי שתוכלו ללחוץ עליו. זו דוגמה פשוטה מאוד להדפסה.

browser.printing.onJobStatusChanged.addListener((jobId, status) => {
  const cancelButton = document.getElementById("cancelButton");
  cancelButton.addEventListener('click', () => {
    browser.printing.cancelJob(jobId).then((response) => {
      if (response !== undefined) {
        console.log(response.status);
      }
      if (browser.runtime.lastError !== undefined) {
        console.log(browser.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 browser.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
  const printerInfo = await browser.printing.getPrinterInfo(printer.id);
  return printerInfo.isDefault;
}
console.log(`Default printer: ${defaultPrinter.name}.\n\t${defaultPrinter.description}`);

submitJob()‎

השיטה 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'
    });
  }
};

browser.printing.submitJob(submitJobRequest, (response) => {
  if (response !== undefined) {
    console.log(response.status);
  }
  if (browser.runtime.lastError !== undefined) {
    console.log(browser.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". כדי לבדוק אם המדפסת תומכת ב-IPP, צריך להתקשר אל getPrinterInfo() ולחפש "display_name" של "finishings/11".

"vendor_capability": [
  {
    "display_name": "finishings/11",
    "id": "finishings/11",
    "type": "TYPED_VALUE",
    "typed_value_cap": {
      "value_type": "BOOLEAN"
    }
  },
  ...
]

הערה: החל מגרסה 124 של Chrome, המדיניות vendor_ticket_item מאפשרת את כל הפריטים מ-vendor_capabilities של המדפסת. לדוגמה, כל ערך שמוחזר על ידי getPrinterInfo() הוא תקין. בעבר, רק המפתח finishings נתמך.

הערכים במפתח 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

מאפיינים

• יכולות

  object optional

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

• status

  PrinterStatus

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

JobStatus

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

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

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

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

‫"FAILED"
משימת ההדפסה הופסקה בגלל שגיאה.

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

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

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

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

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

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

SubmitJobRequest

מאפיינים

• משימה

  PrintJob

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

SubmitJobResponse

מאפיינים

• jobId

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

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

• status

  SubmitJobStatus

  סטטוס הבקשה.

SubmitJobStatus

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

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

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

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

מאפיינים

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

ערך

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

ערך

40

Methods

cancelJob()

browser.printing.cancelJob(
  jobId: string,
): Promise<void>

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

פרמטרים

• jobId

  מחרוזת

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

החזרות

• Promise<void>

  ‫Chrome 100+‎ browser.* ‎ מגרסה Chrome 148

getJobStatus()

‫Chrome מגרסה 135 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

browser.printing.getJobStatus(
  jobId: string,
): Promise<JobStatus>

מחזירה את הסטטוס של משימת ההדפסה. הקריאה הזו תיכשל עם שגיאת זמן ריצה אם משימת ההדפסה עם ה-jobId שצוין לא קיימת. ‫jobId: המזהה של עבודת ההדפסה שהסטטוס שלה יוחזר. המזהה הזה צריך להיות זהה למזהה שהתקבל ב-SubmitJobResponse.

פרמטרים

• jobId

  מחרוזת

החזרות

• Promise<JobStatus>

getPrinterInfo()

browser.printing.getPrinterInfo(
  printerId: string,
): Promise<GetPrinterInfoResponse>

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

פרמטרים

• printerId

  מחרוזת

החזרות

• Promise<GetPrinterInfoResponse>

  ‫Chrome 100+‎ browser.* ‎ מגרסה Chrome 148

getPrinters()

browser.printing.getPrinters(): Promise<Printer[]>

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

החזרות

• ‫Promise<Printer[]>

  ‫Chrome 100+‎ browser.* ‎ מגרסה Chrome 148

submitJob()

browser.printing.submitJob(
  request: SubmitJobRequest,
): Promise<SubmitJobResponse>

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

פרמטרים

• בקשה

  SubmitJobRequest

החזרות

• הבטחה<SubmitJobResponse>

  ‫Chrome 100+‎ browser.* ‎ מגרסה Chrome 148

אירועים

onJobStatusChanged

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

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

פרמטרים

• callback

  פונקציה

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

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

  • jobId

    מחרוזת

  • status

    JobStatus