chrome.printing

תיאור

הרשאות

זמינות

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

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

דוגמאות

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

ל-method 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
  },
  ...
  ]
}

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

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

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

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

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