chrome.printing

תיאור

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

הרשאות

printing

זמינות

Chrome 81 ואילך ‫ChromeOS בלבד

כדי להשתמש בכל השיטות והאירועים של 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". כדי לבדוק אם המדפסת שלכם תומכת ב-getPrinterInfo(), חפשו � of ."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

הסטטוס של עבודת ההדפסה.

Enum

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

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

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

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

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

Printer

מאפיינים

  • תיאור

    מחרוזת

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

  • id [מזהה]

    מחרוזת

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

  • isDefault

    בוליאני

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

  • שם

    מחרוזת

    שם המדפסת.

  • recentlyUsedRank

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

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

  • source

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

  • 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

מאפיינים

  • משימה

    משימת ההדפסה שרוצים לשלוח. סוגי התוכן הנתמכים הם 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()

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, הפונקציה הזו לא החזירה הבטחה.

פרמטרים

החזרות

אירועים

onJobStatusChanged

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

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

פרמטרים

  • callback

    פונקציה

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

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