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" ]
    }
  ]
}

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

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

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

أمثلة

استرداد صفحة كعنصر 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" });
}

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

يوضِّح هذا المثال كيفية اختيار أداة فحص وضبط خياراتها وفتحها. ثم يتم retrievingاسترداد محتوى صفحة واحدة وإغلاق الماسح الضوئي. توضِّح هذه العملية استخدام 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 والإصدارات الأحدث

أماكن إقامة

  • local

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

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

  • آمن

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

    عرض الماسح الضوئي الذي يستخدم نقلاً آمنًا فقط، مثل 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"
نجحت العملية.

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

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

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

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

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

"EOF"
لم تعُد هناك بيانات متاحة.

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

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

‫"COVER_OPEN"
غطاء الطابعة المسطحة مفتوح.

"IO_ERROR"
حدث خطأ أثناء التواصل مع الجهاز.

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

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

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

"غير متوفّر"
تم قطع اتصال الجهاز.

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

OptionConstraint

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

أماكن إقامة

  • قائمة

    سلسلة | عدد اختياري

  • الحد الأقصى

    رقم اختياري

  • دقيقة

    رقم اختياري

  • quant

    رقم اختياري

  • كتابة

    ConstraintType

OptionGroup

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

أماكن إقامة

  • الأعضاء

    string[]

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

  • title

    سلسلة

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

OptionSetting

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

أماكن إقامة

  • الاسم

    سلسلة

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

  • كتابة

    OptionType

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

  • القيمة

    سلسلة | عدد | قيمة منطقية | عدد[] اختياري

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

"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

    رقم اختياري

    إذا كان 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

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

  • القيمة

    سلسلة | عدد | قيمة منطقية | عدد[] اختياري

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

ScanOptions

أماكن إقامة

  • maxImages

    رقم اختياري

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

  • mimeTypes

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

    أنواع 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

    رقم اختياري

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

StartScanResponse

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

أماكن إقامة

  • وظيفة

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

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

  • نتيجة

    OperationResult

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

  • scannerHandle

    سلسلة

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

الطُرق

cancelScan()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

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

المعلمات

  • وظيفة

    سلسلة

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

  • ردّ الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (response: CancelScanResponse) => void

المرتجعات

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

closeScanner()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

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

المعلمات

  • scannerHandle

    سلسلة

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

  • ردّ الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (response: CloseScannerResponse) => void

المرتجعات

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

getOptionGroups()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

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

المعلمات

  • scannerHandle

    سلسلة

    تم عرض الاسم المعرِّف لأحد الماسح الضوئي المفتوحة بعد تلقّي مكالمة من openScanner.

  • ردّ الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (response: GetOptionGroupsResponse) => void

المرتجعات

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

getScannerList()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

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

المعلمات

المرتجعات

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

openScanner()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

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

المعلمات

  • scannerId

    سلسلة

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

  • ردّ الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (response: OpenScannerResponse) => void

المرتجعات

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

readScanData()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

تقرأ هذه الدالة الجزء التالي من بيانات الصورة المتاحة من معرّف مهمة نشط، وتُرجع وعدًا يتم حلّه باستخدام عنصر 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()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
)

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

المعلمات

  • scannerHandle

    سلسلة

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

  • الخيارات

    OptionSetting[]

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

  • ردّ الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (response: SetOptionsResponse) => void

المرتجعات

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

startScan()

الوعد الإصدار 125 من Chrome والإصدارات الأحدث 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

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

المعلمات

  • scannerHandle

    سلسلة

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

  • الخيارات

    StartScanOptions

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

  • ردّ الاتصال

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

    تظهر المَعلمة callback على النحو التالي: 

    (response: StartScanResponse) => void

المرتجعات

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