chrome.printing

ملاحظتان مهمتان: لا تعمل واجهة برمجة التطبيقات هذه إلا على نظام التشغيل ChromeOS.

الوصف

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

الأذونات

printing

مدى التوفّر

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

البيان

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

{
  "name": "My extension",
  ...
  "permissions": [
    "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) وأنّ البيانات المطلوب طباعتها يتم تحويلها إلى كائن ثنائي كبير (السطر 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"
تمت إضافة طابعة من قِبل المستخدم.

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

SubmitJobResponse

أماكن إقامة

• jobId

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

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

• status

  SubmitJobStatus

  حالة الطلب.

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

المرتجعات

• وعود <باطلة>

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

  لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

getPrinterInfo()

وعود

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

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

المعلمات

• printerId

  سلسلة

• رد الاتصال

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

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

  (response: GetPrinterInfoResponse) => void

  • رد

    GetPrinterInfoResponse

المرتجعات

• Promise&lt;GetPrinterInfoResponse&gt;

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

  لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

getPrinters()

وعود

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

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

المعلمات

• رد الاتصال

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

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

  (printers: Printer[]) => void

  • طابعات

    طابعة[]

المرتجعات

• وعد <طابعة[]>

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

  لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

submitJob()

وعود

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

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

المعلمات

• طلب

  SubmitJobRequest

• رد الاتصال

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

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

  (response: SubmitJobResponse) => void

  • رد

    SubmitJobResponse

المرتجعات

• Promise&lt;SubmitJobResponse&gt;

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

  لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

فعاليات

onJobStatusChanged

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

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

المعلمات

• رد الاتصال

  دالة

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

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

  • jobId

    سلسلة

  • status

    JobStatus