تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

chrome.documentScan

الوصف

استخدِم واجهة برمجة التطبيقات chrome.documentScan للعثور على الصور واستردادها من الماسحات الضوئية للمستندات المرفقة.

تم تصميم واجهة برمجة التطبيقات Document Scan API للسماح للتطبيقات والإضافات بعرض محتوى المستندات الورقية على ماسح ضوئي للمستندات متصل بالجهاز.

الأذونات

documentScan

مدى التوفّر

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

يظهر مدى توفّر الأعضاء الذين تمت إضافتهم لاحقًا إلى واجهة برمجة التطبيقات مع هؤلاء الأعضاء.

المفاهيم والاستخدام

تتيح واجهة برمجة التطبيقات هذه طريقتَين لمسح المستندات ضوئيًا. إذا كانت حالة الاستخدام تتوافق مع أي ماسح ضوئي ولا تتطلّب التحكّم في الإعدادات، استخدِم طريقة scan(). تتطلّب حالات الاستخدام الأكثر تعقيدًا الجمع بين عدة طرق، وهي متاحة فقط في الإصدار 124 من Chrome والإصدارات الأحدث.

المسح الضوئي البسيط

بالنسبة إلى حالات الاستخدام البسيطة، أي تلك التي يمكن أن تعمل مع أي ماسح ضوئي ولا تتطلّب التحكّم في الإعدادات، استخدِم scan(). يأخذ هذا الإجراء عنصر ScanOptions ويعرض وعدًا يتم تنفيذه باستخدام عنصر ScanResults. تقتصر إمكانات هذا الخيار على عدد عمليات الفحص وأنواع MIME التي سيقبلها المتصل. يتم عرض عمليات الفحص كعناوين URL في علامة <img> لواجهة المستخدم.

المسح الضوئي المعقّد

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

استكشاف المحتوى

اتّصِل بالرقم getScannerList(). يتم عرض الماسحات الضوئية المتاحة في Promise يتم تنفيذه باستخدام GetScannerListResponse.
- يحتوي عنصر الاستجابة على مصفوفة من عناصر ScannerInfo.
- قد تحتوي المصفوفة على عدة إدخالات لماسح ضوئي واحد إذا كان هذا الماسح الضوئي يتوافق مع عدة بروتوكولات أو طرق اتصال.
اختَر ماسحًا ضوئيًا من الصفيف الذي تم إرجاعه واحفظ قيمة السمة scannerId.

استخدِم خصائص عناصر ScannerInfo الفردية للتمييز بين عناصر متعددة خاصة بجهاز المسح الضوئي نفسه. ستتضمّن العناصر من الماسح الضوئي نفسه القيمة نفسها للسمة deviceUuid. تحتوي السمة ScannerInfo أيضًا على السمة imageFormats التي تتضمّن مصفوفة من أنواع الصور المتوافقة.

إعدادات الماسح الضوئي

اتّصِل بالرقم openScanner()، مع إدخال رقم تعريف الماسح الضوئي المحفوظ. تعرض هذه الدالة Promise يتم تنفيذه باستخدام OpenScannerResponse. يحتوي عنصر الاستجابة على ما يلي:
- سمة scannerHandle، والتي عليك حفظها
- سمة خيارات تحتوي على سمات خاصة بالماسح الضوئي، وعليك ضبطها. راجِع مقالة استرداد خيارات الماسح الضوئي لمزيد من المعلومات.
(اختياري) إذا كنت بحاجة إلى أن يقدّم المستخدم قيمًا لخيارات الماسح الضوئي، أنشئ واجهة مستخدم. ستحتاج إلى خيارات الماسح الضوئي التي تم توفيرها في الخطوة السابقة، كما ستحتاج إلى استرداد مجموعات الخيارات التي يوفّرها الماسح الضوئي. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء واجهة مستخدم.
أنشئ مصفوفة من عناصر OptionSetting باستخدام قيم مقدَّمة آليًا أو من قِبل المستخدم. اطّلِع على مقالة ضبط خيارات الماسح الضوئي للحصول على مزيد من المعلومات.
مرِّر مصفوفة عناصر OptionSetting إلى setOptions() لضبط خيارات الماسح الضوئي. تعرض هذه الدالة وعدًا يتم تنفيذه باستخدام SetOptionsResponse. يحتوي هذا العنصر على نسخة معدَّلة من خيارات الماسح الضوئي التي تم استردادها في الخطوة 1 من عملية إعداد الماسح الضوئي.

