browser.printing

תיאור

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

הרשאות

printing

זמינות

Chrome 81 ואילך ‫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.
  • בלוב של הקובץ או הנתונים להדפסה.

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

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

JobStatus

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

ספירה

‫PENDING
משימת ההדפסה התקבלה בצד של Chrome, אבל עדיין לא עברה עיבוד.

IN_PROGRESS
עבודת ההדפסה נשלחת להדפסה.

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

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

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

Printer

מאפיינים

  • תיאור

    מחרוזת

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

  • id [מזהה]

    מחרוזת

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

  • isDefault

    בוליאני

    הסימון שמראה אם המדפסת מתאימה לכללים של DefaultPrinterSelection. הערה: יכול להיות שכמה מדפסות יסומנו.

  • שם

    מחרוזת

    שם המדפסת.

  • recentlyUsedRank

    מספר אופציונלי

    הערך שמראה מתי לאחרונה נעשה שימוש במדפסת להדפסה מ-Chrome. ככל שהערך נמוך יותר, כך נעשה שימוש במדפסת לאחרונה. הערך המינימלי הוא 0. ערך חסר מציין שלא נעשה שימוש במדפסת לאחרונה. הערך הזה מובטח להיות ייחודי בין המדפסות.

  • source

    המקור של המדפסת (הוגדר על ידי המשתמש או על ידי כללי המדיניות).

  • uri

    מחרוזת

    ה-URI של המדפסת. תוספים יכולים להשתמש בהגדרה הזו כדי לבחור את המדפסת בשביל המשתמש.

PrinterSource

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

ספירה

USER
המשתמש הוסיף מדפסת.

מדיניות
המדפסת נוספה באמצעות מדיניות.

PrinterStatus

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

ספירה

"DOOR_OPEN"
הדלת של המדפסת פתוחה. המדפסת עדיין מקבלת עבודות הדפסה.

"TRAY_MISSING"
המגש של המדפסת חסר. המדפסת עדיין מקבלת עבודות הדפסה.

"OUT_OF_INK"
במדפסת נגמר הדיו. המדפסת עדיין מקבלת עבודות הדפסה.

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

"OUTPUT_FULL"
אזור הפלט של המדפסת (למשל, המגש) מלא. המדפסת עדיין מקבלת עבודות הדפסה.

PAPER_JAM
יש נייר תקוע במדפסת. המדפסת עדיין מקבלת משימות הדפסה.

"GENERIC_ISSUE"
בעיה כללית. המדפסת עדיין מקבלת משימות הדפסה.

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

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

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

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

SubmitJobRequest

מאפיינים

  • משימה

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

SubmitJobResponse

מאפיינים

  • jobId

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

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

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

SubmitJobStatus

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

ספירה

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

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

מאפיינים

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

ערך

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

ערך

40

Methods

cancelJob()

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

ביטול של משימה שנשלחה קודם.

פרמטרים

  • jobId

    מחרוזת

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

החזרות

  • Promise<void>

    Chrome 100 ואילך

getJobStatus()

Chrome 135 ואילך
chrome.printing.getJobStatus(
  jobId: string,
)
: Promise<JobStatus>

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

פרמטרים

  • jobId

    מחרוזת

החזרות

getPrinterInfo()

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

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

פרמטרים

  • printerId

    מחרוזת

החזרות

getPrinters()

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

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

החזרות

  • Promise<Printer[]>

    Chrome 100+

submitJob()

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

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

פרמטרים

החזרות

אירועים

onJobStatusChanged

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

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

פרמטרים

  • callback

    פונקציה

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

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