browser.printing

الوصف

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

الأذونات

printing

مدى التوفّر

الإصدار 81 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome نظام التشغيل Chrome فقط

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

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

أمثلة

توضّح الأمثلة أدناه كيفية استخدام كل طريقة في مساحة الاسم الخاصة بالطباعة. تم نسخ هذا الرمز من api-samples/printing في مستودع 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.
  • يشير هذا المصطلح إلى كائن ثنائي كبير (blob) للملف أو البيانات المطلوب طباعتها.

يؤدي استدعاء 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

الخصائص

  • الإمكانات

    object اختياري

    إمكانات الطابعة بتنسيق CDD قد تكون السمة غير متوفّرة.

  • status

    PrinterStatus

    حالة الطابعة

JobStatus

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

Enum

"PENDING"
تم استلام مهمة الطباعة على Chrome ولكن لم تتم معالجتها بعد.

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

"FAILED"
تمت مقاطعة مهمة الطباعة بسبب خطأ ما.

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

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

Printer

الخصائص

  • الوصف

    سلسلة

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

  • id

    سلسلة

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

  • isDefault

    قيمة منطقية

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

  • الاسم

    سلسلة

    اسم الطابعة

  • recentlyUsedRank

    number اختيارية

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

  • المصدر

    PrinterSource

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

  • معرّف الموارد المنتظم (URI)

    سلسلة

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

PrinterSource

مصدر الطابعة

Enum

"USER"
تمت إضافة الطابعة من قِبل المستخدم.

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

PrinterStatus

حالة الطابعة

Enum

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

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

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

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

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

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

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

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

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

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

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

SubmitJobRequest

الخصائص

  • وظيفة

    PrintJob

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

SubmitJobResponse

الخصائص

  • jobId

    string اختياري

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

  • حالة الطلب

SubmitJobStatus

حالة طلب submitJob.

Enum

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

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

الخصائص

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

القيمة

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

القيمة

40

الطُرق

cancelJob()

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

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

المعلمات

  • jobId

    سلسلة

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

المرتجعات

  • وعد<فراغ>

    الإصدار 100 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getJobStatus()

الإصدار 135 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.printing.getJobStatus(
  jobId: string,
): Promise<JobStatus>

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

المعلمات

  • jobId

    سلسلة

المرتجعات

getPrinterInfo()

browser.printing.getPrinterInfo(
  printerId: string,
): Promise<GetPrinterInfoResponse>

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

المعلمات

  • printerId

    سلسلة

المرتجعات

  • الإصدار 100 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getPrinters()

browser.printing.getPrinters(): Promise<Printer[]>

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

المرتجعات

  • Promise<Printer[]>

    الإصدار 100 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

submitJob()

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

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

المعلمات

المرتجعات

  • الإصدار 100 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الفعاليات

onJobStatusChanged

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

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

المعلمات

  • callback

    دالة

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

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