بما أنّ تغيير أحد الخيارات يمكن أن يؤدي إلى تغيير القيود المفروضة على خيار آخر، قد تحتاج إلى تكرار هذه الخطوات عدة مرات.

جارٍ البحث

أنشئ عنصر StartScanOptions ومرِّره إلى startScan(). تعرض هذه الدالة Promise يتم تنفيذه باستخدام StartScanResponse. الخاصية job هي معرّف ستستخدمه إما لقراءة بيانات الفحص أو لإلغاء الفحص.
مرِّر معرّف المهمة إلى readScanData(). تعرض هذه الدالة وعدًا يتم تنفيذه باستخدام كائن ReadScanDataResponse. إذا تمت قراءة البيانات بنجاح، ستكون قيمة السمة result هي SUCCESS، وستتضمّن السمة data ArrayBuffer مع جزء من عملية الفحص. يُرجى العِلم أنّ estimatedCompletion يتضمّن نسبة مئوية مقدّرة من إجمالي البيانات التي تم تسليمها حتى الآن.

ملاحظة: إذا كانت قيمة result هي SUCCESS، ولكن data فارغ، عليك الانتظار لفترة قصيرة قبل طلب readScanData() مرة أخرى.
كرِّر الخطوة السابقة إلى أن تصبح قيمة السمة result مساوية للقيمة EOF أو خطأ.

عند الوصول إلى نهاية عملية المسح الضوئي، اتّصِل بالدالة closeScanner() باستخدام معرّف الماسح الضوئي الذي تم حفظه في الخطوة 3. تعرض هذه الدالة وعدًا يتم تنفيذه باستخدام CloseScannerResponse. سيؤدي الاتصال بالرقم cancelScan() في أي وقت بعد إنشاء مهمة الفحص إلى إيقاف الفحص.

عناصر الاستجابة

تعرض جميع الطرق Promise يتم حله باستخدام عنصر استجابة من نوع ما. يحتوي معظمها على السمة result التي تكون قيمتها أحد عناصر OperationResult. لن تحتوي بعض خصائص عناصر الاستجابة على قيم ما لم تكن قيمة result قيمة معيّنة. يتم وصف هذه العلاقات في المرجع الخاص بكل عنصر استجابة.

على سبيل المثال، لن تتضمّن OpenScannerResponse.scannerHandle قيمة إلا عندما تكون قيمة OpenScannerResponse.result مساوية لقيمة SUCCESS.

خيارات الماسح الضوئي

تختلف خيارات الماسح الضوئي بشكل كبير حسب الجهاز. وبالتالي، لا يمكن عرض خيارات الماسح الضوئي مباشرةً ضمن واجهة برمجة التطبيقات documentScan. لحلّ هذه المشكلة، يحتوي العنصران 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(). تعرض هذه الدالة Promise يتم تنفيذه باستخدام كائن GetOptionGroupsResponse. تحتوي السمة groups على مصفوفة خاصة بالماسح الضوئي للمجموعات. استخدِم المعلومات الواردة في هذه المجموعات لتنظيم الخيارات في OpenScannerResponse للعرض.

{
  scannerHandle: "123456",
  result: SUCCESS,
  groups: [
    {
      title: "Standard",
      members: [ "resolution", "mode", "source" ]
    }
  ]
}

كما هو موضّح في قسم "إعدادات أداة الفحص"، يمكن أن يؤدي تغيير أحد الخيارات إلى تغيير القيود المفروضة على خيار آخر. لهذا السبب، يحتوي 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

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

الخصائص

وظيفة

سلسلة

