browser.documentScan

شرح

از chrome.documentScan API برای پیدا کردن و بازیابی تصاویر از اسکنرهای سند متصل‌شده استفاده کنید.

Document Scan API به‌گونه‌ای طراحی شده است که به برنامه‌ها و افزونه‌ها اجازه می‌دهد محتوای اسناد کاغذی را در اسکنر سند متصل‌شده مشاهده کنند.

اجازه‌ها

documentScan

دردسترس بودن

Chrome نسخه ۴۴ و بالاتر مرورگر.* از Chrome نسخه ۱۴۸ فقط ChromeOS
دردسترس بودن برای اعضای API که بعداً اضافه می‌شوند با آن اعضا نشان داده می‌شود.

مفاهیم و کاربرد

این میانای برنامه‌سازی کاربردی از دو روش برای اسکن کردن اسناد پشتیبانی می‌کند. اگر مورد استفاده شما می‌تواند با هر اسکنری کار کند و نیازی به کنترل پیکربندی ندارد، از روش scan() استفاده کنید. موارد استفاده پیچیده‌تر به ترکیبی از روش‌ها نیاز دارند، که فقط در Chrome نسخه ۱۲۴ و جدیدتر پشتیبانی می‌شوند.

اسکن کردن ساده

برای موارد استفاده ساده، یعنی مواردی که می‌توانند با هر اسکنری کار کنند و نیازی به کنترل پیکربندی ندارند، scan() را فراخوانی کنید. این روش یک شیء ScanOptions را می‌گیرد و یک Promise برمی‌گرداند که با یک شیء ScanResults حل می‌شود. قابلیت‌های این گزینه به تعداد اسکن‌ها و انواع MIME که توسط تماس‌گیرنده پذیرفته می‌شود محدود است. اسکن‌ها به‌صورت نشانی وب برگردانده می‌شوند تا در برچسب <img> برای میانای کاربر نمایش داده شوند.

اسکن پیچیده

اسکن‌های پیچیده در سه مرحله انجام می‌شوند که در این بخش توضیح داده شده است. این طرح کلی همه آرگومان‌های روش یا همه ویژگی‌های برگردانده‌شده در پاسخ را شرح نمی‌دهد. این فقط برای ارائه راهنمای کلی برای نوشتن کد اسکنر است.

Discovery

  1. با getScannerList() تماس بگیرید. اسکنرهای دردسترس در یک Promise برگردانده می‌شوند که با GetScannerListResponse حل می‌شود.

    • شیء پاسخ حاوی آرایه‌ای از اشیای ScannerInfo است.
    • اگر اسکنر از چند پروتکل یا روش اتصال پشتیبانی کند، آرایه ممکن است حاوی چند ورودی برای یک اسکنر باشد.

  2. اسکنری را از آرایه برگردانده‌شده انتخاب کنید و مقدار ویژگی scannerId آن را ذخیره کنید.

    از ویژگی‌های اشیای ScannerInfo تکی برای تشخیص دادن بین چندین شیء برای یک اسکنر استفاده کنید. اشیاء مربوط به یک اسکنر مقدار یکسانی برای ویژگی deviceUuid خواهند داشت. ScannerInfo همچنین حاوی ویژگی imageFormats است که شامل آرایه‌ای از انواع تصویر پشتیبانی‌شده است.

پیکربندی اسکنر

  1. با ارسال شناسه اسکنر ذخیره‌شده، openScanner() را فراخوانی کنید. این متد یک Promise برمی‌گرداند که با یک OpenScannerResponse حل می‌شود. شیء پاسخ حاوی این موارد است:

    • یک ویژگی scannerHandle که باید آن را ذخیره کنید.

    • یک ویژگی گزینه‌ها که حاوی ویژگی‌های مختص اسکنر است و باید آن را تنظیم کنید. برای اطلاعات بیشتر، به «بازیابی گزینه‌های اسکنر» مراجعه کنید.

  2. (اختیاری) اگر لازم است کاربر مقادیری برای گزینه‌های اسکنر ارائه دهد، یک میانای کاربر بسازید. به گزینه‌های اسکنر ارائه‌شده در مرحله قبل نیاز خواهید داشت و باید گروه‌های گزینه‌های ارائه‌شده توسط اسکنر را بازیابی کنید. برای اطلاعات بیشتر، به ساختن میانای کاربر مراجعه کنید.

  3. آرایه‌ای از اشیای OptionSetting را بااستفاده از مقادیر برنامه‌ای یا ارائه‌شده توسط کاربر بسازید. برای اطلاعات بیشتر، به «تنظیم گزینه‌های اسکنر» مراجعه کنید.

  4. آرایه اشیاء OptionSetting را به setOptions() ارسال کنید تا گزینه‌های اسکنر را تنظیم کنید. این متد یک Promise برمی‌گرداند که با SetOptionsResponse حل می‌شود. این شیء حاوی نسخه به‌روزشده‌ای از گزینه‌های اسکنر است که در مرحله ۱ پیکربندی اسکنر بازیابی شده است.

    ازآنجایی‌که تغییر یک گزینه می‌تواند محدودیت‌های گزینه دیگری را تغییر دهد، ممکن است لازم باشد این مراحل را چندین بار تکرار کنید.

