chrome.printing

תיאור

אפשר להשתמש ב-chrome.printing API כדי לשלוח עבודות הדפסה למדפסות שמותקנות ב-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.
  • בלוב של הקובץ או הנתונים להדפסה.

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

    PrinterStatus

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

JobStatus

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

Enum

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

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

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

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

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

Printer

מאפיינים

  • תיאור

    מחרוזת

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

  • id [מזהה]

    מחרוזת

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

  • isDefault

    בוליאני

    הסימון שמראה אם המדפסת מתאימה לכללים של DefaultPrinterSelection. שימו לב: יכול להיות שיוצג סימון לגבי כמה מדפסות.

  • שם

    מחרוזת

    שם המדפסת.

  • recentlyUsedRank

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

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

  • source

    PrinterSource

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

  • uri

    מחרוזת

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

PrinterSource

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

Enum

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

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

PrinterStatus

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

Enum

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

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

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

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

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

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

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

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

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

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

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

SubmitJobRequest

מאפיינים

  • משימה

    PrintJob

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

SubmitJobResponse

מאפיינים

  • jobId

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

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

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

SubmitJobStatus

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

Enum

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

‫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

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 100 ואילך

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

getJobStatus()

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

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

פרמטרים

  • jobId

    מחרוזת

  • callback

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

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

    (status: JobStatus) => void

החזרות

  • Promise<JobStatus>

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

getPrinterInfo()

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

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

פרמטרים

החזרות

  • ‫Chrome 100 ואילך

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

getPrinters()

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

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

פרמטרים

  • callback

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

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

    (printers: Printer[]) => void

החזרות

  • Promise<Printer[]>

    ‫Chrome 100 ואילך

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

submitJob()

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

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

פרמטרים

החזרות

  • ‫Chrome 100 ואילך

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

אירועים

onJobStatusChanged

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

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

פרמטרים

  • callback

    פונקציה

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

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