تعرض هذه السمة معرّف الوظيفة نفسه الذي تم تمريره إلى cancelScan().
نتيجة

OperationResult

نتيجة إلغاء عملية المسح الضوئي من الخلفية إذا كانت النتيجة OperationResult.SUCCESS أو OperationResult.CANCELLED، يعني ذلك أنّه تم إلغاء عملية المسح الضوئي وأنّ الماسح الضوئي جاهز لبدء عملية مسح ضوئي جديدة. إذا كانت النتيجة OperationResult.DEVICE_BUSY ، يعني ذلك أنّ الماسح الضوئي لا يزال بصدد معالجة طلب الإلغاء، وعلى المتصل الانتظار لفترة قصيرة وإعادة المحاولة. تشير قيم النتائج الأخرى إلى حدوث خطأ دائم لا يجب إعادة محاولة تنفيذه.

CloseScannerResponse

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

الخصائص

نتيجة

OperationResult

نتيجة إغلاق الماسح الضوئي حتى إذا لم تكن هذه القيمة SUCCESS، سيكون المعرّف غير صالح ويجب عدم استخدامه في أي عمليات أخرى.
scannerHandle

سلسلة

مقبض الماسح الضوئي نفسه الذي تم تمريره إلى closeScanner.

Configurability

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

كيفية تغيير أحد الخيارات

Enum

"NOT_CONFIGURABLE"
الخيار للقراءة فقط.

‫"SOFTWARE_CONFIGURABLE"
يمكن ضبط الخيار في البرنامج.

‫HARDWARE_CONFIGURABLE
يمكن للمستخدم ضبط هذا الخيار من خلال تفعيل زر أو الضغط عليه في الماسح الضوئي.

ConnectionType

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

تشير إلى طريقة اتصال الماسح الضوئي بالكمبيوتر.

Enum

"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

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

نوع البيانات الخاص بالقيود الممثَّلة بواسطة OptionConstraint.

Enum

"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

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

الخصائص

محلي

boolean اختياري

عرض الماسحات الضوئية المتصلة مباشرةً بالكمبيوتر فقط
آمن

boolean اختياري

عرض الماسحات الضوئية التي تستخدم وسيلة نقل آمنة، مثل USB أو TLS فقط

GetOptionGroupsResponse

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

الخصائص

مجموعات

OptionGroup[] اختياري

إذا كانت القيمة result هي SUCCESS، يتم توفير قائمة بمجموعات الخيارات بالترتيب الذي يوفّره برنامج تشغيل الماسح الضوئي.
نتيجة

OperationResult

نتيجة الحصول على مجموعات الخيارات إذا كانت القيمة هي SUCCESS، سيتم ملء السمة groups.
scannerHandle

سلسلة

مقبض الماسح الضوئي نفسه الذي تم تمريره إلى getOptionGroups.

GetScannerListResponse

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

الخصائص

نتيجة

OperationResult

نتيجة التعداد يُرجى العِلم أنّه يمكن عرض نتائج جزئية حتى إذا كان ذلك يشير إلى حدوث خطأ.
أجهزة المسح الضوئي

ScannerInfo[]

قائمة قد تكون فارغة تضم الماسحات الضوئية التي تتطابق مع DeviceFilter المقدَّم.

OpenScannerResponse

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

الخصائص

الخيارات

العنصر اختياري

إذا كانت قيمة result هي SUCCESS، يتم توفير عملية ربط بين المفتاح والقيمة، حيث يكون المفتاح خيارًا خاصًا بالجهاز والقيمة هي مثيل ScannerOption.
نتيجة

OperationResult

نتيجة فتح الماسح الضوئي إذا كانت قيمة هذا الحقل SUCCESS، ستتم تعبئة السمتَين scannerHandle وoptions.
scannerHandle

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

إذا كانت قيمة result هي SUCCESS، يكون هذا الحقل عبارة عن معرّف للماسح الضوئي يمكن استخدامه في عمليات أخرى.
scannerId

سلسلة

تم تمرير معرّف الماسح الضوئي إلى openScanner().

OperationResult

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

تعداد يشير إلى نتيجة كل عملية.

