browser.documentScan

الوصف

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

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

الأذونات

documentScan

مدى التوفّر

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome نظام التشغيل Chrome فقط
يتم عرض مدى توفّر الأعضاء الذين تمت إضافتهم لاحقًا من خلال واجهة برمجة التطبيقات مع هؤلاء الأعضاء.

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

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

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

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

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

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

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

  1. الاتصال بـ getScannerList() يتم عرض الماسحات الضوئية المتاحة في Promise يتم حلّه باستخدام GetScannerListResponse.

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

  2. اختَر ماسحًا ضوئيًا من الصفيف الذي تم عرضه واحفظ قيمة السمة scannerId.

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

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

  1. استدعِ openScanner()، مع إدخال معرّف الماسح الضوئي المحفوظ. وتعرض هذه الطريقة كائن Promise يتم حله باستخدام OpenScannerResponse. يحتوي عنصر الاستجابة على ما يلي:

    • موقع إلكتروني واحد (scannerHandle) عليك حفظه

    • An options property containing scanner-specific properties, which you'll need to set. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة "استرداد خيارات الماسح الضوئي".

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

  3. أنشئ مصفوفة من عناصر OptionSetting باستخدام قيم برمجية أو قيم يقدّمها المستخدم. لمزيد من المعلومات، يُرجى الاطّلاع على "ضبط خيارات الماسح الضوئي".

  4. مرِّر مصفوفة عناصر OptionSetting إلى setOptions() لضبط خيارات الماسح الضوئي. وتعرض Promise يتم حلّها باستخدام SetOptionsResponse. يحتوي هذا العنصر على نسخة معدَّلة من خيارات الماسح الضوئي التي تم استردادها في الخطوة 1 من إعداد الماسح الضوئي.

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

جارٍ البحث

  1. أنشِئ عنصر StartScanOptions ومرِّره إلى startScan(). وتعرض هذه الطريقة كائن Promise يتم تحليله باستخدام StartScanResponse. السمة job هي معرّف يمكن استخدامه لقراءة بيانات المسح الضوئي أو إلغاء المسح الضوئي.

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

  3. كرِّر الخطوة السابقة إلى أن تساوي السمة result القيمة EOF أو تظهر رسالة خطأ.

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

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

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

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

كما هو موضّح في قسم "إعدادات الماسح الضوئي"، يمكن أن يؤدي تغيير أحد الخيارات إلى تغيير القيود على خيار آخر. لهذا السبب، يحتوي setOptionsResponse (عنصر الاستجابة لـ setOptions()) على سمة options أخرى. استخدِم هذا لتحديث واجهة المستخدم. ثم كرر حسب الحاجة حتى يتم تعيين جميع الخيارات.

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

يمكنك ضبط خيارات الماسح الضوئي من خلال تمرير مصفوفة من عناصر OptionSetting إلى setOptions(). للاطّلاع على مثال، يُرجى مراجعة قسم مسح صفحة واحدة بحجم Letter ضوئيًا أدناه.

أمثلة

استرداد صفحة كملف ثنائي كبير (blob)

يوضّح هذا المثال طريقة واحدة لاسترداد صفحة من الماسح الضوئي كملف ثنائي كبير، ويوضّح استخدام startScan() وreadScanData() باستخدام قيمة OperationResult.

async function pageAsBlob(handle) {
  let response = await browser.documentScan.startScan(
      handle, {format: "image/jpeg"});
  if (response.result != browser.documentScan.OperationResult.SUCCESS) {
    return null;
  }
  const job = response.job;

  let imgParts = [];
  response = await browser.documentScan.readScanData(job);
  while (response.result == browser.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 browser.documentScan.readScanData(job);
  }
  if (response.result != browser.documentScan.OperationResult.EOF) {
    return null;
  }
  if (response.data && response.data.byteLength > 0) {
    imgParts.push(response.data);
  }
  return new Blob(imgParts, { type: "image/jpeg" });
}

مسح صفحة واحدة بحجم Letter ضوئيًا

يوضّح هذا المثال كيفية اختيار ماسح ضوئي وضبط خياراته وفتحه. بعد ذلك، يسترد محتويات صفحة واحدة ويغلق الماسح الضوئي. توضّح هذه العملية كيفية استخدام getScannerList() وopenScanner() وsetOptions() وcloseScanner(). يُرجى العِلم أنّه يتم استرداد محتوى الصفحة من خلال استدعاء الدالة pageAsBlob() من المثال السابق.

async function scan() {
    let response = await browser.documentScan.getScannerList({ secure: true });
    let scanner = await browser.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: browser.documentScan.OptionType.STRING,
                value: { value: source }
            });
            break;
        }
    }
    options.push({
        name: "tl-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 215.9  // 8.5" in mm
    });
    options.push({
        name: "tl-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 279.4  // 11" in mm
    });
    response = await browser.documentScan.setOptions(handle, options);

    let imgBlob = await pageAsBlob(handle);
    if (imgBlob != null) {
        // Insert imgBlob into DOM, save to disk, etc
    }
    await browser.documentScan.closeScanner(handle);
}

عرض الإعدادات

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

