chrome.documentScan

مهم: این API فقط روی ChromeOS کار می‌کند.

توضیحات

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

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

مجوزها

documentScan

در دسترس بودن

فقط کروم او اس ۴۴+

در دسترس بودن برای اعضای API که بعداً اضافه شده‌اند، همراه با آن اعضا نشان داده شده است.

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

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

اسکن ساده

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

اسکن پیچیده

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

نکته: فراخوانی توابع openScanner() ، getScannerList() یا startScan() بیش از یک بار، عملیاتی را که توسط فراخوانی‌های قبلی این متدها آغاز شده‌اند، لغو می‌کند. برای جزئیات بیشتر به توضیحات این متدها مراجعه کنید.

کشف

1. فراخوانی getScannerList() . اسکنرهای موجود در یک Promise که با GetScannerListResponse پاسخ داده می‌شود، بازگردانده می‌شوند.

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

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

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

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

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

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

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

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

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

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

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

اسکن

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

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

   نکته: اگر result SUCCESS باشد، اما data خالی باشند، قبل از فراخوانی مجدد readScanData() کمی تأخیر ایجاد کنید.

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

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

اشیاء پاسخ

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

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

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

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

ساختار به طور کلی به این شکل است:

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

برای مثال، اسکنری را تصور کنید که گزینه‌هایی با نام‌های "source" و "resolution" را برمی‌گرداند. ساختار شیء options برگردانده شده چیزی شبیه به مثال زیر خواهد بود. برای سادگی، فقط پاسخ‌های جزئی ScannerOption نشان داده می‌شوند.

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

ساخت رابط کاربری

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

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

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

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

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

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

مثال‌ها

بازیابی یک صفحه به صورت یک لکه

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

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

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

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

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

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

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

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

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

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

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() ارسال شده بود، ارائه می‌دهد.

• نتیجه

  نتیجه عملیات

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

CloseScannerResponse

کروم ۱۲۵+

خواص

• نتیجه

  نتیجه عملیات

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

• دسته اسکنر

  رشته

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

Configurability

کروم ۱۲۵+

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

شمارشی

"غیرقابل_تنظیم"
گزینه فقط خواندنی است.

«قابل پیکربندی نرم‌افزار»
این گزینه را می‌توان به صورت نرم‌افزاری تنظیم کرد.

"سخت‌افزار_قابل_پیکربندی"
این گزینه را می‌توان با تغییر وضعیت یا فشار دادن دکمه‌ای روی اسکنر توسط کاربر تنظیم کرد.

ConnectionType

کروم ۱۲۵+

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

شمارشی

«نامشخص»

"یو اس بی"

«شبکه»

ConstraintType

کروم ۱۲۵+

نوع داده‌ی محدودیتی که توسط OptionConstraint نمایش داده می‌شود.

شمارشی

"دامنه_عددی"
محدودیت روی طیفی از مقادیر OptionType.INT . ویژگی‌های min ، max و quant از OptionConstraint long خواهند بود و ویژگی list آن تنظیم نشده است.

"محدوده ثابت"
محدودیت روی طیفی از مقادیر OptionType.FIXED . ویژگی‌های min ، max و quant از OptionConstraint برابر double خواهد بود و ویژگی list آن تنظیم نشده است.

"لیست_INT"
محدودیت روی یک لیست خاص از مقادیر OptionType.INT . ویژگی OptionConstraint.list شامل مقادیر long خواهد بود و سایر ویژگی‌ها تنظیم نشده‌اند.

"لیست_ثابت"
محدودیت روی یک لیست خاص از مقادیر OptionType.FIXED . ویژگی OptionConstraint.list شامل مقادیر double خواهد بود و سایر ویژگی‌ها تنظیم نشده‌اند.

"لیست_رشته‌ای"
محدودیت روی یک لیست خاص از مقادیر OptionType.STRING . ویژگی OptionConstraint.list شامل مقادیر DOMString خواهد بود و سایر ویژگی‌ها تنظیم نشده‌اند.