Enum

"UNKNOWN"
حدث خطأ غير معروف أو عام.

"SUCCESS"
تمت العملية بنجاح.

"غير متوافق"
العملية غير متوافقة.

"تم الإلغاء"
تم إلغاء العملية.

‫"DEVICE_BUSY"
الجهاز مشغول.

"INVALID"
إما أنّ البيانات أو إحدى الوسيطات التي تم تمريرها إلى الطريقة غير صالحة.

‫"WRONG_TYPE"
القيمة المقدَّمة هي نوع البيانات غير الصحيح للخيار الأساسي.

"EOF"
لا تتوفّر أي بيانات أخرى.

‫"ADF_JAMMED"
وحدة تغذية المستندات مليئة بالأوراق.

‫"ADF_EMPTY"
وحدة تغذية المستندات فارغة.

‫"COVER_OPEN"
غطاء الماسحة الضوئية المسطحة مفتوح.

‫"IO_ERROR"
حدث خطأ أثناء الاتصال بالجهاز.

"ACCESS_DENIED"
يتطلّب الجهاز المصادقة.

‫"NO_MEMORY"
لا تتوفّر مساحة تخزين كافية في ذاكرة Chromebook لإكمال العملية.

"UNREACHABLE"
يتعذّر الوصول إلى الجهاز.

"MISSING"
الجهاز غير متصل.

‫"INTERNAL_ERROR"
حدث خطأ في مكان آخر غير التطبيق الذي تم الاتصال به.

OptionConstraint

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

الخصائص

قائمة

string[] | number[] اختيارية
الحد الأقصى

number اختياري
دقيقة

number اختياري
quant

number اختياري
النوع

ConstraintType

OptionGroup

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

الخصائص

الأعضاء

string[]

مجموعة من أسماء الخيارات بالترتيب الذي يحدّده السائق
title

سلسلة

توفّر عنوانًا قابلاً للطباعة، مثل "خيارات الأشكال الهندسية".

OptionSetting

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

الخصائص

الاسم

سلسلة

تشير إلى اسم الخيار المطلوب ضبطه.
النوع

OptionType

تشير إلى نوع بيانات الخيار. يجب أن يتطابق نوع البيانات المطلوب مع نوع البيانات الفعلي للخيار الأساسي.
القيمة

string | number | boolean | number[] اختياري

تشير إلى القيمة المطلوب ضبطها. اتركها بدون ضبط لطلب إعداد تلقائي للخيارات التي تم تفعيل autoSettable فيها. يجب أن يتطابق نوع البيانات المقدَّم لـ value مع type.

OptionType

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

نوع بيانات أحد الخيارات

Enum

UNKNOWN
نوع بيانات الخيار غير معروف. سيتم إلغاء ضبط السمة value.

"BOOL"
ستكون قيمة السمة value إحدى القيمتين truefalse.

"INT"
عدد صحيح 32 بت موقّع ستكون السمة value من النوع long أو long[]، وذلك حسب ما إذا كان الخيار يقبل أكثر من قيمة واحدة.

"FIXED"
عدد مزدوج في النطاق ‎-32768-32767.9999 بدقة 1/65535 سيكون نوع السمة value هو double أو double[] ‎ استنادًا إلى ما إذا كان الخيار يقبل أكثر من قيمة واحدة. سيتم تقريب قيم الأعداد المضاعفة التي لا يمكن تمثيلها بدقة إلى النطاق والدقة المتاحَين.

"STRING"
سلسلة من أي بايتات باستثناء NUL (‎\0). ستكون السمة value عبارة عن DOMString.

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

"GROUP"
خيار التجميع بلا قيمة يتم تضمين ذلك لأغراض التوافق، ولكن لن يتم عرضه عادةً في قيم ScannerOption. استخدِم getOptionGroups() لاسترداد قائمة المجموعات مع خيارات الأعضاء.

OptionUnit

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

يشير إلى نوع البيانات ScannerOption.unit.

Enum

