chrome.printing

الوصف

استخدِم واجهة برمجة التطبيقات 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() ثلاثة أشياء.

  • بنية 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

أماكن إقامة

  • capabilities

    الكائن اختياري

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

  • status

    PrinterStatus

    حالة الطابعة.

JobStatus

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

التعداد

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

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

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

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

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

Printer

أماكن إقامة

  • الوصف

    سلسلة

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

  • id

    سلسلة

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

  • isDefault

    boolean

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

  • اسم

    سلسلة

    اسم الطابعة

  • recentlyUsedRank

    الرقم اختياري

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

  • source

    PrinterSource

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

  • uri

    سلسلة

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

PrinterSource

مصدر الطابعة.

التعداد

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

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

PrinterStatus

حالة الطابعة.

التعداد

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

"TRAY_MDAYSING"
درج الطابعة مفقود. لا تزال الطابعة تقبل مهام الطباعة.

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

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

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

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

"GENERIC_ISSUE"
هناك مشكلة عامة. لا تزال الطابعة تقبل مهام الطباعة.

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

"غير قابلة للوصول"
يتعذّر الوصول إلى الطابعة ولا تقبل مهام الطباعة.

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

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

SubmitJobRequest

أماكن إقامة

  • وظيفة

    PrintJob

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

SubmitJobResponse

أماكن إقامة

  • jobId

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

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

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

المَعلمات

  • jobId

    سلسلة

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

getPrinterInfo()

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

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

المَعلمات

المرتجعات

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

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

getPrinters()

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

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (printers: Printer[])=>void

المرتجعات

  • الوعد<Printer[]>

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

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

submitJob()

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

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

المَعلمات

المرتجعات

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

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

فعاليات

onJobStatusChanged

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

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