chrome.printing

الوصف

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

الأذونات

printing

مدى التوفّر

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

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

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

أمثلة

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

cancelJob()‎

يستخدم هذا المثال معالِج 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() وابحث عن "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

    رقم اختياري

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

  • المصدر

    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"، ويجب ألا يتضمّن تذكرة مهام السحابة الإلكترونية حقول FitToPageTicketItem وPageRangeTicketItem وReverseOrderTicketItem وVendorTicketItem لأنّها غير ذات صلة بالطباعة الأصلية. يجب توفّر جميع الحقول الأخرى.

SubmitJobResponse

الخصائص

  • jobId

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

    معرّف مهمة الطباعة التي تم إنشاؤها. هذا معرّف فريد بين جميع مهام الطباعة على الجهاز. إذا لم تكن الحالة "حسنًا"، سيكون 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,
  callback?: function,
)

يؤدي هذا الخيار إلى إلغاء المهمة التي تم إرسالها سابقًا.

المعلمات

  • jobId

    سلسلة

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

  • ردّ الاتصال

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

getJobStatus()

الوعد في انتظار المراجعة
chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
)

تعرِض هذه السمة حالة مهمة الطباعة. سيتعذّر إجراء هذا الطلب بسبب خطأ في وقت التشغيل في حال عدم توفّر مهمة الطباعة التي تحمل jobId المحدّد. jobId: رقم تعريف مهمة الطباعة المطلوب عرض حالتها يجب أن يكون هذا هو المعرّف نفسه الذي تم تلقّيه في SubmitJobResponse.

المعلمات

  • jobId

    سلسلة

  • ردّ الاتصال

    الدالة اختيارية

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

    (status: JobStatus) => void

المرتجعات

  • Promise<JobStatus>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

getPrinterInfo()

الوعد 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

تعرِض حالة الطابعة وإمكاناتها بتنسيق CDD. سيتعذّر إجراء هذا الطلب بسبب خطأ في وقت التشغيل في حال عدم تثبيت أي طابعات بالمعرّف المحدّد.

المعلمات

المرتجعات

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

getPrinters()

الوعد 
chrome.printing.getPrinters(
  callback?: function,
)

عرض قائمة الطابعات المتاحة على الجهاز ويشمل ذلك الطابعات المُضافة يدويًا والطابعات المخصّصة للمؤسسات والطابعات التي تم اكتشافها.

المعلمات

  • ردّ الاتصال

    الدالة اختيارية

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

    (printers: Printer[]) => void

المرتجعات

  • Promise<Printer[]>

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

submitJob()

الوعد 
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

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

المعلمات

المرتجعات

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

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.

الفعاليات

onJobStatusChanged

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

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

المعلمات

  • ردّ الاتصال

    دالة

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

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