"UNITLESS"
القيمة هي رقم بدون وحدة. على سبيل المثال، يمكن أن يكون حدًا أدنى.

"PIXEL"
القيمة هي عدد وحدات البكسل، مثل أبعاد المسح الضوئي.

"BIT"
القيمة هي عدد وحدات البت، على سبيل المثال، عمق اللون.

"MM"
يتم قياس القيمة بالملليمتر، على سبيل المثال، أبعاد عملية المسح الضوئي.

"DPI"
يتم قياس القيمة بالنقاط لكل بوصة، على سبيل المثال، الدقة.

استبدِل "PERCENT"
بالقيمة التي تمثّل نسبة مئوية، مثل السطوع.

"MICROSECOND"
يتم قياس القيمة بالميكرو ثانية، على سبيل المثال، وقت التعرض.

ReadScanDataResponse

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

الخصائص

البيانات

ArrayBuffer اختياري

إذا كانت قيمة result هي SUCCESS، يحتوي على الجزء التالي من بيانات الصورة الممسوحة ضوئيًا. إذا كانت قيمة result هي EOF، يحتوي على الجزء الأخير من بيانات الصورة الممسوحة ضوئيًا.
estimatedCompletion

number اختياري

إذا كانت قيمة result هي SUCCESS، يكون هذا الحقل عبارة عن تقدير لمقدار بيانات الفحص الإجمالية التي تم تسليمها حتى الآن، وذلك في النطاق من 0 إلى 100.
وظيفة

سلسلة

تقدِّم هذه السمة معرّف المهمة الذي تم تمريره إلى readScanData().
نتيجة

OperationResult

نتيجة قراءة البيانات إذا كانت قيمتها SUCCESS، سيحتوي data على الجزء التالي (الذي قد يكون بطول صفر) من بيانات الصورة الجاهزة للقراءة. إذا كانت القيمة EOF، يحتوي data على الجزء الأخير من بيانات الصورة.

ScannerInfo

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

الخصائص

connectionType

ConnectionType

تشير إلى طريقة اتصال الماسح الضوئي بالكمبيوتر.
deviceUuid

سلسلة

للمطابقة مع إدخالات ScannerInfo الأخرى التي تشير إلى الجهاز الفعلي نفسه
imageFormats

string[]

مصفوفة من أنواع MIME التي يمكن طلبها لعمليات الفحص التي يتم إرجاعها.
الشركة المصنّعة

سلسلة

الشركة المصنّعة للماسح الضوئي
نموذج

سلسلة

تمثّل هذه السمة طراز الماسح الضوئي إذا كان متاحًا، أو وصفًا عامًا.
الاسم

سلسلة

اسم الماسح الضوئي الذي يمكن للمستخدم قراءته والمطلوب عرضه في واجهة المستخدم
protocolType

سلسلة

وصف يمكن لشخص عادي قراءته للبروتوكول أو برنامج التشغيل المستخدَم للوصول إلى الماسح الضوئي، مثل Mopria أو WSD أو epsonds ويفيد ذلك بشكل أساسي في السماح للمستخدم بالاختيار بين البروتوكولات إذا كان الجهاز يتوافق مع بروتوكولات متعددة.
scannerId

سلسلة

معرّف ماسح ضوئي معيّن
آمن

قيمة منطقية

إذا كانت القيمة صحيحة، لا يمكن اعتراض وسيلة نقل اتصال الماسح الضوئي من خلال مستمع سلبي، مثل بروتوكول أمان طبقة النقل (TLS) أو USB.

ScannerOption

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

الخصائص

قابلية الإعداد

إمكانية الضبط

تشير إلى ما إذا كان يمكن تغيير الخيار وكيفية تغييره.
قيد

OptionConstraint اختياري

تحدّد هذه السمة OptionConstraint في خيار الماسح الضوئي الحالي.
الوصف

سلسلة

وصف أطول للخيار
isActive

قيمة منطقية

تشير إلى أنّ الخيار نشط ويمكن ضبطه أو استرداده. في حال ضبطها على "خطأ"، لن يتم ضبط السمة value.
isAdvanced

قيمة منطقية

