chrome.printing

الوصف

استخدِم واجهة برمجة التطبيقات chrome.printing لإرسال مهام الطباعة إلى الطابعات المثبَّتة على جهاز Chromebook.

الأذونات

printing

مدى التوفّر

الإصدار 81 من Chrome والإصدارات الأحدث نظام التشغيل ChromeOS فقط

تتطلّب جميع طرق chrome.printing وأحداثها الإفصاح عن إذن "printing" في بيان الإضافة. على سبيل المثال:

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

أمثلة

توضّح الأمثلة أدناه كيفية استخدام كل طريقة من الطرق في مساحة اسم الطباعة. تم نسخ هذا الرمز من api-samples/printing أو استناده إليه في مستودع extensions-samples على Github.

cancelJob()

يستخدم هذا المثال معالج onJobStatusChanged لإخفاء زر "إلغاء" عندما لا تكون قيمة jobStatus هي PENDING أو IN_PROGRESS. يُرجى العِلم أنّه في بعض الشبكات أو عند توصيل جهاز Chromebook بالطابعة مباشرةً، قد تمرّ هذه الحالات بسرعة كبيرة جدًا بحيث لا يظهر زر الإلغاء لفترة كافية لاستخدامه. هذا مثال مبسط للغاية على الطباعة.

chrome.printing.onJobStatusChanged.addListener((jobId, status) => {   const cancelButton = document.getElementById("cancelButton");   cancelButton.addEventListener(>9;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 (sta&&tus !== "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) وأنّ البيانات المطلوب طباعتها يتم تحويلها إلى كائن ثنائي كبير (السطر 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" فيه صحيحة. استخدِم قيمتَي الارتفاع والعرض للتذكرة.

"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

"في انتظار المراجعة"
تم تلقّي مهمة الطباعة على Chrome ولكن لم تتم معالجتها بعد.

"IN_PROGRESS"
تم إرسال مهمة الطباعة.

"تعذّر التنفيذ"
تمت مقاطعة مهمة الطباعة بسبب حدوث خطأ.

"تم الإلغاء"
ألغى المستخدم مهمة الطباعة أو تم إلغاؤها من خلال واجهة برمجة التطبيقات.

"تمت الطباعة"
تمت طباعة مهمة الطباعة بدون أي أخطاء.

Printer

الخصائص

  • الوصف

    سلسلة

    وصف الطابعة الذي يمكن لشخص عادي قراءته

  • id

    سلسلة

    معرّف الطابعة، ويُضمن أن يكون فريدًا بين الطابعات على الجهاز.

  • isDefault

    قيمة منطقية

    العلامة التي توضّح ما إذا كانت الطابعة تتوافق مع قواعد DefaultPrinterSelection. يُرجى العِلم أنّه يمكن الإبلاغ عن عدة طابعات.

  • الاسم

    سلسلة

    تمثّل هذه السمة اسم الطابعة.

  • recentlyUsedRank

    number اختياري

    القيمة التي توضّح مدى حداثة استخدام الطابعة للطباعة من Chrome. كلما كانت القيمة أقل، كان استخدام الطابعة أحدث. الحد الأدنى للقيمة هو 0. تشير القيمة "غير متوفّر" إلى أنّه لم يتم استخدام الطابعة مؤخرًا. من المؤكّد أنّ هذه القيمة ستكون فريدة بين الطابعات.

  • المصدر

    PrinterSource

    مصدر الطابعة (المستخدم أو السياسة التي تم ضبطها)

  • uri

    سلسلة

    معرّف الموارد المنتظم (URI) للطابعة يمكن أن تستخدم الإضافات هذه السمة لاختيار الطابعة للمستخدم.

PrinterSource

تمثّل هذه السمة مصدر الطابعة.

Enum

"المستخدم"
أضاف المستخدم الطابعة.

"السياسة"
تمت إضافة الطابعة من خلال السياسة.

PrinterStatus

تعرض هذه السمة حالة الطابعة.

Enum

‫"DOOR_OPEN"
باب الطابعة مفتوح. لا تزال الطابعة تقبل مهام الطباعة.

‫"TRAY_MISSING"
درج الطابعة غير متوفّر. لا تزال الطابعة تقبل مهام الطباعة.

"OUT_OF_INK"
نفد حبر الطابعة. لا تزال الطابعة تقبل مهام الطباعة.

"OUT_OF_PAPER"
نفد الورق من الطابعة. لا تزال الطابعة تقبل مهام الطباعة.

"OUTPUT_FULL"
منطقة الإخراج في الطابعة (مثل الدرج) ممتلئة. لا تزال الطابعة تقبل مهام الطباعة.

‫"PAPER_JAM"
هناك ورقة عالقة في الطابعة. لا تزال الطابعة تقبل مهام الطباعة.

‫"GENERIC_ISSUE"
مشكلة عامة. لا تزال الطابعة تقبل مهام الطباعة.

"متوقفة"
تكون الطابعة متوقفة ولا تطبع، ولكنها تظل تقبل مهام الطباعة.

"لا يمكن الوصول إلى الطابعة"
لا يمكن الوصول إلى الطابعة ولا تقبل مهام الطباعة.

"EXPIRED_CERTIFICATE"
انتهت صلاحية شهادة طبقة المقابس الآمنة (SSL). تقبل الطابعة المهام ولكنها تفشل.

"متاحة"
الطابعة متاحة.

SubmitJobRequest

الخصائص

  • وظيفة

    PrintJob

    مهمة الطباعة التي سيتم إرسالها أنواع المحتوى المتوافقة هي "application/pdf" و "image/png". يجب ألا تتضمّن تذكرة مهمة الطباعة السحابية الحقول FitToPageTicketItem وPageRangeTicketItem وReverseOrderTicketItem لأنّها غير ذات صلة بالطباعة الأصلية. VendorTicketItem هو حقل اختياري. يجب أن تكون جميع الحقول الأخرى متوفّرة.

SubmitJobResponse

الخصائص

  • jobId

    سلسلة اختيارية

    معرّف مهمة الطباعة التي تم إنشاؤها هذا المعرّف فريد بين جميع مهام الطباعة على الجهاز. إذا لم تكن الحالة OK، ستكون قيمة jobId فارغة.

  • حالة الطلب

SubmitJobStatus

حالة طلب submitJob.

Enum

"موافق"
تم قبول طلب مهمة الطباعة المُرسَل.

"USER_REJECTED"
رفض المستخدم طلب مهمة الطباعة المُرسَل.

الخصائص

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

الحدّ الأقصى لعدد المرات التي يمكن فيها استدعاء getPrinterInfo في الدقيقة الواحدة

القيمة

‫20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

الحدّ الأقصى لعدد المرات التي يمكن فيها استدعاء submitJob في الدقيقة الواحدة

القيمة

40

الطُرق

cancelJob()

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

لإلغاء مهمة تم إرسالها سابقًا

المعلمات

  • jobId

    سلسلة

    معرّف مهمة الطباعة المطلوب إلغاؤها. يجب أن يكون هذا المعرّف هو نفسه المعرّف الذي تم تلقّيه في SubmitJobResponse.

المرتجعات

  • Promise<void>

    الإصدار 100 من Chrome والإصدارات الأحدث

getJobStatus()

الإصدار 135 من Chrome والإصدارات الأحدث 
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[]>

    الإصدار 100 من Chrome والإصدارات الأحدث

submitJob()

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

إرسال مهمة الطباعة إذا لم تكن الإضافة مُدرَجة في سياسة PrintingAPIExtensionsAllowlist، سيُطلب من المستخدم قبول مهمة الطباعة. قبل الإصدار 120 من Chrome، لم تكن هذه الدالة تعرض وعدًا.

المعلمات

المرتجعات

  • الإصدار 100 من Chrome والإصدارات الأحدث

الفعاليات

onJobStatusChanged

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

يتم إطلاق هذا الحدث عند تغيير حالة المهمة. يتم تشغيل هذا الإجراء فقط للوظائف التي تم إنشاؤها بواسطة هذه الإضافة.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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