chrome.documentScan

الوصف

يمكنك استخدام واجهة برمجة التطبيقات chrome.documentScan API لاكتشاف الصور واستردادها من الماسحات الضوئية للمستندات المرفقة.

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

الأذونات

documentScan

مدى التوفّر

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

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

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

الفحص البسيط

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

الفحص المعقد

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

الحملات أثناء التصفّح

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

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

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

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

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

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

    • سمة على scannerHandle وعليك حفظها.

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

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

  3. يمكنك إنشاء مصفوفة من عناصر OptionSetting باستخدام القيم الآلية أو القيم المقدَّمة من المستخدم. يمكنك الاطلاع على "ضبط خيارات الماسح الضوئي" للحصول على مزيد من المعلومات.

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

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

جارٍ الفحص

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

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

  3. كرِّر الخطوة السابقة إلى أن تساوي السمة 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

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

CloseScannerResponse

في انتظار المراجعة

أماكن إقامة

  • نتيجة

    OperationResult

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

  • scannerHandle

    سلسلة

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

Configurability

في انتظار المراجعة

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

التعداد

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

"Software_CONFIGURABLE"
يمكن ضبط هذا الخيار في البرنامج.

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

ConnectionType

في انتظار المراجعة

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

التعداد

"USB"

ConstraintType

في انتظار المراجعة

نوع البيانات للقيد الذي يمثّله OptionConstraint.

التعداد

"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، سيتم تقديم قائمة بمجموعات الخيارات بالترتيب الذي يوفّره برنامج تشغيل الماسح الضوئي.

  • نتيجة

    OperationResult

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

  • scannerHandle

    سلسلة

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

GetScannerListResponse

في انتظار المراجعة

أماكن إقامة

  • نتيجة

    OperationResult

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

  • ماسحات ضوئية

    ScannerInfo[]

    قائمة يُحتمَل أن تكون فارغة من برامج الفحص التي تطابق رمز DeviceFilter المقدَّم.

OpenScannerResponse

في انتظار المراجعة

أماكن إقامة

  • الخيارات

    الكائن اختياري

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

  • نتيجة

    OperationResult

    نتيجة فتح الماسح الضوئي. إذا كانت قيمة هذه السمة هي 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

في انتظار المراجعة

أماكن إقامة

  • قائمة

    string[]|number[] optional

  • الحد الأقصى

    الرقم اختياري

  • دقيقة

    الرقم اختياري

  • الكمّية

    الرقم اختياري

  • كتابة

    ConstraintType

OptionGroup

في انتظار المراجعة

أماكن إقامة

  • الأعضاء

    سلسلة[]

    مصفوفة من أسماء الخيارات بترتيب مقدَّمة من السائق.

  • title

    سلسلة

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

OptionSetting

في انتظار المراجعة

أماكن إقامة

  • اسم

    سلسلة

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

  • كتابة

    OptionType

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

  • القيمة

    string|number|boolean|number[] optional

    يشير إلى القيمة المطلوب ضبطها. يمكنك ترك السياسة بدون ضبط لطلب ضبط الإعداد التلقائي للخيارات التي تم فيها تفعيل 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() لاسترداد قائمة المجموعات مع خيارات الأعضاء فيها.

OptionUnit

في انتظار المراجعة

يشير هذا الحقل إلى نوع بيانات ScannerOption.unit.

التعداد

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

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

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

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

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

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

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

ReadScanDataResponse

في انتظار المراجعة

أماكن إقامة

  • البيانات

    ArrayBuffer اختيارية

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

  • estimatedCompletion

    الرقم اختياري

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

  • وظيفة

    سلسلة

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

  • نتيجة

    OperationResult

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

ScannerInfo

في انتظار المراجعة

أماكن إقامة

  • connectionType

    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

    سلسلة

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

  • كتابة

    OptionType

    تمثّل هذه السمة نوع البيانات المضمّنة في السمة value، وهي مطلوبة لضبط هذا الخيار.

  • الوحدة

    OptionUnit

    وحدة القياس لهذا الخيار.

  • القيمة

    string|number|boolean|number[] optional

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

ScanOptions

أماكن إقامة

  • maxImages

    الرقم اختياري

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

  • mimeTypes

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

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

ScanResults

أماكن إقامة

  • dataUrls

    سلسلة[]

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

  • mimeType

    سلسلة

    تمثّل هذه السمة نوع MIME للسمة dataUrls.

SetOptionResult

في انتظار المراجعة

أماكن إقامة

  • اسم

    سلسلة

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

  • نتيجة

    OperationResult

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

SetOptionsResponse

في انتظار المراجعة

أماكن إقامة

  • الخيارات

    الكائن اختياري

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

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

  • النتائج

    SetOptionResult[]

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

  • scannerHandle

    سلسلة

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

StartScanOptions

في انتظار المراجعة

أماكن إقامة

  • التنسيق

    سلسلة

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

  • maxReadSize

    الرقم اختياري

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

StartScanResponse

في انتظار المراجعة

أماكن إقامة

  • وظيفة

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

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

  • نتيجة

    OperationResult

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

  • scannerHandle

    سلسلة

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

الطُرق

cancelScan()

وعد في انتظار المراجعة
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

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

المَعلمات

  • وظيفة

    سلسلة

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (response: CancelScanResponse)=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

closeScanner()

وعد في انتظار المراجعة
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

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

المَعلمات

  • scannerHandle

    سلسلة

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (response: CloseScannerResponse)=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getOptionGroups()

وعد في انتظار المراجعة
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

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

المَعلمات

  • scannerHandle

    سلسلة

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (response: GetOptionGroupsResponse)=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getScannerList()

وعد في انتظار المراجعة
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

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

المَعلمات

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

openScanner()

وعد في انتظار المراجعة
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

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

المَعلمات

  • scannerId

    سلسلة

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (response: OpenScannerResponse)=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

readScanData()

وعد في انتظار المراجعة
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

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

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

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

المَعلمات

  • وظيفة

    سلسلة

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (response: ReadScanDataResponse)=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

scan()

وعد 
chrome.documentScan.scan(
  options: ScanOptions,
  callback?: function,
)

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

المَعلمات

  • الخيارات

    ScanOptions

    عنصر يحتوي على معلَمات فحص

  • معاودة الاتصال

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

    تبدو معلَمة 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[]

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (response: SetOptionsResponse)=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

startScan()

وعد في انتظار المراجعة
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

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

المَعلمات

  • scannerHandle

    سلسلة

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

  • الخيارات

    StartScanOptions

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (response: StartScanResponse)=>void

المرتجعات

  • تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.