async function showConfig() {
  let response = await browser.documentScan.getScannerList({ secure: true });
  let scanner = await browser.documentScan.openScanner(
      response.scanners[0].scannerId);
  let groups = await browser.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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • وظيفة

    سلسلة

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

  • نتيجة

    OperationResult

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

CloseScannerResponse

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • نتيجة

    OperationResult

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

  • scannerHandle

    سلسلة

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

Configurability

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

كيفية تغيير خيار معيّن

Enum

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

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

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

ConnectionType

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من 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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • محلي

    قيمة منطقية اختيارية

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

  • آمن

    قيمة منطقية اختيارية

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

GetOptionGroupsResponse

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • مجموعات

    OptionGroup[] اختيارية

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

  • نتيجة

    OperationResult

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

  • scannerHandle

    سلسلة

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

GetScannerListResponse

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • نتيجة

    OperationResult

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

  • أجهزة المسح الضوئي

    ScannerInfo[]

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

OpenScannerResponse

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • الخيارات

    object اختياري

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

  • نتيجة

    OperationResult

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

  • scannerHandle

    string اختياري

    إذا كانت قيمة result هي SUCCESS، يتم عرض مؤشر للماسح الضوئي يمكن استخدامه لإجراء عمليات أخرى.

  • scannerId

    سلسلة

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

OperationResult

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

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

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

"UNSUPPORTED"
العملية غير متاحة.

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

‫"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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • قائمة

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

  • الحد الأقصى

    number اختيارية

  • دقيقة

    number اختيارية

  • quant

    number اختيارية

  • النوع

    ConstraintType

OptionGroup

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • الأعضاء

    string[]

    مصفوفة من أسماء الخيارات بالترتيب الذي يوفّره السائق

  • title

    سلسلة

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

OptionSetting

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • الاسم

    سلسلة

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

  • النوع

    OptionType

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

  • القيمة

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

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

OptionType

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من 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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

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

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

‫"BIT"
تمثّل القيمة عدد وحدات البت، مثل عمق اللون.

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

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

"PERCENT"
القيمة هي نسبة مئوية، مثل مستوى السطوع.

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

ReadScanDataResponse

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • البيانات

    ‫ArrayBuffer اختياري

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

  • estimatedCompletion

    number اختيارية

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

  • وظيفة

    سلسلة

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

  • نتيجة

    OperationResult

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

ScannerInfo

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • connectionType

    ConnectionType

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

  • deviceUuid

    سلسلة

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

  • imageFormats

    string[]

    مصفوفة من أنواع MIME التي يمكن طلبها لعمليات المسح الضوئي التي يتم عرضها

  • الشركة المصنّعة

    سلسلة

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

  • نموذج

    سلسلة

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

  • الاسم

    سلسلة

    اسم الماسح الضوئي الذي يمكن لشخص عادي قراءته ليظهر في واجهة المستخدم

  • protocolType

    سلسلة

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

  • scannerId

    سلسلة

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

  • آمن

    قيمة منطقية

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

ScannerOption

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من 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 والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • الاسم

    سلسلة

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

  • نتيجة

    OperationResult

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

SetOptionsResponse

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • الخيارات

    object اختياري

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

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

  • النتائج

    SetOptionResult[]

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

  • scannerHandle

    سلسلة

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

StartScanOptions

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • التنسيق

    سلسلة

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

  • maxReadSize

    number اختيارية

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

StartScanResponse

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • وظيفة

    string اختياري

    إذا كانت قيمة result هي SUCCESS، يتم توفير مؤشر يمكن استخدامه لقراءة بيانات المسح الضوئي أو إلغاء المهمة.

  • نتيجة

    OperationResult

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

  • scannerHandle

    سلسلة

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

الطُرق

cancelScan()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.cancelScan(
  job: string,
): Promise<CancelScanResponse>

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

المعلمات

  • وظيفة

    سلسلة

    يشير هذا الحقل إلى الاسم المعرِّف لمهمة مسح ضوئي نشطة تم إرجاعها سابقًا من طلب إلى startScan.

المرتجعات

  • تعرض هذه الطريقة كائن Promise يتم حله بالنتيجة.

closeScanner()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.closeScanner(
  scannerHandle: string,
): Promise<CloseScannerResponse>

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

المعلمات

  • scannerHandle

    سلسلة

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

المرتجعات

  • تعرض هذه الطريقة كائن Promise يتم حله بالنتيجة.

getOptionGroups()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.getOptionGroups(
  scannerHandle: string,
): Promise<GetOptionGroupsResponse>

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

المعلمات

  • scannerHandle

    سلسلة

    مؤشر الماسح الضوئي المفتوح الذي تم عرضه من طلب إلى openScanner.

المرتجعات

getScannerList()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.getScannerList(
  filter: DeviceFilter,
): Promise<GetScannerListResponse>

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

المعلمات

  • تصفية

    DeviceFilter

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

المرتجعات

  • تعرض هذه الطريقة كائن Promise الذي يحلّ النتيجة وقائمة الماسحات الضوئية.

openScanner()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.openScanner(
  scannerId: string,
): Promise<OpenScannerResponse>

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

المعلمات

  • scannerId

    سلسلة

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

المرتجعات

  • تعرض هذه الطريقة كائن Promise يتم حله بالنتيجة.

readScanData()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.readScanData(
  job: string,
): Promise<ReadScanDataResponse>

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

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

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

المعلمات

  • وظيفة

    سلسلة

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

المرتجعات

  • تعرض هذه الطريقة كائن Promise يتم حله بالنتيجة.

scan()

browser.documentScan.scan(
  options: ScanOptions,
): Promise<ScanResults>

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

المعلمات

  • الخيارات

    ScanOptions

    عنصر يحتوي على معلَمات المسح الضوئي

المرتجعات

  • Promise<ScanResults>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

setOptions()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
): Promise<SetOptionsResponse>

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

المعلمات

  • scannerHandle

    سلسلة

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

  • الخيارات

    OptionSetting[]

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

المرتجعات

  • تعرض هذه الطريقة كائن Promise يتم حله بالنتيجة.

startScan()

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
): Promise<StartScanResponse>

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

المعلمات

  • scannerHandle

    سلسلة

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

  • الخيارات

    StartScanOptions

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

المرتجعات

  • تعرض هذه الطريقة كائن Promise يتم حله بالنتيجة.