تشير إلى أنّه يجب ألا تعرض واجهة المستخدم هذا الخيار تلقائيًا.
isAutoSettable

قيمة منطقية

يمكن ضبطه تلقائيًا بواسطة برنامج تشغيل الماسح الضوئي.
isDetectable

قيمة منطقية

تشير إلى إمكانية رصد هذا الخيار من خلال البرامج.
isEmulated

قيمة منطقية

يتم محاكاتها بواسطة برنامج تشغيل الماسح الضوئي إذا كانت القيمة صحيحة.
الاسم

سلسلة

اسم الخيار باستخدام أحرف ASCII صغيرة وأرقام وشرطات لا يُسمح باستخدام علامات التشكيل.
title

سلسلة

عنوان قابل للطباعة من سطر واحد
النوع

OptionType

نوع البيانات الواردة في السمة value، وهو أمر ضروري لضبط هذا الخيار
الوحدة

OptionUnit

تمثّل هذه السمة وحدة القياس لهذا الخيار.
القيمة

string | number | boolean | number[] اختياري

تمثّل هذه السمة القيمة الحالية للخيار، إذا كان ذلك منطبقًا. يُرجى العِلم أنّ نوع بيانات هذه السمة يجب أن يتطابق مع نوع البيانات المحدّد في type.

ScanOptions

الخصائص

maxImages

number اختياري

عدد الصور المسموح بمسحها ضوئيًا القيمة التلقائية هي 1.
mimeTypes

string[] اختياري

أنواع MIME التي يقبلها المتصل.

ScanResults

الخصائص

dataUrls

string[]

مصفوفة من عناوين URL لصور البيانات بتنسيق يمكن تمريره كقيمة "src" إلى علامة صورة.
mimeType

سلسلة

نوع MIME الخاص بـ dataUrls.

SetOptionResult

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

الخصائص

الاسم

سلسلة

تشير إلى اسم الخيار الذي تم ضبطه.
نتيجة

OperationResult

تشير إلى نتيجة ضبط الخيار.

SetOptionsResponse

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

الخصائص

الخيارات

العنصر اختياري

عملية ربط معدَّلة بين المفتاح والقيمة من أسماء الخيارات إلى قيم ScannerOption التي تحتوي على الإعداد الجديد بعد محاولة ضبط جميع الخيارات المقدَّمة. تتضمّن هذه السمة البنية نفسها التي تتضمّنها السمة options في OpenScannerResponse.

سيتم ضبط هذه السمة حتى إذا لم يتم ضبط بعض الخيارات بنجاح، ولكن سيتم إلغاء ضبطها في حال تعذّر استرداد الإعدادات المعدَّلة (على سبيل المثال، إذا تم فصل الماسح الضوئي أثناء عملية المسح).
النتائج

SetOptionResult[]

مصفوفة من النتائج، واحدة لكل OptionSetting تم تمريرها.
scannerHandle

سلسلة

تقدِّم هذه السمة معرّف الماسح الضوئي الذي تم تمريره إلى setOptions().

StartScanOptions

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

الخصائص

التنسيق

سلسلة

تحدّد هذه السمة نوع MIME الذي سيتم عرض البيانات الممسوحة ضوئيًا به.
maxReadSize

number اختياري

في حال تحديد قيمة غير صفرية، يتم حصر الحد الأقصى للبايتات التي تم فحصها والتي يتم عرضها في ردّ readScanData واحد على هذه القيمة. أصغر قيمة مسموح بها هي 32768 (32 كيلوبايت). في حال عدم تحديد هذه السمة، قد يكون حجم الجزء الذي يتم عرضه كبيرًا مثل الصورة الممسوحة ضوئيًا بالكامل.

StartScanResponse

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

الخصائص

وظيفة

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

إذا كانت قيمة result هي SUCCESS، يتم توفير معرّف يمكن استخدامه لقراءة بيانات الفحص أو إلغاء المهمة.
نتيجة

OperationResult

نتيجة بدء عملية فحص إذا كانت القيمة هي SUCCESS، سيتم ملء السمة job.
scannerHandle

