الوصف
يمكنك استخدام واجهة برمجة التطبيقات chrome.documentScan
API لاكتشاف الصور واستردادها من الماسحات الضوئية للمستندات المرفقة.
تم تصميم واجهة برمجة التطبيقات Document Scan API للسماح للتطبيقات والإضافات بعرض محتوى المستندات الورقية على الماسح الضوئي للمستندات المرفقة.
الأذونات
documentScan
مدى التوفّر
المفاهيم والاستخدام
تتيح واجهة برمجة التطبيقات هذه طريقتين لمسح المستندات ضوئيًا. استخدِم طريقة scan()
إذا كانت حالة الاستخدام متوافقة مع أي ماسح ضوئي ولا تتطلّب التحكّم في الإعدادات. تتطلب حالات الاستخدام الأكثر تعقيدًا مجموعة من الطرق،
التي لا يتم دعمها إلا في الإصدار 124 من Chrome والإصدارات الأحدث.
الفحص البسيط
في حالات الاستخدام البسيطة، أي تلك التي يمكن أن تعمل مع أي ماسح ضوئي ولا تتطلّب التحكّم في الإعدادات، يمكنك طلب الرقم scan()
. تأخذ هذه الطريقة كائن
ScanOptions
وتعرض "الوعد" الذي يتم حله باستخدام
كائن ScanResults
. تقتصر إمكانات هذا الخيار على عدد عمليات الفحص
وأنواع MIME التي سيقبلها المتصل. يتم عرض عمليات الفحص على شكل عناوين URL
لعرضها في علامة <img>
لواجهة مستخدم.
الفحص المعقد
ويتم إجراء عمليات الفحص المعقدة في ثلاث مراحل كما هو موضّح في هذا القسم. لا يصف هذا المخطط كل وسيطة طريقة أو كل خاصية يتم عرضها في استجابة. الغرض منها فقط تقديم دليل عام لكتابة كود الماسح الضوئي.
الحملات أثناء التصفّح
الاتصال بالرقم
getScannerList()
يتم عرض الماسحات الضوئية المتاحة في وعد يتم حله مع علامةGetScannerListResponse
.- يحتوي كائن الاستجابة على مصفوفة من عناصر
ScannerInfo
. - قد تحتوي المصفوفة على إدخالات متعددة لماسح ضوئي واحد إذا كان هذا الماسح الضوئي يتيح بروتوكولات أو طرق اتصال متعددة.
- يحتوي كائن الاستجابة على مصفوفة من عناصر
اختَر ماسحًا ضوئيًا من الصفيف المعروض واحفظ قيمة السمة
scannerId
الخاصة به.استخدِم خصائص عناصر
ScannerInfo
الفردية للتمييز بين العناصر المتعددة للماسح الضوئي نفسه. العناصر من نفس الماسح الضوئي ستكون لها القيمة نفسها للسمةdeviceUuid
. تحتويScannerInfo
أيضًا على السمةimageFormats
التي تحتوي على مجموعة من أنواع الصور المتوافقة.
إعداد الماسح الضوئي
يمكنك الاتصال بالرقم
openScanner()
، وسيتم إرسال رقم تعريف الماسح الضوئي المحفوظ. ويعرض وعدًا يتم حلّه معOpenScannerResponse
. يحتوي كائن الاستجابة على:سمة على
scannerHandle
وعليك حفظها.تمثّل هذه السمة خاصية خيارات تحتوي على خصائص خاصة بالماسح الضوئي ستحتاج إلى ضبطها. يُرجى الاطّلاع على خيارات استرداد الماسح الضوئي للحصول على مزيد من المعلومات.
(اختياري) إذا كنت تريد من المستخدم تقديم قيم لخيارات الماسح الضوئي، أنشئ واجهة مستخدم. ستحتاج إلى خيارات الماسح الضوئي المتوفرة في الخطوة السابقة، وستحتاج إلى استرداد مجموعات الخيارات التي يوفرها الماسح الضوئي. راجِع إنشاء واجهة مستخدم للحصول على مزيد من المعلومات.
يمكنك إنشاء مصفوفة من عناصر
OptionSetting
باستخدام القيم الآلية أو القيم المقدَّمة من المستخدم. يمكنك الاطلاع على "ضبط خيارات الماسح الضوئي" للحصول على مزيد من المعلومات.مرِّر مصفوفة عناصر
OptionSetting
إلىsetOptions()
لضبط الخيارات المتعلّقة بالماسح الضوئي. فهو يعرض وعدًا يتم حلّه باستخدامSetOptionsResponse
. يحتوي هذا الكائن على نسخة محدّثة من خيارات الماسح الضوئي التي تم استردادها في الخطوة 1 من إعداد الماسح الضوئي.نظرًا لأن تغيير أحد الخيارات يمكن أن يغير القيود المفروضة على خيار آخر، فقد تحتاج إلى تكرار هذه الخطوات عدة مرات.
جارٍ الفحص
أنشِئ كائن
StartScanOptions
ومرِّره إلىstartScan()
. ويعرض وعدًا يتم حله باستخدامStartScanResponse
. وخاصيةjob
هي اسم معرِّف ستستخدمه إما لقراءة بيانات الفحص أو لإلغاء الفحص.مرِّر الاسم المعرِّف الخاص بالمهمة إلى
readScanData()
. وتعرض هذه العملية وعدًا يتم حلّه باستخدام كائنReadScanDataResponse
. إذا تمت قراءة البيانات بنجاح، تكون السمةresult
الخاصة بها تساويSUCCESS
وتحتوي السمةdata
الخاصة بها علىArrayBuffer
مع جزء من الفحص. لاحظ أنestimatedCompletion
يحتوي على نسبة مئوية مقدرة من إجمالي البيانات التي تم تسليمها حتى الآن.كرِّر الخطوة السابقة إلى أن تساوي السمة
result
EOF
أو تساوي خطأً.
عند الوصول إلى نهاية عملية الفحص، استدعِ closeScanner()
مع حفظ مقبض الماسح الضوئي في الخطوة
3. يعرض هذا الوعد الذي يتم حله باستخدام CloseScannerResponse
. سيؤدي الاتصال بـ
cancelScan()
في أي وقت بعد إنشاء المهمة إلى إنهاء الفحص.
كائنات الاستجابة
تعرض جميع الطرق وعدًا يتم حله مع كائن استجابة من نوع ما.
ويحتوي معظمها على السمة result
التي تندرج قيمتها ضمن
OperationResult
. لن تحتوي بعض خصائص كائنات الاستجابة
على قيم ما لم تكن قيمة result
لها قيمة محددة. يتم وصف هذه العلاقات في المرجع لكل كائن استجابة.
على سبيل المثال، لن يكون للقاعدة OpenScannerResponse.scannerHandle
قيمة إلا عندما تكون قيمة OpenScannerResponse.result
مساوية لـ SUCCESS
.
خيارات الماسح الضوئي
تختلف خيارات الماسح الضوئي إلى حد كبير باختلاف الجهاز. وبالتالي، لا يمكن عرض خيارات الماسح
الماسح الضوئي مباشرة داخل واجهة برمجة التطبيقات DocumentScan API. لحلّ هذه المشكلة، يحتوي كلّ من OpenScannerResponse
(والذي تم استرداده باستخدام openScanner()
) SetOptionsResponse
(كائن الاستجابة setOptions()
) على السمة options
التي هي عنصر يحتوي على خيارات خاصة بالماسح الضوئي. يكون كل خيار هو ربط مفتاح/قيمة، حيث يكون المفتاح هو خيار خاص بالجهاز والقيمة هي مثيل لـ ScannerOption
.
يبدو الهيكل بشكل عام كما يلي:
{
"key1": { scannerOptionInstance }
"key2": { scannerOptionInstance }
}
على سبيل المثال، تخيَّل ماسحًا ضوئيًا يعرض خيارَي "المصدر" و"الدقة". ستبدو بنية الكائن options
المعروض كما يلي: للتبسيط، يتم عرض ردود ScannerOption
الجزئية فقط.
{
"source": {
"name": "source",
"type": OptionType.STRING,
...
},
"resolution": {
"name": "resolution",
"type": OptionType.INT,
...
},
...
}
إنشاء واجهة مستخدم
ومع أنّ استخدام واجهة برمجة التطبيقات هذه ليس مطلوبًا، قد تحتاج إلى أن يختار المستخدم قيمة لخيار معيّن. يتطلب هذا واجهة مستخدم. استخدِم
OpenScannerResponse
(تم فتحه بواسطة
openScanner()
) لعرض خيارات الماسح الضوئي المرفق كما هو موضّح في القسم السابق.
تجمع بعض برامج الفحص الخيارات بطرق خاصة بالجهاز. ولا تؤثر هذه المجموعات على سلوكيات الخيارات، ولكن نظرًا لأنه قد تكون هذه المجموعات مذكورة في وثائق منتج الماسح الضوئي، يجب عرض هذه المجموعات للمستخدم. يمكنك استرداد هذه المجموعات
من خلال طلب getOptionGroups()
. يؤدي ذلك إلى عرض وعد يتم حله باستخدام كائن GetOptionGroupsResponse
. تحتوي السمة groups
على مصفوفة من المجموعات خاصة بالماسح الضوئي. استخدِم المعلومات الواردة في هذه المجموعات لتنظيم الخيارات في OpenScannerResponse
للعرض.
{
scannerHandle: "123456",
result: SUCCESS,
groups: [
{
title: "Standard",
members: [ "resolution", "mode", "source" ]
}
]
}
كما هو مذكور ضمن إعدادات Scanner، قد يؤدي تغيير أحد الخيارات إلى تغيير القيود في خيار آخر. لهذا السبب، تحتوي السمة setOptionsResponse
(كائن الاستجابة لـ
setOptions()
) على سمة options
أخرى. استخدِم هذا الخيار لتحديث واجهة المستخدم. ثم كرر حسب الحاجة حتى يتم
تعيين جميع الخيارات.
ضبط خيارات الماسح الضوئي
يمكنك ضبط خيارات الماسح الضوئي من خلال تمرير مجموعة من
عناصر OptionSetting
إلى
setOptions()
. للحصول على مثال، يُرجى الاطّلاع على القسم مسح صفحة بحجم حرف واحد التالي.
أمثلة
استرداد صفحة على شكل كائن ثنائي كبير (blob)
يوضح هذا المثال طريقة واحدة لاسترداد صفحة من الماسح الضوئي على شكل فقاعة، ويوضّح استخدام startScan()
وreadScanData()
باستخدام القيمة OperationResult
.
async function pageAsBlob(handle) {
let response = await chrome.documentScan.startScan(
handle, {format: "image/jpeg"});
if (response.result != chrome.documentScan.OperationResult.SUCCESS) {
return null;
}
const job = response.job;
let imgParts = [];
response = await chrome.documentScan.readScanData(job);
while (response.result == chrome.documentScan.OperationResult.SUCCESS) {
if (response.data && response.data.byteLength > 0) {
imgParts.push(response.data);
} else {
// Delay so hardware can make progress.
await new Promise(r => setTimeout(r, 100));
}
response = await chrome.documentScan.readScanData(job);
}
if (response.result != chrome.documentScan.OperationResult.EOF) {
return null;
}
if (response.data && response.data.byteLength > 0) {
imgParts.push(response.data);
}
return new Blob(imgParts, { type: "image/jpeg" });
}
مسح صفحة بحجم حرف واحد ضوئيًا
يوضّح هذا المثال كيفية اختيار ماسح ضوئي وضبط خياراته وفتحه. ثم تسترد محتويات صفحة واحدة وتغلق الماسح الضوئي. وتوضّح هذه العملية استخدام getScannerList()
وopenScanner()
وsetOptions()
وcloseScanner()
. لاحظ أنه يتم استرداد محتويات الصفحة من خلال استدعاء الدالة pageAsBlob()
من المثال السابق.
async function scan() {
let response = await chrome.documentScan.getScannerList({ secure: true });
let scanner = await chrome.documentScan.openScanner(
response.scanners[0].scannerId);
const handle = scanner.scannerHandle;
let options = [];
for (source of scanner.options["source"].constraint.list) {
if (source.includes("ADF")) {
options.push({
name: "source",
type: chrome.documentScan.OptionType.STRING,
value: { value: source }
});
break;
}
}
options.push({
name: "tl-x",
type: chrome.documentScan.OptionType.FIXED,
value: 0.0
});
options.push({
name: "br-x",
type: chrome.documentScan.OptionType.FIXED,
value: 215.9 // 8.5" in mm
});
options.push({
name: "tl-y",
type: chrome.documentScan.OptionType.FIXED,
value: 0.0
});
options.push({
name: "br-y",
type: chrome.documentScan.OptionType.FIXED,
value: 279.4 // 11" in mm
});
response = await chrome.documentScan.setOptions(handle, options);
let imgBlob = await pageAsBlob(handle);
if (imgBlob != null) {
// Insert imgBlob into DOM, save to disk, etc
}
await chrome.documentScan.closeScanner(handle);
}
عرض الإعدادات
كما هو مذكور في مكان آخر، يجب عرض خيارات ضبط الماسح الضوئي للمستخدم للاتصال بـ getOptionGroups()
بالإضافة إلى خيارات الماسح الضوئي التي يتم عرضها عند الاتصال بـ openScanner()
. الهدف من ذلك هو عرض الخيارات للمستخدمين في المجموعات التي تحددها الشركة المصنّعة. يوضح هذا المثال كيفية إجراء ذلك.
async function showConfig() {
let response = await chrome.documentScan.getScannerList({ secure: true });
let scanner = await chrome.documentScan.openScanner(
response.scanners[0].scannerId);
let groups = await chrome.documentScan.getOptionGroups(scanner.scannerHandle);
for (const group of groups.groups) {
console.log("=== " + group.title + " ===");
for (const member of group.members) {
const option = scanner.options[member];
if (option.isActive) {
console.log(" " + option.name + " = " + option.value);
} else {
console.log(" " + option.name + " is inactive");
}
}
}
}
الأنواع
CancelScanResponse
أماكن إقامة
-
وظيفة
سلسلة
يقدّم الاسم المعرِّف الوظيفي نفسه الذي تم إرساله إلى "
cancelScan()
". -
نتيجة
نتيجة البحث عن إلغاء في الخلفية إذا كانت النتيجة
OperationResult.SUCCESS
أوOperationResult.CANCELLED
، هذا يعني أنّه تم إلغاء المسح الضوئي وسيصبح الماسح الضوئي جاهزًا لبدء عملية فحص جديدة. إذا كانت النتيجةOperationResult.DEVICE_BUSY
، يعني ذلك أنّ الماسح الضوئي لا يزال يعالج عملية الإلغاء المطلوبة، ومن المفترض أن ينتظر المتصل وقتًا قصيرًا ويحاول مرة أخرى الطلب. تشير قيم النتائج الأخرى إلى خطأ دائم يجب عدم إعادة المحاولة.
CloseScannerResponse
أماكن إقامة
-
نتيجة
نتيجة إغلاق الماسح الضوئي. حتى إذا لم تكن هذه القيمة
SUCCESS
، سيكون الاسم المعرِّف غير صالح ويجب عدم استخدامه في أي عمليات أخرى. -
scannerHandle
سلسلة
مقبض الماسح الضوئي نفسه الذي تم تمريره إلى
closeScanner
.
Configurability
كيفية تغيير أحد الخيارات
التعداد
"NOT_CONFIGURABLE"
هذا الخيار للقراءة فقط.
"Software_CONFIGURABLE"
يمكن ضبط هذا الخيار في البرنامج.
"HARDWARE_CONFIGURABLE"
يمكن تحديد هذا الخيار عن طريق المستخدم تفعيل أو الضغط على زر في الماسح الضوئي.
ConnectionType
يشير إلى كيفية اتصال الماسح الضوئي بالكمبيوتر.
التعداد
"USB"
التعداد
"INT_RANGE"
القيد على نطاق من قيم OptionType.INT
. ستكون السمات min
وmax
وquant
في OptionConstraint
هي long
، وسيتم إلغاء ضبط خاصية list
.
"FIXED_RANGE"
القيد على نطاق من قيم OptionType.FIXED
. سيتم إلغاء ضبط السمات min
وmax
وquant
في OptionConstraint
على double
، وسيتم إلغاء ضبط السمة list
.
"INT_LIST"
القيد على قائمة معيّنة من قيم OptionType.INT
. ستحتوي السمة OptionConstraint.list
على قيم long
، وسيتم إلغاء ضبط السمات الأخرى.
"FIXED_LIST"
القيد على قائمة معيّنة من قيم OptionType.FIXED
. ستحتوي السمة OptionConstraint.list
على قيم double
، وسيتم إلغاء ضبط السمات الأخرى.
"STRING_LIST"
القيد على قائمة معيّنة من قيم OptionType.STRING
. ستحتوي السمة OptionConstraint.list
على قيم DOMString
، وسيتم إلغاء ضبط السمات الأخرى.
DeviceFilter
أماكن إقامة
-
local
منطقية اختيارية
إرجاع الماسحات الضوئية المتصلة مباشرةً بجهاز الكمبيوتر فقط.
-
آمن
منطقية اختيارية
إرجاع الماسحات الضوئية التي تستخدم عملية نقل آمنة فقط، مثل USB أو بروتوكول أمان طبقة النقل (TLS)
GetOptionGroupsResponse
أماكن إقامة
-
مجموعات
OptionGroup[] اختيارية
إذا كانت قيمة الحقل
result
هيSUCCESS
، سيتم تقديم قائمة بمجموعات الخيارات بالترتيب الذي يوفّره برنامج تشغيل الماسح الضوئي. -
نتيجة
نتيجة الحصول على مجموعات الخيارات. إذا كانت قيمة هذه السمة
SUCCESS
، ستتم تعبئة السمةgroups
. -
scannerHandle
سلسلة
مقبض الماسح الضوئي نفسه الذي تم تمريره إلى
getOptionGroups
.
GetScannerListResponse
أماكن إقامة
-
نتيجة
نتيجة التعداد تجدر الإشارة إلى أنّه يمكن عرض نتائج جزئية حتى إذا كان ذلك يشير إلى حدوث خطأ.
-
ماسحات ضوئية
قائمة يُحتمَل أن تكون فارغة من برامج الفحص التي تطابق رمز
DeviceFilter
المقدَّم.
OpenScannerResponse
أماكن إقامة
-
الخيارات
الكائن اختياري
إذا كانت قيمة السمة
result
هيSUCCESS
، يتم تقديم ربط لقيمة المفتاح حيث يكون المفتاح خيارًا خاصًا بالجهاز وتكون القيمة مثيلاً لـScannerOption
. -
نتيجة
نتيجة فتح الماسح الضوئي. إذا كانت قيمة هذه السمة هي
SUCCESS
، ستتم تعبئة السمتَينscannerHandle
وoptions
. -
scannerHandle
سلسلة اختيارية
إذا كانت قيمة السمة
result
هيSUCCESS
، سيكون الاسم المعرِّف للماسح الضوئي يمكن استخدامه لإجراء المزيد من العمليات. -
scannerId
سلسلة
تم تمرير رقم تعريف الماسح الضوئي إلى
openScanner()
.
OperationResult
تعداد يشير إلى نتيجة كل عملية.
التعداد
"UNKNOWN"
حدث خطأ غير معروف أو عام.
"Success"
نجحت العملية.
"غير مدعومة"
العملية غير متاحة.
"تم إلغاؤها"
تم إلغاء العملية.
"DEVICE_BUSY"
الجهاز مشغول.
"غير صالح"
البيانات أو الوسيطة التي تم تمريرها إلى الطريقة غير صالحة.
"WRONG_TYPE"
القيمة التي تم تقديمها هي نوع البيانات غير الصحيح للخيار الأساسي.
"EOF"
لا تتوفّر أيّ بيانات أخرى.
"ADF_JAMMED"
وحدة تغذية المستندات عالقة.
"ADF_EMPTY"
وحدة تغذية المستندات فارغة.
"COVER_OPEN"
الغطاء المسطَّح مفتوح.
"IO_ERROR"
حدث خطأ أثناء الاتصال بالجهاز.
"ACCESS_DENIED"
يجب مصادقة الجهاز.
"NO_MEMORY"
لا تتوفر ذاكرة كافية على جهاز Chromebook لإكمال العملية.
"غير قابلة للوصول"
لا يمكن الوصول إلى الجهاز.
"MightING"
الجهاز غير متصل.
"INTERNAL_ERROR"
حدث خطأ في مكان آخر غير تطبيق الاتصال.
OptionConstraint
أماكن إقامة
-
قائمة
سلسلة[] | رقم[] اختياري
-
الحد الأقصى
الرقم اختياري
-
دقيقة
الرقم اختياري
-
الكمّية
الرقم اختياري
-
كتابة
OptionGroup
أماكن إقامة
-
الأعضاء
سلسلة[]
مصفوفة من أسماء الخيارات بترتيب مقدَّمة من السائق.
-
title
سلسلة
توفّر عنوانًا قابلاً للطباعة، مثل "خيارات الهندسة".
OptionSetting
أماكن إقامة
-
اسم
سلسلة
تشير إلى اسم الخيار المطلوب ضبطه.
-
كتابة
تشير هذه السمة إلى نوع بيانات الخيار. يجب أن يتطابق نوع البيانات المطلوب مع نوع البيانات الفعلي للخيار الأساسي.
-
القيمة
سلسلة | رقم | منطقي | رقم[] اختياري
يشير إلى القيمة المطلوب ضبطها. يمكنك ترك السياسة بدون ضبط لطلب ضبط الإعداد التلقائي للخيارات التي تم فيها تفعيل
autoSettable
. يجب أن يتطابق نوع البيانات المقدَّم للسمةvalue
معtype
.
OptionType
نوع البيانات لأحد الخيارات.
التعداد
"UNKNOWN"
نوع بيانات الخيار غير معروف. سيتم إلغاء ضبط السمة value
.
"BOOL"
ستكون السمة value
واحدة من true
خطأ.
"INT"
عدد صحيح 32 بت مُوقَّع. ستكون السمة value
طويلة أو طويلة[]، اعتمادًا على ما إذا كان الخيار سيتطلّب أكثر من قيمة واحدة.
"FIXED"
عدد مزدوج في النطاق -32768-32767.9999 وبدرجة دقة 1/65535. ستكون السمة value
مزدوجة أو مزدوجة[] استنادًا إلى ما إذا كان الخيار سيتطلّب أكثر من قيمة واحدة. وسيتم تقريب القيم المزدوجة التي لا يمكن تمثيلها بدقة إلى النطاق والدقة المتاحَين.
"STRING"
تسلسل لأي بايت باستثناء القيمة الفارغة ('\0). ستكون السمة value
هي DOMString.
"button"
لا يحتوي خيار من هذا النوع على قيمة. بدلاً من ذلك، يؤدي تحديد خيار من هذا النوع إلى حدوث تأثير جانبي خاص بالخيار في برنامج تشغيل الماسح الضوئي. على سبيل المثال، يمكن أن يستخدم برنامج تشغيل الماسح الضوئي خيارًا من نوع الأزرار لتحديد القيم التلقائية أو لتوجيه أداة تغذية المستندات التلقائية إلى الورقة التالية.
"GROUP"
خيار التجميع. بلا قيمة. ويتم تضمين هذه السمة من أجل التوافق، ولكن لن يتم عرضها عادةً في قيم ScannerOption
. استخدِم getOptionGroups()
لاسترداد قائمة المجموعات مع خيارات الأعضاء فيها.
التعداد
"UNITLESS"
القيمة هي رقم بدون وحدة. على سبيل المثال، يمكن أن تكون قيمة ثابتة.
"PIXEL"
القيمة هي عدد من وحدات البكسل، على سبيل المثال، أبعاد المسح الضوئي.
"BIT"
القيمة هي عدد وحدات البت، مثل عمق اللون.
"MM"
يتم قياس القيمة بالملليمتر، مثل أبعاد المسح الضوئي.
"DPI"
يتم قياس القيمة بالنقاط لكل بوصة، على سبيل المثال، درجة الدقة.
"PERCENT"
القيمة هي نسبة مئوية، على سبيل المثال، السطوع.
"MICROSECOND"
يتم قياس القيمة بالميكرو ثانية، على سبيل المثال، وقت التعرّض.
ReadScanDataResponse
أماكن إقامة
-
البيانات
ArrayBuffer اختيارية
إذا كانت قيمة السمة
result
هيSUCCESS
، يجب تضمين المقطع التالي من بيانات الصور الممسوحة ضوئيًا. إذا كانت قيمة السمةresult
هيEOF
، يجب تضمين المقطع الأخير من بيانات الصور الممسوحة ضوئيًا. -
estimatedCompletion
الرقم اختياري
إذا كانت قيمة
result
هيSUCCESS
، سيكون تقدير مقدار إجمالي بيانات الفحص التي تم إرسالها حتى الآن، في النطاق من 0 إلى 100. -
وظيفة
سلسلة
تقدِّم هذه السمة الاسم المعرِّف الوظيفي الذي تم تمريره إلى
readScanData()
. -
نتيجة
نتيجة قراءة البيانات. إذا كانت قيمتها
SUCCESS
، سيحتويdata
على المقطع التالي (الذي قد يكون ذو طول صفري) من بيانات الصورة الجاهزة للقراءة. إذا كانت قيمتهاEOF
، سيحتويdata
على المقطع الأخير من بيانات الصورة.
ScannerInfo
أماكن إقامة
-
connectionType
يشير إلى كيفية اتصال الماسح الضوئي بالكمبيوتر.
-
deviceUuid
سلسلة
للمطابقة مع إدخالات
ScannerInfo
الأخرى التي تشير إلى الجهاز الفعلي نفسه -
imageFormats
سلسلة[]
مصفوفة من أنواع MIME التي يمكن طلبها لعمليات الفحص التي تم إرجاعها.
-
الشركة المصنّعة
سلسلة
الشركة المصنّعة للماسح الضوئي
-
model
سلسلة
طراز الماسح الضوئي في حال توفّره، أو وصف عام.
-
اسم
سلسلة
تمثّل هذه السمة اسم يمكن للماسح الضوئي قراءته في واجهة المستخدم.
-
protocolType
سلسلة
وصف يمكن لشخص عادي قراءته للبروتوكول أو برنامج التشغيل المستخدَم للوصول إلى برنامج الماسح الضوئي، مثل Mopria أو WSD أو epsonds. وهذا مفيد في المقام الأول للسماح للمستخدم بالاختيار من بين البروتوكولات إذا كان الجهاز يدعم بروتوكولات متعددة.
-
scannerId
سلسلة
رقم تعريف ماسح ضوئي معيّن.
-
آمن
boolean
في حال اختيار القيمة "صحيح"، لا يمكن أن يعترض جهاز مستمع سلبي، مثل بروتوكول أمان طبقة النقل (TLS) أو USB عملية نقل اتصال الماسح الضوئي.
ScannerOption
أماكن إقامة
-
إمكانية الضبط
تشير إلى ما إذا كان يمكن تغيير الخيار وكيفية تغييره.
-
قيد
OptionConstraint اختيارية
لتحديد
OptionConstraint
في خيار الماسح الضوئي الحالي. -
الوصف
سلسلة
وصف أطول للخيار.
-
isActive
boolean
تشير إلى أن الخيار نشط ويمكن ضبطه أو استرداده. وفي حال اختيار القيمة "خطأ"، لن يتم ضبط السمة
value
. -
isAdvanced
boolean
تشير هذه السمة إلى أنّه يجب ألا تعرض واجهة المستخدم هذا الخيار تلقائيًا.
-
isAutoSettable
boolean
يمكن ضبطها تلقائيًا بواسطة برنامج تشغيل الماسح الضوئي.
-
isDetectable
boolean
تشير إلى إمكانية اكتشاف هذا الخيار من خلال البرنامج.
-
isEmulated
boolean
وتتم المحاكاة من خلال برنامج تشغيل الماسح الضوئي إذا كانت القيمة true.
-
اسم
سلسلة
اسم الخيار باستخدام أحرف ASCII صغيرة وأرقام وشرطات. لا يُسمح باستخدام علامات التشكيل.
-
title
سلسلة
عنوان مكون من سطر واحد قابل للطباعة.
-
كتابة
تمثّل هذه السمة نوع البيانات المضمّنة في السمة
value
، وهي مطلوبة لضبط هذا الخيار. -
الوحدة
وحدة القياس لهذا الخيار.
-
القيمة
سلسلة | رقم | منطقي | رقم[] اختياري
القيمة الحالية للخيار، إذا كان ذلك ملائمًا. لاحظ أن نوع البيانات لهذا الموقع يجب أن يتطابق مع نوع البيانات المحدّد في
type
.
ScanOptions
أماكن إقامة
-
maxImages
الرقم اختياري
عدد الصور الممسوحة ضوئيًا المسموح بها. القيمة التلقائية هي 1.
-
mimeTypes
سلسلة[] اختيارية
أنواع MIME التي يقبلها المتصل.
ScanResults
أماكن إقامة
-
dataUrls
سلسلة[]
مصفوفة من عناوين URL لصور البيانات في شكل يمكن تمريرها كقيمة "src" إلى علامة صورة
-
mimeType
سلسلة
تمثّل هذه السمة نوع MIME للسمة
dataUrls
.
SetOptionResult
أماكن إقامة
-
اسم
سلسلة
يشير إلى اسم الخيار الذي تم ضبطه.
-
نتيجة
تشير هذه السمة إلى نتيجة ضبط الخيار.
SetOptionsResponse
أماكن إقامة
-
الخيارات
الكائن اختياري
تم تعديل ربط قيمة المفتاح من أسماء الخيارات إلى قيم
ScannerOption
التي تحتوي على الإعدادات الجديدة بعد محاولة ضبط جميع الخيارات المقدَّمة. لها نفس بنية السمةoptions
فيOpenScannerResponse
.سيتم ضبط هذه السمة حتى إذا لم يتم ضبط بعض الخيارات بنجاح، ولكن سيتم تركها بدون ضبط في حال تعذّر استرداد الإعدادات المعدَّلة (على سبيل المثال، إذا كان الماسح الضوئي غير متصل في منتصف عملية الفحص).
-
النتائج
مصفوفة من النتائج، واحدة لكل
OptionSetting
تم تمريرها. -
scannerHandle
سلسلة
توفِّر هذه السياسة مقبض الماسح الضوئي الذي تم تمريره إلى
setOptions()
.
StartScanOptions
أماكن إقامة
-
التنسيق
سلسلة
تُحدِّد نوع MIME الذي سيتم فيه عرض البيانات الممسوحة ضوئيًا.
-
maxReadSize
الرقم اختياري
في حال تحديد قيمة غير صفرية، يتم تقييد الحد الأقصى لوحدات البايت التي يتم فحصها في استجابة
readScanData
واحدة لتلك القيمة. علمًا بأن أصغر قيمة مسموح بها هي 32768 (32 كيلوبايت). إذا لم يتم تحديد هذه الخاصية، فقد يكون حجم المقطع المعروض بحجم الصورة الممسوحة ضوئيًا بالكامل.
StartScanResponse
أماكن إقامة
-
وظيفة
سلسلة اختيارية
إذا كانت قيمة السمة
result
هيSUCCESS
، يتم توفير اسم معرِّف يمكن استخدامه لقراءة بيانات البحث أو إلغاء المهمة. -
نتيجة
نتيجة بدء الفحص. إذا كانت قيمة هذه السمة
SUCCESS
، ستتم تعبئة السمةjob
. -
scannerHandle
سلسلة
يوفّر مقبض الماسح الضوئي نفسه الذي تم تمريره إلى
startScan()
.
الطُرق
cancelScan()
chrome.documentScan.cancelScan(
job: string,
callback?: function,
)
لإلغاء الفحص الذي تم بدؤه وعرض وعد يتم حله مع عنصر CancelScanResponse
. وفي حال استخدام معاودة الاتصال، يتم تمرير الكائن إليه بدلاً من ذلك.
المَعلمات
-
وظيفة
سلسلة
الاسم المعرِّف لمهمة فحص نشطة تم إرجاعها في السابق من مكالمة إلى
startScan
. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: CancelScanResponse) => void
المرتجعات
-
Promise<CancelScanResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
closeScanner()
chrome.documentScan.closeScanner(
scannerHandle: string,
callback?: function,
)
يتم إغلاق الماسح الضوئي للمقبض الذي تم تمريره وعرض رمز الوعد الذي يتم حله مع عنصر CloseScannerResponse
. وفي حال استخدام معاودة الاتصال، يتم تمرير الكائن إليه بدلاً من ذلك. وحتى إذا لم تكن الاستجابة ناجحة، يصبح الاسم المعرِّف المقدَّم غير صالح ويجب عدم استخدامه في عمليات إضافية.
المَعلمات
-
scannerHandle
سلسلة
تُحدِّد مقبض ماسح ضوئي مفتوح تم عرضه سابقًا من مكالمة إلى
openScanner
. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: CloseScannerResponse) => void
المرتجعات
-
Promise<CloseScannerResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getOptionGroups()
chrome.documentScan.getOptionGroups(
scannerHandle: string,
callback?: function,
)
للحصول على أسماء المجموعات وخيارات الأعضاء من ماسح ضوئي تم فتحه سابقًا من خلال openScanner
. تعرِض هذه الطريقة وعدًا يتم حلّه باستخدام كائن GetOptionGroupsResponse
. إذا تم تمرير معاودة الاتصال إلى هذه الدالة، يتم تمرير البيانات المعروضة إليها بدلاً من ذلك.
المَعلمات
-
scannerHandle
سلسلة
مقبض ماسح ضوئي مفتوح تم إرجاعه من مكالمة إلى
openScanner
. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: GetOptionGroupsResponse) => void
المرتجعات
-
Promise<GetOptionGroupsResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getScannerList()
chrome.documentScan.getScannerList(
filter: DeviceFilter,
callback?: function,
)
للحصول على قائمة بالماسحات الضوئية المتاحة وعرض وعد يتم حله مع عنصر GetScannerListResponse
. إذا تم تمرير معاودة الاتصال إلى هذه الدالة، يتم تمرير البيانات المعروضة إليها بدلاً من ذلك.
المَعلمات
-
filter
رمز
DeviceFilter
يشير إلى أنواع الماسحات الضوئية التي يجب عرضها. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: GetScannerListResponse) => void
المرتجعات
-
Promise<GetScannerListResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
openScanner()
chrome.documentScan.openScanner(
scannerId: string,
callback?: function,
)
يؤدي هذا الاختصار إلى فتح ماسح ضوئي لإتاحة الوصول الحصري وعرض وعد يتم حله مع عنصر OpenScannerResponse
. إذا تم تمرير معاودة الاتصال إلى هذه الدالة، يتم تمرير البيانات المعروضة إليها بدلاً من ذلك.
المَعلمات
-
scannerId
سلسلة
رقم تعريف الماسح الضوئي المُراد فتحه. هذه القيمة هي قيمة تم عرضها من مكالمة سابقة إلى
getScannerList
. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: OpenScannerResponse) => void
المرتجعات
-
Promise<OpenScannerResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
readScanData()
chrome.documentScan.readScanData(
job: string,
callback?: function,
)
تقرأ المقطع التالي من بيانات الصورة المتاحة من مؤشر مهمة نشط، وتعرض Promise الذي يتم حله باستخدام كائن ReadScanDataResponse
. وفي حال استخدام معاودة الاتصال، يتم تمرير الكائن إليه بدلاً من ذلك.
**ملاحظة:**يمكن أن تكون نتيجة الرد SUCCESS
مع تضمين عضو في data
بقيمة صفرية. وهذا يعني أنّ الماسح الضوئي لا يزال يعمل ولكن ليس لديه بيانات إضافية جاهزة حتى الآن. يجب أن ينتظر المتصل وقتًا قصيرًا ويعيد المحاولة.
عند اكتمال مهمة البحث، ستكون قيمة النتيجة EOF
للاستجابة. قد تحتوي هذه الإجابة على عضو نهائي في "data
" بقيمة غير صفرية.
المَعلمات
-
وظيفة
سلسلة
الاسم المعرِّف للمهمة النشط الذي تم عرضه سابقًا من
startScan
. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: ReadScanDataResponse) => void
المرتجعات
-
Promise<ReadScanDataResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
scan()
chrome.documentScan.scan(
options: ScanOptions,
callback?: function,
)
يُجري مسحًا ضوئيًا للمستندات ويعرض وعدًا يتم حلّه مع عنصر ScanResults
. إذا تم تمرير معاودة الاتصال إلى هذه الدالة، يتم تمرير البيانات التي يتم عرضها إليها بدلاً من ذلك.
المَعلمات
-
الخيارات
عنصر يحتوي على معلَمات فحص
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: ScanResults) => void
-
نتيجة
-
المرتجعات
-
Promise<ScanResults>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
setOptions()
chrome.documentScan.setOptions(
scannerHandle: string,
options: OptionSetting[],
callback?: function,
)
لضبط الخيارات على الماسح الضوئي المحدّد، وعرض وعد يتم حله مع عنصر SetOptionsResponse
يحتوي على نتيجة محاولة ضبط كل قيمة بترتيب العنصر OptionSetting
الذي تم تمريره. وفي حال استخدام معاودة الاتصال، يتم تمرير الكائن إليه بدلاً من ذلك.
المَعلمات
-
scannerHandle
سلسلة
مقبض الماسح الضوئي لضبط الخيارات عليه. يجب أن تكون هذه قيمة تم عرضها في السابق من مكالمة إلى
openScanner
. -
الخيارات
تضم هذه القائمة
OptionSetting
عناصر سيتم تطبيقها على الماسح الضوئي. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: SetOptionsResponse) => void
المرتجعات
-
Promise<SetOptionsResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
startScan()
chrome.documentScan.startScan(
scannerHandle: string,
options: StartScanOptions,
callback?: function,
)
تبدأ عملية فحص على الماسح الضوئي المحدّد وعرض وعد يفي بـ StartScanResponse
. وفي حال استخدام معاودة الاتصال، يتم تمرير الكائن إليه بدلاً من ذلك. إذا تمت المكالمة بنجاح، سيتضمن الرد الاسم المعرِّف للوظيفة الذي يمكن استخدامه في الطلبات اللاحقة لقراءة بيانات البحث أو إلغاء الفحص.
المَعلمات
-
scannerHandle
سلسلة
مقبض الماسح الضوئي المفتوح. يجب أن تكون هذه قيمة تم عرضها في السابق من مكالمة إلى
openScanner
. -
الخيارات
عنصر
StartScanOptions
يشير إلى الخيارات التي سيتم استخدامها في الفحص يجب أن تتطابق السمةStartScanOptions.format
مع أحد الإدخالات المعروضة في سمةScannerInfo
الخاصة بالماسح الضوئي. -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(response: StartScanResponse) => void
المرتجعات
-
Promise<StartScanResponse>
تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.