الوصف
استخدِم واجهة برمجة التطبيقات chrome.printing
لإرسال مهام الطباعة إلى الطابعات المثبَّتة على جهاز Chromebook.
الأذونات
printing
مدى توفّر الخدمة
البيان
تتطلّب منك جميع طرق وأحداث 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
حالة الطابعة.
JobStatus
حالة مهمة الطباعة.
التعداد
"Pending"
تم استلام مهمة الطباعة من جهة Chrome، ولكن لم تتم معالجتها بعد.
"IN_PROGRESS"
تم إرسال مهمة الطباعة للطباعة.
"تعذّر"
تمت مقاطعة مهمة الطباعة بسبب حدوث خطأ.
"CANCELED"
تم إلغاء مهمة الطباعة من قِبل المستخدم أو عبر واجهة برمجة التطبيقات.
"PrintED"
تمت طباعة مهمة الطباعة بدون أي أخطاء.
Printer
أماكن إقامة
-
الوصف
سلسلة
تمثّل هذه السمة وصف الطابعة الذي يمكن لشخص عادي قراءته.
-
id
سلسلة
معرّف الطابعة الذي يضمن أن يكون فريدًا بين الطابعات على الجهاز.
-
isDefault
boolean
العلامة التي توضِّح ما إذا كانت الطابعة تتوافق مع قواعد DefaultPrinterSelection. لاحظ أنه يمكن وضع علامة على عدة طابعات.
-
اسم
سلسلة
اسم الطابعة
-
recentlyUsedRank
الرقم اختياري
القيمة التي توضّح مدى حداثة استخدام الطابعة من أجل الطباعة من Chrome. كلما انخفضت القيمة، كانت حداثة استخدام الطابعة أحدث. الحد الأدنى للقيمة هو 0. يشير عدم توفّر القيمة إلى عدم استخدام الطابعة مؤخرًا. ومن المضمون أن تكون هذه القيمة فريدة بين الطابعات.
-
source
مصدر الطابعة (تم ضبط السياسة أو المستخدم).
-
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
أماكن إقامة
-
وظيفة
مهمة الطباعة التي سيتم إرسالها. إنّ نوع المحتوى الوحيد المتوافق هو "تطبيق/pdf"، ويجب ألّا يتضمّن Cloud Job Ticket الحقول
FitToPageTicketItem
وPageRangeTicketItem
وReverseOrderTicketItem
وVendorTicketItem
لأنّها غير مناسبة للطباعة الأصلية. يجب أن تكون جميع الحقول الأخرى متوفّرة.
SubmitJobResponse
أماكن إقامة
-
jobId
سلسلة اختيارية
معرّف مهمة الطباعة التي تم إنشاؤها. وهو معرّف فريد بين جميع مهام الطباعة على الجهاز. وإذا لم تكن الحالة على ما يرام، ستكون قيمة jobId صفرًا.
-
status
حالة الطلب.
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 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
تعرض حالة الطابعة وإمكاناتها بتنسيق CDD. سيتعذر هذا الطلب مع ظهور خطأ في وقت التشغيل إذا لم يتم تثبيت أي طابعات لها معرّف معيّن.
المَعلمات
-
printerId
سلسلة
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: GetPrinterInfoResponse) => void
المرتجعات
-
Promise<GetPrinterInfoResponse>
Chrome 100 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
لعرض قائمة الطابعات المتاحة على الجهاز. ويشمل ذلك الطابعات التي تمت إضافتها يدويًا والمتعلقة بالمؤسسات والمكتشفة.
المَعلمات
المرتجعات
-
الوعد<Printer[]>
Chrome 100 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
يرسل المهمة للطباعة. إذا لم تكن الإضافة مدرَجة في سياسة PrintingAPIExtensionsAllowlist
، سيُطلَب من المستخدم قبول مهمة الطباعة.
قبل الإصدار 120 من Chrome، لم تكن هذه الوظيفة تعرض أي وعود.
المَعلمات
-
طلب
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: SubmitJobResponse) => void
المرتجعات
-
Promise<SubmitJobResponse>
Chrome 100 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
فعاليات
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
يتم تنشيط الحدث عند تغيير حالة المهمة. يتم تنشيط هذا الخيار للوظائف التي أنشأتها هذه الإضافة فقط.