browser.printing

الوصف

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

الأذونات

printing

مدى التوفّر

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

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

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

أمثلة

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

cancelJob()

يستخدم هذا المثال معالج 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) وأنّ البيانات المطلوب طباعتها يتم تحويلها إلى كائن ثنائي كبير (السطر 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". لمعرفة ما إذا كانت طابعتك تتوافق مع هذه الميزة، اتّصِل بالرقم 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

حالة مهمة الطباعة

تعداد

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

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

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

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

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

Printer

الخصائص

  • الوصف

    سلسلة

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

  • id

    سلسلة

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

  • isDefault

    قيمة منطقية

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

  • الاسم

    سلسلة

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

  • recentlyUsedRank

    number اختياري

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

  • المصدر

    PrinterSource

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

  • uri

    سلسلة

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

PrinterSource

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

تعداد

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

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

PrinterStatus

حالة الطابعة

تعداد

‫"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.

تعداد

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

"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