DeviceFilter

کروم ۱۲۵+

خواص

• محلی

  بولی اختیاری

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

• امن

  بولی اختیاری

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

GetOptionGroupsResponse

کروم ۱۲۵+

خواص

• گروه‌ها

  گروه گزینه [] اختیاری

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

• نتیجه

  نتیجه عملیات

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

• دسته اسکنر

  رشته

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

GetScannerListResponse

کروم ۱۲۵+

خواص

• نتیجه

  نتیجه عملیات

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

• اسکنرها

  اطلاعات اسکنر []

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

OpenScannerResponse

کروم ۱۲۵+

خواص

• گزینه‌ها

  شیء اختیاری

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

• نتیجه

  نتیجه عملیات

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

• دسته اسکنر

  رشته اختیاری

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

• اسکنر آی دی

  رشته

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

OperationResult

کروم ۱۲۵+

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

شمارشی

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

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

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

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

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

«نامعتبر»
یا داده یا آرگومان ارسالی به متد معتبر نیست.

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

"ای او اف"
داده بیشتری در دسترس نیست.

"ADF_متوقف شد"
تغذیه کننده سند گیر کرده است.

"ADF_EMPTY"
تغذیه کننده سند خالی است.

«پوشش_باز»
پوشش تخت باز است.

"خطای ورودی/خروجی"
هنگام برقراری ارتباط با دستگاه، خطایی رخ داد.

«دسترسی_ممنوع»
دستگاه نیاز به احراز هویت دارد.

"بدون_حافظه"
حافظه کافی در کروم‌بوک برای تکمیل عملیات موجود نیست.

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

«گمشده»
دستگاه قطع شده است.

"خطای داخلی"
خطایی در جایی غیر از برنامه‌ی فراخوانی‌کننده رخ داده است.

OptionConstraint

کروم ۱۲۵+

خواص

• فهرست

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

• حداکثر

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

• دقیقه

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

• کمیت

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

• نوع

  نوع محدودیت

OptionGroup

کروم ۱۲۵+

خواص

• اعضا

  رشته[]

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

• عنوان

  رشته

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

OptionSetting

کروم ۱۲۵+

خواص

• نام

  رشته

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

• نوع

  نوع گزینه

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

• ارزش

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

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

OptionType

کروم ۱۲۵+

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

شمارشی

«ناشناس»
نوع داده‌ی این گزینه ناشناخته است. ویژگی value غیرفعال خواهد شد.

"بول"
ویژگی value یکی از مقادیر true false خواهد بود.

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

«ثابت»
یک عدد دو رقمی در محدوده ‎-32768-32767.9999‎ با وضوح ‎1/65535‎. ویژگی value ‎double‎ یا ‎double[]‎ خواهد بود، بسته به اینکه آیا گزینه بیش از یک مقدار می‌گیرد یا خیر. مقادیر دو رقمی که نمی‌توانند دقیقاً نمایش داده شوند، به محدوده و دقت موجود گرد می‌شوند.

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

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

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

OptionUnit

کروم ۱۲۵+

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

شمارشی

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

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

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

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

"دی پی آی"
مقدار آن بر حسب نقطه در هر اینچ اندازه‌گیری می‌شود، برای مثال، وضوح تصویر.

«درصد»
مقدار آن درصد است، مثلاً روشنایی.

"میکرو ثانیه"
مقدار در میکروثانیه اندازه‌گیری می‌شود، برای مثال، زمان نوردهی.

ReadScanDataResponse

کروم ۱۲۵+

خواص

• داده‌ها

  ArrayBuffer اختیاری

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

• تکمیل تخمینی

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

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

• شغل

  رشته

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

• نتیجه

  نتیجه عملیات

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

ScannerInfo

کروم ۱۲۵+

خواص

• نوع اتصال

  نوع اتصال

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

• یوآی‌دی دستگاه

  رشته

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

• قالب‌های تصویر

  رشته[]

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