اسکن کردن

  1. شیء StartScanOptions بسازید و آن را به startScan() ارسال کنید. این متد یک Promise برمی‌گرداند که با یک StartScanResponse حل می‌شود. ویژگی job آن دسته‌ای است که از آن برای خواندن داده‌های اسکن یا لغو اسکن استفاده خواهید کرد.

  2. دستگیره کار را به readScanData() منتقل کنید. این متد یک Promise برمی‌گرداند که با یک شیء ReadScanDataResponse حل می‌شود. اگر داده‌ها با موفقیت خوانده شود، ویژگی result آن برابر با SUCCESS است و ویژگی data آن حاوی ArrayBuffer با بخشی از اسکن است. توجه داشته باشید که estimatedCompletion حاوی درصد تخمینی از کل داده‌هایی است که تاکنون تحویل داده شده است.

  3. مرحله قبلی را تکرار کنید تا زمانی که ویژگی result برابر با EOF یا خطا شود.

وقتی اسکن به پایان رسید، closeScanner() را با دسته اسکنر ذخیره‌شده در مرحله ۳ فراخوانی کنید. این روش یک Promise برمی‌گرداند که با CloseScannerResponse حل می‌شود. فراخوانی cancelScan() در هر زمانی پس‌از ایجاد کار، اسکن را پایان می‌دهد.

اشیاء پاسخ

همه روش‌ها یک Promise برمی‌گردانند که با یک شیء پاسخ از نوعی حل می‌شود. بیشتر این موارد حاوی ویژگی result هستند که مقدار آن عضوی از OperationResult است. برخی‌از ویژگی‌های اشیای پاسخ حاوی مقدار نخواهند بود، مگراینکه مقدار result مقدار خاصی داشته باشد. این روابط در مرجع هر شیء پاسخ شرح داده شده است.

برای مثال، OpenScannerResponse.scannerHandle فقط زمانی مقدار خواهد داشت که OpenScannerResponse.result برابر با SUCCESS باشد.

گزینه‌های اسکنر

گزینه‌های اسکنر بسته به دستگاه بسیار متفاوت است. درنتیجه، امکان منعکس کردن گزینه‌های اسکنر به‌طور مستقیم در documentScan API وجود ندارد. برای دور زدن این مشکل، OpenScannerResponse (بازیابی‌شده بااستفاده از openScanner()) و SetOptionsResponse (شیء پاسخ برای setOptions()) حاوی ویژگی options هستند که شیء حاوی گزینه‌های مختص اسکنر است. هر گزینه یک نگاشت مقدار کلید است که در آن کلید یک گزینه مختص دستگاه است و مقدار یک نمونه از ScannerOption است.

ساختار آن معمولاً به این شکل است:

{
  "key1": { scannerOptionInstance }
  "key2": { scannerOptionInstance }
}

برای مثال، اسکنری را تصور کنید که گزینه‌هایی با نام «منبع» و «وضوح» برمی‌گرداند. ساختار شیء options برگردانده‌شده چیزی شبیه به مثال زیر خواهد بود. برای سادگی، فقط بخشی از پاسخ‌های ScannerOption نشان داده شده است.

{
  "source": {
    "name": "source",
    "type": OptionType.STRING,
...
},
  "resolution": {
    "name": "resolution",
    "type": OptionType.INT,
...
  },
...
}

ساختن واسط کاربر

اگرچه برای استفاده از این میانای برنامه‌سازی کاربردی الزامی نیست، ممکن است بخواهید کاربر مقدار را برای گزینه خاصی انتخاب کند. این کار به میانای کاربر نیاز دارد. از OpenScannerResponse (بازشده توسط openScanner()) برای بازیابی گزینه‌های اسکنر متصل‌شده استفاده کنید (همان‌طور که در بخش قبلی توضیح داده شد).

برخی‌از اسکنرها گزینه‌ها را به‌روش‌های مختص دستگاه گروه‌بندی می‌کنند. این گروه‌ها بر رفتار گزینه‌ها تأثیر نمی‌گذارند، اما چون ممکن است در اسناد محصول اسکنر به آن‌ها اشاره شده باشد، باید به کاربر نشان داده شوند. می‌توانید این گروه‌ها را با فراخوانی getOptionGroups() بازیابی کنید. این کار یک Promise برمی‌گرداند که با یک شیء GetOptionGroupsResponse حل می‌شود. ویژگی groups آن حاوی آرایه‌ای از گروه‌های مختص اسکنر است. از اطلاعات موجود در این گروه‌ها برای سازمان‌دهی گزینه‌ها در OpenScannerResponse برای نمایش استفاده کنید.

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