سلسلة

تعرض معرّف الماسح الضوئي نفسه الذي تم تمريره إلى startScan().

الطُرق

cancelScan()

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

chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
): Promise<CancelScanResponse>

يلغي عملية مسح ضوئي تم بدؤها ويعرض Promise يتم تنفيذه باستخدام العنصر CancelScanResponse. في حال استخدام دالة ردّ الاتصال، يتم تمرير الكائن إليها بدلاً من ذلك.

المعلمات

وظيفة

سلسلة

معرّف مهمة فحص نشطة تم عرضها سابقًا من خلال طلب إلى startScan.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: CancelScanResponse) => void
```
- رد
  
  CancelScanResponse

المرتجعات

Promise<CancelScanResponse>

closeScanner()

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

chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
): Promise<CloseScannerResponse>

تُغلِق هذه الطريقة الماسح الضوئي باستخدام المعرّف الذي تم تمريره وتعرض Promise يتم تنفيذه باستخدام عنصر CloseScannerResponse. في حال استخدام دالة ردّ الاتصال، يتم تمرير الكائن إليها بدلاً من ذلك. حتى إذا لم تنجح الاستجابة، يصبح المعرّف المقدَّم غير صالح ويجب عدم استخدامه في عمليات أخرى.

المعلمات

scannerHandle

سلسلة

تحدّد هذه السمة معرّف ماسح ضوئي مفتوح تم عرضه سابقًا من خلال طلب إلى openScanner.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: CloseScannerResponse) => void
```
- رد
  
  CloseScannerResponse

المرتجعات

Promise<CloseScannerResponse>

getOptionGroups()

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

chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
): Promise<GetOptionGroupsResponse>

تعرض هذه الطريقة أسماء المجموعات وخيارات الأعضاء من أداة فحص تم فتحها سابقًا باستخدام openScanner. يعرض هذا الإجراء Promise يتم تنفيذه باستخدام عنصر GetOptionGroupsResponse. إذا تم تمرير دالة ردّ اتصال إلى هذه الدالة، سيتم تمرير البيانات التي تم إرجاعها إليها بدلاً من ذلك.

المعلمات

scannerHandle

سلسلة

مقبض ماسح ضوئي مفتوح تم عرضه من خلال طلب إلى openScanner.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: GetOptionGroupsResponse) => void
```
- رد
  
  GetOptionGroupsResponse

المرتجعات

Promise<GetOptionGroupsResponse>

getScannerList()

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

chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
): Promise<GetScannerListResponse>

تعرض هذه الطريقة قائمة بأجهزة المسح الضوئي المتاحة وتعرض Promise يتم تنفيذه باستخدام عنصر GetScannerListResponse. إذا تم تمرير دالة ردّ اتصال إلى هذه الدالة، سيتم تمرير البيانات التي تم إرجاعها إليها بدلاً من ذلك.

المعلمات

تصفية

DeviceFilter

DeviceFilter تشير إلى أنواع الماسحات الضوئية التي يجب عرضها.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: GetScannerListResponse) => void
```
- رد
  
  GetScannerListResponse

المرتجعات

Promise<GetScannerListResponse>

openScanner()

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

chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
): Promise<OpenScannerResponse>

يفتح هذا الإجراء ماسحًا ضوئيًا للوصول الحصري ويعرض وعدًا يتم تنفيذه باستخدام عنصر OpenScannerResponse. إذا تم تمرير دالة ردّ اتصال إلى هذه الدالة، سيتم تمرير البيانات التي تم إرجاعها إليها بدلاً من ذلك.

المعلمات

scannerId

سلسلة

