chrome.printing

refresh date: 2026-09-25 robots: noindex

תיאור

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

הרשאות

printing

זמינות

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

מניפסט

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

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

דוגמאות

הדוגמאות הבאות ממחישות את השימוש בכל אחת מהשיטות במרחב השמות של ההדפסה. הקוד הזה מועתק מ-api-samples/printing במאגר extensions-samples ב-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()‎

השיטה 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". כדי לבדוק אם המדפסת תומכת ב-IPP, צריך להתקשר אל 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

מאפיינים

  • יכולות

    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.

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

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,
): Promise<void>

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

פרמטרים

  • jobId

    מחרוזת

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

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

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

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

getJobStatus()

Promise Chrome 135+‎ 
chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
): Promise<JobStatus>

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

פרמטרים

  • jobId

    מחרוזת

  • callback

    function optional

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

    (status: JobStatus) => void

החזרות

  • Promise<JobStatus>

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

getPrinterInfo()

Promise 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
): Promise<GetPrinterInfoResponse>

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

פרמטרים

החזרות

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

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

getPrinters()

Promise 
chrome.printing.getPrinters(
  callback?: function,
): Promise<Printer[]>

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

פרמטרים

  • callback

    function optional

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

    (printers: Printer[]) => void

החזרות

  • ‫Promise<Printer[]>

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

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

submitJob()

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

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

פרמטרים

החזרות

  • הבטחה<SubmitJobResponse>

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

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

אירועים

onJobStatusChanged

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

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

פרמטרים

  • callback

    פונקציה

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

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