همان‌طور که در پیکربندی «اسکنر» ذکر شده است، تغییر یک گزینه می‌تواند محدودیت‌های گزینه دیگری را تغییر دهد. به همین دلیل است که setOptionsResponse (شیء پاسخ برای setOptions()) حاوی ویژگی options دیگری است. از این برای به‌روزرسانی میانای کاربر استفاده کنید. سپس درصورت نیاز تکرار کنید تا همه گزینه‌ها تنظیم شوند.

تنظیم گزینه‌های اسکنر

گزینه‌های اسکنر را با ارسال آرایه‌ای از اشیای OptionSetting به setOptions() تنظیم کنید. برای مثال، بخش اسکن کردن یک صفحه با اندازه Letter را در زیر ببینید.

مثال‌ها

بازیابی صفحه به‌عنوان حباب

این مثال یک روش برای بازیابی صفحه از اسکنر به‌عنوان حبابک را نشان می‌دهد و نحوه استفاده از startScan() و readScanData() را بااستفاده از مقدار OperationResult نشان می‌دهد.

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

  let imgParts = [];
  response = await browser.documentScan.readScanData(job);
  while (response.result == browser.documentScan.OperationResult.SUCCESS) {
    if (response.data && response.data.byteLength > 0) {
        imgParts.push(response.data);
    } else {
      // Delay so hardware can make progress.
      await new Promise(r => setTimeout(r, 100));
    }
    response = await browser.documentScan.readScanData(job);
  }
  if (response.result != browser.documentScan.OperationResult.EOF) {
    return null;
  }
  if (response.data && response.data.byteLength > 0) {
    imgParts.push(response.data);
  }
  return new Blob(imgParts, { type: "image/jpeg" });
}

اسکن کردن یک صفحه با اندازه نامه

این مثال نشان می‌دهد که چگونه اسکنری را انتخاب کنید، گزینه‌های آن را تنظیم کنید، و آن را باز کنید. سپس محتوای یک صفحه را بازیابی می‌کند و اسکنر را می‌بندد. این فرایند نحوه استفاده از getScannerList()،‏ openScanner()،‏ setOptions()، و closeScanner() را نشان می‌دهد. توجه داشته باشید که محتوای صفحه با فراخوانی تابع pageAsBlob() از مثال قبلی بازیابی می‌شود.

