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(). تعرض هذه الدالة Promise يتم تنفيذه باستخدام عنصر ReadScanDataResponse. إذا تمت قراءة البيانات بنجاح، ستكون قيمة السمة result هي SUCCESS، وستتضمّن السمة data ArrayBuffer مع جزء من عملية الفحص. يُرجى العِلم أنّ estimatedCompletion يتضمّن نسبة مئوية مقدّرة من إجمالي البيانات التي تم تسليمها حتى الآن.

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

عند الوصول إلى نهاية عملية المسح الضوئي، اتّصِل بالرقم closeScanner() باستخدام معرّف الماسح الضوئي الذي تم حفظه في الخطوة 3. تعرض هذه الدالة Promise يتم تنفيذه باستخدام 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(). يعرض هذا الإجراء وعدًا يتم تنفيذه باستخدام عنصر 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 طويلة أو طويلة[]، وذلك حسب ما إذا كان الخيار يتضمّن أكثر من قيمة واحدة.

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

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

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

"المجموعة"
خيار التجميع لا توجد قيمة. يتم تضمين ذلك لأغراض التوافق، ولكن لن يتم عرضه عادةً في قيم 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()

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

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

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

المعلمات

وظيفة

سلسلة

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

المرتجعات

Promise<CancelScanResponse>

تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة.

closeScanner()

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

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

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

المعلمات

scannerHandle

سلسلة

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

المرتجعات

Promise<CloseScannerResponse>

تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة.

getOptionGroups()

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

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

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

المعلمات

scannerHandle

سلسلة

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

المرتجعات

Promise<GetOptionGroupsResponse>

تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة.

getScannerList()

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

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

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

المعلمات

تصفية

DeviceFilter

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

المرتجعات

Promise<GetScannerListResponse>

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

openScanner()

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

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

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

المعلمات

scannerId

سلسلة

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

المرتجعات

Promise<OpenScannerResponse>

تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة.

readScanData()

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

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

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

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

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

المعلمات

وظيفة

سلسلة

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

المرتجعات

Promise<ReadScanDataResponse>

تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة.

scan()

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

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

المعلمات

الخيارات

ScanOptions

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

المرتجعات

Promise<ScanResults>

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

تعرض هذه الطريقة Promise يتم تنفيذه مع نتائج الفحص.

setOptions()

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

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

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

المعلمات

scannerHandle

سلسلة

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

OptionSetting[]

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

المرتجعات

Promise<SetOptionsResponse>

تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة.

startScan()

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

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

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

المعلمات

scannerHandle

سلسلة

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

StartScanOptions

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

المرتجعات

Promise<StartScanResponse>

تعرض هذه الطريقة Promise يتم تنفيذه مع النتيجة.

chrome.documentScan تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الوصف

الأذونات

مدى التوفّر

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

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

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

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

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

جارٍ البحث

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

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

إنشاء واجهة مستخدم

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

أمثلة

استرداد صفحة ككائن ثنائي كبير

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

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

الأنواع

CancelScanResponse

الخصائص

CloseScannerResponse

الخصائص

Configurability

Enum

ConnectionType

Enum

ConstraintType

Enum

DeviceFilter

الخصائص

GetOptionGroupsResponse

الخصائص

GetScannerListResponse

الخصائص

OpenScannerResponse

الخصائص

OperationResult

Enum

OptionConstraint

الخصائص

OptionGroup

الخصائص

OptionSetting

الخصائص

OptionType

Enum

OptionUnit

Enum

ReadScanDataResponse

الخصائص

ScannerInfo

الخصائص

ScannerOption

الخصائص

ScanOptions

الخصائص

ScanResults

الخصائص

SetOptionResult

الخصائص

SetOptionsResponse

الخصائص

StartScanOptions

الخصائص

StartScanResponse

الخصائص

الطُرق

cancelScan()

المعلمات

المرتجعات

closeScanner()

المعلمات

المرتجعات

getOptionGroups()

المعلمات

المرتجعات

getScannerList()

المعلمات

المرتجعات

chrome.documentScan