رقم تعريف الماسح الضوئي المطلوب فتحه هذه القيمة هي قيمة تم عرضها من طلب سابق إلى getScannerList.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: OpenScannerResponse) => void
```
- رد
  
  OpenScannerResponse

المرتجعات

Promise<OpenScannerResponse>

readScanData()

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

chrome.documentScan.readScanData(
  job: string,
  callback?: function,
): Promise<ReadScanDataResponse>

تقرأ هذه الطريقة الجزء التالي من بيانات الصورة المتاحة من معرّف مهمة نشطة، وتعرض Promise يتم تنفيذه باستخدام عنصر ReadScanDataResponse. في حال استخدام دالة ردّ الاتصال، يتم تمرير الكائن إليها بدلاً من ذلك.

**ملاحظة:**من المقبول أن تكون نتيجة الرد SUCCESS مع عضو data بطول صفر. هذا يعني أنّ الماسح الضوئي لا يزال يعمل ولكنّه لم يحصل بعد على بيانات إضافية. على المتصل الانتظار لفترة قصيرة ثم إعادة المحاولة.

عند اكتمال مهمة البحث، ستتضمّن الاستجابة قيمة النتيجة EOF. قد تحتوي هذه الاستجابة على عضو نهائي بقيمة data غير صفرية.

المعلمات

وظيفة

سلسلة

مقبض الوظيفة النشطة الذي تم عرضه سابقًا من startScan.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: ReadScanDataResponse) => void
```
- رد
  
  ReadScanDataResponse

المرتجعات

Promise<ReadScanDataResponse>

scan()

الوعد

chrome.documentScan.scan(
  options: ScanOptions,
  callback?: function,
): Promise<ScanResults>

تنفّذ عملية مسح ضوئي للمستند وتعرض Promise يتم تنفيذه باستخدام عنصر ScanResults. إذا تم تمرير دالة ردّ اتصال إلى هذه الدالة، سيتم تمرير البيانات التي تم إرجاعها إليها بدلاً من ذلك.

المعلمات

الخيارات

ScanOptions

كائن يحتوي على مَعلمات المسح الضوئي
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(result: ScanResults) => void
```
- نتيجة
  
  ScanResults

المرتجعات

Promise<ScanResults>

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

setOptions()

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

chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
): Promise<SetOptionsResponse>

تضبط هذه الطريقة الخيارات على الماسح الضوئي المحدّد وتعرض Promise يتم تنفيذه باستخدام كائن SetOptionsResponse يحتوي على نتيجة محاولة ضبط كل قيمة بترتيب الكائن OptionSetting الذي تم تمريره. في حال استخدام دالة ردّ الاتصال، يتم تمرير الكائن إليها بدلاً من ذلك.

المعلمات

scannerHandle

سلسلة

مقبض أداة الفحص لضبط الخيارات. يجب أن تكون هذه القيمة قد تم عرضها سابقًا من طلب إلى openScanner.
الخيارات

OptionSetting[]

قائمة تضم OptionSetting عنصر سيتم تطبيقه على الماسح الضوئي.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: SetOptionsResponse) => void
```
- رد
  
  SetOptionsResponse

المرتجعات

Promise<SetOptionsResponse>

startScan()

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

chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
): Promise<StartScanResponse>

يبدأ عملية مسح ضوئي على الماسح الضوئي المحدّد ويعرض Promise يتم تنفيذه باستخدام StartScanResponse. في حال استخدام دالة ردّ الاتصال، يتم تمرير الكائن إليها بدلاً من ذلك. إذا كانت المكالمة ناجحة، تتضمّن الاستجابة معرّف مهمة يمكن استخدامه في المكالمات اللاحقة لقراءة بيانات الفحص أو إلغاء عملية فحص.

المعلمات

scannerHandle

سلسلة

مقبض ماسح ضوئي مفتوح يجب أن تكون هذه القيمة قد تم عرضها سابقًا من طلب إلى openScanner.
الخيارات

StartScanOptions

كائن StartScanOptions يشير إلى الخيارات التي سيتم استخدامها في عملية البحث. يجب أن تتطابق السمة StartScanOptions.format مع إحدى الإدخالات التي تم عرضها في ScannerInfo الخاصة بالماسح الضوئي.
callback

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

تظهر المَعلمة callback على النحو التالي:
```
(response: StartScanResponse) => void
```
- رد
  
  StartScanResponse

المرتجعات

Promise<StartScanResponse>