async function scan() {
    let response = await browser.documentScan.getScannerList({ secure: true });
    let scanner = await browser.documentScan.openScanner(
        response.scanners[0].scannerId);
    const handle = scanner.scannerHandle;

    let options = [];
    for (source of scanner.options["source"].constraint.list) {
        if (source.includes("ADF")) {
            options.push({
                name: "source",
                type: browser.documentScan.OptionType.STRING,
                value: { value: source }
            });
            break;
        }
    }
    options.push({
        name: "tl-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 215.9  // 8.5" in mm
    });
    options.push({
        name: "tl-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 279.4  // 11" in mm
    });
    response = await browser.documentScan.setOptions(handle, options);

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

نمایش پیکربندی

همان‌طور که در جای دیگری گفته شد، برای نشان دادن گزینه‌های پیکربندی اسکنر به کاربر، علاوه‌بر گزینه‌های اسکنر که از تماس با openScanner() برگردانده شده است، باید getOptionGroups() فراخوانی شود. این کار برای این است که گزینه‌ها در گروه‌های تعریف‌شده توسط سازنده به کاربران نشان داده شود. این مثال نحوه انجام این کار را نشان می‌دهد.

async function showConfig() {
  let response = await browser.documentScan.getScannerList({ secure: true });
  let scanner = await browser.documentScan.openScanner(
      response.scanners[0].scannerId);
  let groups = await browser.documentScan.getOptionGroups(scanner.scannerHandle);

  for (const group of groups.groups) {
    console.log("=== " + group.title + " ===");
    for (const member of group.members) {
      const option = scanner.options[member];
      if (option.isActive) {
        console.log("  " + option.name + " = " + option.value);
      } else {
        console.log("  " + option.name + " is inactive");
      }
    }
  }
}

انواع

CancelScanResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • شغل

    رشته

    همان شناسه کاری را که به cancelScan() ارسال شده بود ارائه می‌دهد.

  • نتیجه

    OperationResult

    نتیجه لغو اسکن پس‌زمینه. اگر نتیجه OperationResult.SUCCESS یا OperationResult.CANCELLED باشد، اسکن لغو شده است و اسکنر آماده شروع اسکن جدید است. اگر نتیجه OperationResult.DEVICE_BUSY باشد، اسکنر هنوز درحال پردازش لغو درخواست‌شده است؛ تماس‌گیرنده باید کمی صبر کند و دوباره درخواست را امتحان کند. مقادیر نتیجه دیگر نشان‌دهنده خطای دائمی است که نباید دوباره امتحان شود.

CloseScannerResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • نتیجه

    OperationResult

    نتیجه بستن اسکنر. حتی اگر این مقدار SUCCESS نباشد، دسته نامعتبر خواهد بود و نباید برای عملیات‌های بعدی استفاده شود.

  • scannerHandle

    رشته

    همان دسته اسکنر که به closeScanner ارسال شده است.

Configurability

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

چگونه می‌توان گزینه‌ای را تغییر داد.

شمارشی

"NOT_CONFIGURABLE"
گزینه فقط خواندنی است.

«SOFTWARE_CONFIGURABLE»
این گزینه را می‌توان در نرم‌افزار تنظیم کرد.

«HARDWARE_CONFIGURABLE»
این گزینه را کاربر می‌تواند با تغییر وضعیت یا فشار دادن دکمه‌ای در اسکنر تنظیم کند.

ConnectionType

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

نشان می‌دهد اسکنر چگونه به رایانه متصل شده است.

شمارشی

"UNSPECIFIED"

"USB"

«NETWORK»

ConstraintType

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

نوع داده محدودیت که با 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

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • محلی

    بولی اختیاری

    فقط اسکنرهایی را برگردانید که مستقیماً به رایانه متصل هستند.

  • ایمن کردن

    بولی اختیاری

    فقط اسکنرهایی را برگردانید که از انتقال امن، مثل USB یا TLS، استفاده می‌کنند.

GetOptionGroupsResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • گروه‌ها

    OptionGroup[] اختیاری

    اگر result SUCCESS باشد، فهرستی از گروه‌های گزینه‌ها را به‌ترتیبی که درایور اسکنر ارائه کرده است ارائه می‌دهد.

  • نتیجه

    OperationResult

    نتیجه دریافت گروه‌های گزینه. اگر مقدار این SUCCESS باشد، خصوصیت groups درج خواهد شد.

  • scannerHandle

    رشته

    همان دسته اسکنر که به getOptionGroups ارسال شده است.

GetScannerListResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • نتیجه

    OperationResult

    نتیجه شمارش. توجه داشته باشید که حتی اگر این نشان‌دهنده خطا باشد، ممکن است نتایج جزئی برگردانده شود.

  • اسکنرها

    ScannerInfo[]

    فهرستی از اسکنرها که احتمالاً خالی است و با DeviceFilter ارائه‌شده مطابقت دارد.

OpenScannerResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • گزینه‌ها

    شیء اختیاری

    اگر result SUCCESS باشد، نگاشت مقدار کلید را ارائه می‌دهد که در آن کلید گزینه‌ای مختص دستگاه و مقدار نمونه‌ای از ScannerOption است.

  • نتیجه

    OperationResult

    نتیجه باز کردن اسکنر. اگر مقدار این SUCCESS باشد، دارایی‌های scannerHandle و options درج خواهند شد.

  • scannerHandle

    رشته اختیاری

    اگر result برابر با SUCCESS باشد، دستگیره‌ای برای اسکنر است که می‌تواند برای عملیات بیشتر استفاده شود.

  • scannerId

    رشته

    شناسه اسکنر به openScanner() ارسال شد.

OperationResult

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

یک enum که نتیجه هر عملیات را نشان می‌دهد.

شمارشی

«نامشخص»
خطای نامشخص یا عمومی رخ داده است.

«SUCCESS»
عملیات با موفقیت انجام شد.

«پشتیبانی‌نشده»
این عملیات پشتیبانی نمی‌شود.

«لغوشده»
عملیات لغو شد.

«DEVICE_BUSY»
دستگاه مشغول است.

«نامعتبر»
داده یا متغیر مستقل ارسال‌شده به روش معتبر نیست.

«WRONG_TYPE»
مقدار ارائه‌شده نوع داده اشتباهی برای گزینه اصلی است.

«EOF»
داده دیگری دردسترس نیست.

«ADF_JAMMED»
تغذیه سند گیر کرده است.

«ADF_EMPTY»
تغذیه سند خالی است.

"COVER_OPEN"
درب اسکنر تخت باز است.

«IO_ERROR»
هنگام برقراری ارتباط با دستگاه خطایی روی داد.

«ACCESS_DENIED»
دستگاه به اصالت‌سنجی نیاز دارد.

«NO_MEMORY»
حافظه کافی در Chromebook برای تکمیل عملیات دردسترس نیست.

«غیرقابل‌دسترس»
دستگاه قابل‌دسترس نیست.

«ناموجود»
اتصال دستگاه قطع است.

«INTERNAL_ERROR»
خطایی در جایی غیراز برنامه فراخواننده روی داده است.

OptionConstraint

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • فهرست

    string[] | number[] اختیاری

  • حداکثر

    شماره اختیاری

  • دقیقه

    شماره اختیاری

  • quant

    شماره اختیاری

OptionGroup

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • اعضاء

    string[]

    آرایه‌ای از نام‌های گزینه‌ها به ترتیبی که راننده ارائه کرده است.

  • عنوان

    رشته

    عنوانی قابل‌چاپ ارائه می‌دهد، برای مثال «گزینه‌های هندسه».

OptionSetting

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • نام

    رشته

    نام گزینه را برای تنظیم نشان می‌دهد.

  • نوع

    OptionType

    نوع داده گزینه را نشان می‌دهد. نوع داده درخواست‌شده باید با نوع داده واقعی گزینه اصلی مطابقت داشته باشد.

  • مقدار

    رشته | عدد | بولی | عدد[] اختیاری

    مقداری را که باید تنظیم شود نشان می‌دهد. برای درخواست تنظیم خودکار برای گزینه‌هایی که autoSettable را فعال کرده‌اند، تنظیم‌نشده باقی بگذارید. نوع داده ارائه‌شده برای value باید با type مطابقت داشته باشد.

OptionType

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

نوع داده یک گزینه.

شمارشی

«UNKNOWN»
نوع داده گزینه ناشناخته است. خصوصیت value لغو تنظیم خواهد شد.

«BOOL»
ویژگی value یکی از truefalse خواهد بود.

«INT»
عدد صحیح ۳۲ بیتی علامت‌دار. ویژگی value بسته به اینکه گزینه بیش‌از یک مقدار داشته باشد یا نه، long یا []long خواهد بود.

«ثابت»
یک عدد اعشاری با دقت مضاعف در محدوده ۳۲۷۶۸- تا ۳۲۷۶۷٫۹۹۹۹ با وضوح ۱/۶۵۵۳۵. ویژگی value بسته به اینکه گزینه بیش‌از یک مقدار داشته باشد، double یا double[] خواهد بود. مقادیر دوبرابری که نمی‌توانند دقیقاً نشان داده شوند، به محدوده و دقت دردسترس گرد خواهند شد.

«رشته»
دنباله‌ای از هر بایت به‌جز NUL ('\0'). خصوصیت value یک DOMString خواهد بود.

«BUTTON»
گزینه‌ای از این نوع مقدار ندارد. درعوض، تنظیم گزینه‌ای از این نوع باعث ایجاد عارضه جانبی مختص گزینه در درایور اسکنر می‌شود. برای مثال، یک گزینه از نوع دکمه می‌تواند توسط یک درایور اسکنر استفاده شود تا وسیله‌ای برای انتخاب مقادیر پیش‌فرض یا دستور دادن به یک تغذیه‌کننده خودکار سند برای رفتن به برگه کاغذ بعدی فراهم کند.

«GROUP»
گزینه گروه‌بندی. بدون مقدار. این مورد برای سازگاری گنجانده شده است، اما معمولاً در مقادیر ScannerOption برگردانده نمی‌شود. از getOptionGroups() برای بازیابی فهرست گروه‌ها با گزینه‌های اعضای آن‌ها استفاده کنید.

OptionUnit

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

نوع داده را برای ScannerOption.unit نشان می‌دهد.

شمارشی

«UNITLESS»
مقدار عددی بدون واحد است. برای مثال، می‌تواند یک آستانه باشد.

«PIXEL»
مقدار تعداد پیکسل‌ها است، برای مثال، ابعاد اسکن.

«BIT»
مقدار تعداد بیت‌ها است، برای مثال، عمق رنگ.

«MM»
مقدار برحسب میلی‌متر اندازه‌گیری می‌شود، برای مثال، ابعاد اسکن.

«DPI»
این مقدار با نقطه در اینچ اندازه‌گیری می‌شود، برای مثال، وضوح.

«PERCENT»
مقدار به‌صورت درصد است، مثلاً روشنایی.

«میکروثانیه»
مقدار برحسب میکروثانیه اندازه‌گیری می‌شود، برای مثال، زمان نوردهی.

ReadScanDataResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • داده

    ArrayBuffer اختیاری

    اگر result SUCCESS باشد، حاوی بخش بعدی داده‌های تصویر اسکن‌شده است. اگر result برابر با EOF باشد، حاوی آخرین بخش از داده‌های تصویر اسکن‌شده است.

  • estimatedCompletion

    شماره اختیاری

    اگر result برابر با SUCCESS باشد، تخمینی از مقدار کل داده‌های اسکن که تاکنون تحویل داده شده است، در محدوده ۰ تا ۱۰۰.

  • شغل

    رشته

    دستگیره کار را که به readScanData() ارسال شده است ارائه می‌دهد.

  • نتیجه

    OperationResult

    نتیجه خواندن داده‌ها. اگر مقدار آن SUCCESS باشد، data حاوی تکه بعدی (احتمالاً با طول صفر) داده‌های تصویر است که برای خواندن آماده است. اگر مقدار آن EOF باشد، data حاوی آخرین بخش از داده‌های تصویر است.

ScannerInfo

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • connectionType

    ConnectionType

    نشان می‌دهد اسکنر چگونه به رایانه متصل شده است.

  • deviceUuid

    رشته

    برای مطابقت دادن با سایر ورودی‌های ScannerInfo که به همان دستگاه فیزیکی اشاره می‌کنند.

  • imageFormats

    string[]

    آرایه‌ای از انواع MIME که می‌توان برای اسکن‌های برگردانده‌شده درخواست کرد.

  • سازنده

    رشته

    سازنده اسکنر.

  • مدل

    رشته

    مدل اسکنر درصورت دردسترس بودن، یا شرحی کلی.

  • نام

    رشته

    نامی قابل‌خواندن برای انسان برای اسکنر جهت نمایش در واسط کاربر.

  • protocolType

    رشته

    شرحی قابل‌خواندن برای انسان از پروتکل یا درایور مورداستفاده برای دسترسی به اسکنر، مانند Mopria،‏ WSD، یا epsonds. این ویژگی عمدتاً برای این مفید است که اگر دستگاهی از چند پروتکل پشتیبانی می‌کند، کاربر بتواند بین پروتکل‌ها انتخاب کند.

  • scannerId

    رشته

    شناسه اسکنر خاص.

  • ایمن کردن

    بولی

    اگر درست باشد، انتقال اتصال اسکنر نمی‌تواند توسط شنونده غیرفعال، مانند TLS یا USB، رهگیری شود.

ScannerOption

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • پیکربندی‌پذیری

    پیکربندی‌پذیری

    نشان می‌دهد که آیا و چگونه می‌توان گزینه را تغییر داد.

  • محدودیت

    OptionConstraint اختیاری

    OptionConstraint را در گزینه اسکنر فعلی تعریف می‌کند.

  • description

    رشته

    توضیح طولانی‌تر گزینه.

  • isActive

    بولی

    نشان می‌دهد که گزینه فعال است و می‌توان آن را تنظیم یا بازیابی کرد. اگر نادرست باشد، ویژگی value تنظیم نخواهد شد.

  • isAdvanced

    بولی

    نشان می‌دهد که واسط کاربر نباید این گزینه را به‌طور پیش‌فرض نمایش دهد.

  • isAutoSettable

    بولی

    می‌تواند به‌طور خودکار توسط درایور اسکنر تنظیم شود.

  • isDetectable

    بولی

    نشان می‌دهد که این گزینه را می‌توان از نرم‌افزار شناسایی کرد.

  • isEmulated

    بولی

    اگر درست باشد، توسط درایور اسکنر شبیه‌سازی می‌شود.

  • نام

    رشته

    نام گزینه بااستفاده از حروف کوچک ASCII، اعداد، و خط تیره. نشانه‌های زیروزبر مجاز نیست.

  • عنوان

    رشته

    عنوان یک‌خطی قابل‌چاپ.

  • نوع

    OptionType

    نوع داده موجود در ویژگی value که برای تنظیم این گزینه لازم است.

  • واحد

    OptionUnit

    واحد اندازه‌گیری این گزینه.

  • مقدار

    رشته | عدد | بولی | عدد[] اختیاری

    مقدار فعلی گزینه، درصورت مرتبط بودن. توجه داشته باشید که نوع داده این ویژگی باید با نوع داده مشخص‌شده در type مطابقت داشته باشد.

ScanOptions

مشخصات

  • maxImages

    شماره اختیاری

    تعداد تصاویر اسکن‌شده مجاز. پیش‌فرض ۱ است.

  • mimeTypes

    رشته[] اختیاری

    انواع MIME که تماس‌گیرنده می‌پذیرد.

ScanResults

مشخصات

  • dataUrls

    string[]

    آرایه‌ای از نشانی‌های وب تصویر داده در فرمی که می‌تواند به‌عنوان مقدار «src» به برچسب تصویر ارسال شود.

  • mimeType

    رشته

    نوع MIME dataUrls.

SetOptionResult

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • نام

    رشته

    نام گزینه‌ای را که تنظیم شده است نشان می‌دهد.

  • نتیجه

    OperationResult

    نتیجه تنظیم گزینه را نشان می‌دهد.

SetOptionsResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • گزینه‌ها

    شیء اختیاری

    نگاشت کلید-مقدار به‌روزشده از نام‌های گزینه به مقادیر ScannerOption که حاوی پیکربندی جدید پس‌از تلاش برای تنظیم همه گزینه‌های ارائه‌شده است. این ساختار مشابهی با ویژگی options در OpenScannerResponse دارد.

    این ویژگی حتی اگر برخی‌از گزینه‌ها با موفقیت تنظیم نشده باشند تنظیم خواهد شد، اما اگر بازیابی پیکربندی به‌روزشده ناموفق باشد (برای مثال، اگر اسکنر در اواسط اسکن قطع شود) تنظیم نخواهد شد.

  • نتایج

    SetOptionResult[]

    آرایه‌ای از نتایج، هرکدام برای هر OptionSetting ارسال‌شده.

  • scannerHandle

    رشته

    دستگیره اسکنر ارسال‌شده به setOptions() را ارائه می‌دهد.

StartScanOptions

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • قالب

    رشته

    نوع MIME را برای برگرداندن داده‌های اسکن‌شده مشخص می‌کند.

  • maxReadSize

    شماره اختیاری

    اگر مقدار غیرصفر مشخص شده باشد، حداکثر بایت‌های اسکن‌شده برگردانده‌شده در یک پاسخ readScanData را به آن مقدار محدود می‌کند. کوچک‌ترین مقدار مجاز ۳۲۷۶۸ (۳۲ کیلوبایت) است. اگر این ویژگی مشخص نشده باشد، اندازه تکه برگردانده‌شده ممکن است به‌اندازه کل تصویر اسکن‌شده باشد.

StartScanResponse

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

  • شغل

    رشته اختیاری

    اگر result SUCCESS باشد، دستگیره‌ای ارائه می‌دهد که می‌توان از آن برای خواندن داده‌های اسکن یا لغو کردن کار استفاده کرد.

  • نتیجه

    OperationResult

    نتیجه شروع اسکن. اگر مقدار این SUCCESS باشد، خصوصیت job درج خواهد شد.

  • scannerHandle

    رشته

    همان دسته اسکنر را که به startScan() ارسال شده است ارائه می‌دهد.

روش‌ها

cancelScan()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.cancelScan(
  job: string,
): Promise<CancelScanResponse>

اسکن شروع‌شده را لغو می‌کند و یک Promise برمی‌گرداند که با شیء CancelScanResponse حل می‌شود. اگر از فراخوانی برگشتی استفاده شود، شیء به‌جای آن به آن منتقل می‌شود.

پارامترها

  • شغل

    رشته

    دستگیره کار اسکن فعال قبلاً از تماس با startScan برگردانده شده است.

بازگشتی‌ها

  • یک Promise برمی‌گرداند که با نتیجه حل می‌شود.

closeScanner()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.closeScanner(
  scannerHandle: string,
): Promise<CloseScannerResponse>

اسکنر را با دسته ارسال‌شده می‌بندد و یک Promise برمی‌گرداند که با شیء CloseScannerResponse حل می‌شود. اگر از فراخوانی برگشتی استفاده شود، شیء به‌جای آن به آن منتقل می‌شود. حتی اگر پاسخ موفقیت‌آمیز نباشد، دسته ارائه‌شده نامعتبر می‌شود و نباید برای عملیات بعدی استفاده شود.

پارامترها

  • scannerHandle

    رشته

    دستگیره اسکنر بازی را که قبلاً از تماس با openScanner برگردانده شده است مشخص می‌کند.

بازگشتی‌ها

  • یک Promise برمی‌گرداند که با نتیجه حل می‌شود.

getOptionGroups()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.getOptionGroups(
  scannerHandle: string,
): Promise<GetOptionGroupsResponse>

نام‌های گروه و گزینه‌های عضو را از اسکنری که قبلاً توسط openScanner باز شده است دریافت می‌کند. این روش یک Promise برمی‌گرداند که با یک شیء GetOptionGroupsResponse حل می‌شود. اگر فراخوانی متقابل به این تابع منتقل شود، داده‌های برگردانده‌شده به‌جای آن منتقل می‌شود.

پارامترها

  • scannerHandle

    رشته

    دستگیره اسکنر بازشده از تماس با openScanner برگردانده شد.

بازگشتی‌ها

getScannerList()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.getScannerList(
  filter: DeviceFilter,
): Promise<GetScannerListResponse>

فهرست اسکنرهای دردسترس را دریافت می‌کند و یک Promise برمی‌گرداند که با شیء GetScannerListResponse حل می‌شود. اگر فراخوانی متقابل به این تابع منتقل شود، داده‌های برگردانده‌شده به‌جای آن منتقل می‌شود.

پارامترها

  • فیلتر کردن

    DeviceFilter

    DeviceFilter که نشان می‌دهد کدام نوع اسکنرها باید برگردانده شوند.

بازگشتی‌ها

  • یک Promise برمی‌گرداند که با نتیجه و فهرست اسکنرها حل می‌شود.

openScanner()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.openScanner(
  scannerId: string,
): Promise<OpenScannerResponse>

اسکنری را برای دسترسی انحصاری باز می‌کند و Promise را که با شیء OpenScannerResponse حل می‌شود برمی‌گرداند. اگر فراخوانی متقابل به این تابع منتقل شود، داده‌های برگردانده‌شده به‌جای آن منتقل می‌شود.

پارامترها

  • scannerId

    رشته

    شناسه اسکنری که باید باز شود. این مقدار یکی از مقادیر برگردانده‌شده از تماس قبلی به getScannerList است.

بازگشتی‌ها

  • یک Promise برمی‌گرداند که با نتیجه حل می‌شود.

readScanData()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.readScanData(
  job: string,
): Promise<ReadScanDataResponse>

بخش بعدی داده‌های تصویر دردسترس را از یک دسته کار فعال می‌خواند و یک Promise برمی‌گرداند که با یک شیء ReadScanDataResponse حل می‌شود. اگر از فراخوانی برگشتی استفاده شود، شیء به‌جای آن به آن منتقل می‌شود.

**توجه:**معتبر است که نتیجه پاسخ SUCCESS با عضو data با طول صفر باشد. این یعنی اسکنر هنوز درحال کار است اما هنوز داده‌های بیشتری آماده نکرده است. تماس‌گیرنده باید کمی صبر کند و دوباره امتحان کند.

وقتی کار اسکن تکمیل شود، پاسخ دارای مقدار نتیجه EOF خواهد بود. این پاسخ ممکن است حاوی عضو نهایی غیرصفر data باشد.

پارامترها

  • شغل

    رشته

    دستگیره کار فعال قبلاً از startScan برگردانده شده است.

بازگشتی‌ها

  • یک Promise برمی‌گرداند که با نتیجه حل می‌شود.

scan()

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

سند را اسکن می‌کند و یک Promise برمی‌گرداند که با شیء ScanResults حل می‌شود. اگر فراخوانی متقابل به این تابع منتقل شود، داده‌های برگردانده‌شده به‌جای آن منتقل می‌شود.

پارامترها

  • گزینه‌ها

    ScanOptions

    شیء حاوی پارامترهای اسکن.

بازگشتی‌ها

  • Promise<ScanResults>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

    یک Promise برمی‌گرداند که با نتایج اسکن حل می‌شود.

setOptions()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
): Promise<SetOptionsResponse>

