chrome.printing

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

תיאור

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

הרשאות

printing

זמינות

Chrome מגרסה 81 ואילך ב-ChromeOS בלבד

מניפסט

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

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

דוגמאות

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

cancelJob()

בדוגמה הזו נעשה שימוש במטפל 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.
• 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"
המשימה להדפסה נשלחה להדפסה.

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

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

SubmitJobRequest

מאפיינים

• משימה

  PrintJob

  משימת ההדפסה שרוצים לשלוח. סוג התוכן היחיד שנתמך הוא 'application/pdf', וכרטיס המשימה ב-Cloud לא צריך לכלול את השדות 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()

Promise

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

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

פרמטרים

• jobId

  מחרוזת

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

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

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

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

  () => void

החזרות

• Promise<void>

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

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

getJobStatus()

Promise בהמתנה

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

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

פרמטרים

• jobId

  מחרוזת

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

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

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

  (status: JobStatus) => void

  • status

    JobStatus

החזרות

• Promise<JobStatus>

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

getPrinterInfo()

Promise

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

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

פרמטרים

• printerId

  מחרוזת

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

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

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

  (response: GetPrinterInfoResponse) => void

  • תשובה

    GetPrinterInfoResponse

החזרות

• Promise<GetPrinterInfoResponse>

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

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

getPrinters()

Promise

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

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

פרמטרים

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

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

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

  (printers: Printer[]) => void

  • מדפסות

    מדפסת[]

החזרות

• Promise<Printer[]>

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

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

submitJob()

Promise

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

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

פרמטרים

• בקשה

  SubmitJobRequest

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

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

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

  (response: SubmitJobResponse) => void

  • תשובה

    SubmitJobResponse

החזרות

• Promise<SubmitJobResponse>

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

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

אירועים

onJobStatusChanged

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

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

פרמטרים

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

  פונקציה

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

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

  • jobId

    מחרוזת

  • status

    JobStatus