• تولیدکننده

  رشته

  شرکت سازنده اسکنر

• مدل

  رشته

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

• نام

  رشته

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

• پروتکلنوع

  رشته

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

• اسکنر آی دی

  رشته

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

• امن

  بولی

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

ScannerOption

کروم ۱۲۵+

خواص

• قابلیت پیکربندی

  قابلیت پیکربندی

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

• محدودیت

  محدودیت گزینه اختیاری

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

• توضیحات

  رشته

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

• فعال است

  بولی

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

• پیشرفته

  بولی

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

• قابل تنظیم خودکار

  بولی

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

• قابل تشخیص است

  بولی

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

• شبیه سازی شده است

  بولی

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

• نام

  رشته

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

• عنوان

  رشته

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

• نوع

  نوع گزینه

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

• واحد

  واحد آپشن

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

• ارزش

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

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

ScanOptions

خواص

• تصاویر حداکثر

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

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

• انواع mime

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

  انواع MIME که توسط فراخواننده پذیرفته می‌شوند.

ScanResults

خواص

• آدرس‌های داده

  رشته[]

  آرایه‌ای از آدرس‌های اینترنتی تصاویر داده‌ای به شکلی که می‌تواند به عنوان مقدار "src" به یک تگ تصویر منتقل شود.

• نوع مایم

  رشته

  نوع MIME مربوط به dataUrls .

SetOptionResult

کروم ۱۲۵+

خواص

• نام

  رشته

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

• نتیجه

  نتیجه عملیات

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

SetOptionsResponse

کروم ۱۲۵+

خواص

• گزینه‌ها

  شیء اختیاری

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

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

• نتایج

  تنظیم گزینه نتیجه []

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

• دسته اسکنر

  رشته

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

StartScanOptions

کروم ۱۲۵+

خواص

• قالب

  رشته

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

• حداکثر اندازه خواندن

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

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

StartScanResponse

کروم ۱۲۵+

خواص

• شغل

  رشته اختیاری

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

• نتیجه

  نتیجه عملیات

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

• دسته اسکنر

  رشته

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

روش‌ها

cancelScan()

کروم ۱۲۵+

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

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

پارامترها

• شغل

  رشته

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

بازگشت‌ها

• قول< لغو اسکن پاسخ >

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

closeScanner()

کروم ۱۲۵+

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

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

پارامترها

• دسته اسکنر

  رشته

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

بازگشت‌ها

• قول< بستن اسکنرپاسخ >

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

getOptionGroups()

کروم ۱۲۵+

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

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

پارامترها

• دسته اسکنر

  رشته

  شناسه‌ی یک اسکنر باز از فراخوانی تابع openScanner برگشت داده شده است.

بازگشت‌ها

• قول <GetOptionGroupsResponse>

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

getScannerList()

کروم ۱۲۵+

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

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

پارامترها

• فیلتر

  فیلتر دستگاه

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

بازگشت‌ها

• قول < GetScannerListResponse >

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

openScanner()

کروم ۱۲۵+

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

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

پارامترها

• اسکنر آی دی

  رشته

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

بازگشت‌ها

• قول< OpenScannerResponse >

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

readScanData()

کروم ۱۲۵+

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

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

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

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

پارامترها

• شغل

  رشته

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

بازگشت‌ها

• قول <ReadScanDataResponse>

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

scan()

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

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

پارامترها

• گزینه‌ها

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

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

بازگشت‌ها

• قول< نتایج اسکن >

  کروم ۹۶+

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

setOptions()

کروم ۱۲۵+

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

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

پارامترها

• دسته اسکنر

  رشته

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

• گزینه‌ها

  تنظیمات گزینه []

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

بازگشت‌ها

• قول <SetOptionsResponse>

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

startScan()

کروم ۱۲۵+

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

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

پارامترها

• دسته اسکنر

  رشته

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

• گزینه‌ها

  گزینه‌های اسکن شروع

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

بازگشت‌ها

• قول < شروع اسکن پاسخ >

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