گزینه‌ها را در اسکنر مشخص‌شده تنظیم می‌کند و یک Promise برمی‌گرداند که با یک شیء SetOptionsResponse حاوی نتیجه تلاش برای تنظیم هر مقدار به ترتیب شیء OptionSetting ارسال‌شده حل می‌شود. اگر از فراخوانی برگشتی استفاده شود، شیء به‌جای آن به آن منتقل می‌شود.

پارامترها

  • scannerHandle

    رشته

    دستگیره اسکنر برای تنظیم گزینه‌ها. این باید مقداری باشد که قبلاً از تماس با openScanner برگردانده شده است.

  • گزینه‌ها

    OptionSetting[]

    فهرستی از OptionSetting شیء که باید در اسکنر اعمال شود.

بازگشتی‌ها

  • یک Promise برمی‌گرداند که با نتیجه حل می‌شود.

startScan()

Chrome نسخه ۱۲۵ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
): Promise<StartScanResponse>

اسکن را در اسکنر مشخص‌شده شروع می‌کند و یک Promise برمی‌گرداند که با StartScanResponse حل می‌شود. اگر از فراخوانی برگشتی استفاده شود، شیء به‌جای آن به آن منتقل می‌شود. اگر فراخوانی موفقیت‌آمیز باشد، پاسخ شامل یک دسته کار است که می‌تواند در فراخوانی‌های بعدی برای خواندن داده‌های اسکن یا لغو اسکن استفاده شود.

پارامترها

  • scannerHandle

    رشته

    دستگیره اسکنر باز. این باید مقداری باشد که قبلاً از تماس با openScanner برگردانده شده است.

  • گزینه‌ها

    StartScanOptions

    شیء StartScanOptions که گزینه‌های مورداستفاده برای اسکن را نشان می‌دهد. ویژگی StartScanOptions.format باید با یکی از ورودی‌های برگردانده‌شده در ScannerInfo اسکنر مطابقت داشته باشد.

بازگشتی‌ها

  • یک Promise برمی‌گرداند که با نتیجه حل می‌شود.