chrome.printing

الوصف

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

الأذونات

printing

مدى التوفّر

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

البيان

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

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

أمثلة

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

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"
تمت إضافة طابعة من قِبل المستخدم.

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

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"، ويجب ألا تتضمّن Cloud Job Ticket الحقول 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 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

getPrinterInfo()

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

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

المعلمات

المرتجعات

  • الإصدار 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، لم تقدّم هذه الوظيفة أي تعهد.

المعلمات

المرتجعات

  • Promise&lt;SubmitJobResponse&gt;

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

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

الفعاليات

onJobStatusChanged

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

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

المعلمات

  • رد الاتصال

    دالة

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

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