דף זה תורגם על ידי Cloud Translation API.

chrome.documentScan

תיאור

שימוש ב-API ‏chrome.documentScan כדי למצוא ולשלוף תמונות מסורקי מסמכים מחוברים.

Document Scan API נועד לאפשר לאפליקציות ולתוספים להציג את התוכן של מסמכים מודפסים בסורק מסמכים מחובר.

הרשאות

documentScan

זמינות

Chrome מגרסה 44 ואילך ב-ChromeOS בלבד

הזמינות לחברי API שנוספו מאוחר יותר תוצג עם החברים האלה.

מושגים ושימוש

ה-API הזה תומך בשתי שיטות לסריקה של מסמכים. אם תרחיש לדוגמה יכול לפעול עם כל סורק ולא נדרש לשלוט בהגדרות, צריך להשתמש בשיטה scan(). בתרחישי שימוש מורכבים יותר נדרש שילוב של שיטות, שנתמכות רק ב-Chrome בגרסה 124 ואילך.

סריקה פשוטה

בתרחישי שימוש פשוטים, כלומר כאלה שאפשר להשתמש בהם עם כל סורק ולא דורשים שליטה בהגדרות, צריך להפעיל את הפונקציה scan(). ה-method הזה מקבל אובייקט ScanOptions ומחזיר Promise שמתבצע בו פתרון עם אובייקט ScanResults. היכולות של האפשרות הזו מוגבלות למספר הסריקות ולסוגי ה-MIME שייקבלו על ידי מבצע הקריאה החוזרת. הסריקה מוחזרת ככתובות URL להצגה בתג <img> בממשק המשתמש.

סריקה מורכבת

סריקות מורכבות מתבצעות בשלושה שלבים, כפי שמתואר בקטע הזה. בסקירה הכללית הזו לא מתוארים כל ארגומנטים של שיטות או כל המאפיינים שמוחזרים בתגובה. המאמר הזה מיועד רק להדרכה כללית בנושא כתיבת קוד לסורק.

גילוי

קוראים לפונקציה getScannerList(). הסורקים הזמינים מוחזרים ב-Promise שמתקבל עם GetScannerListResponse.
- אובייקט התשובה מכיל מערך של אובייקטים מסוג ScannerInfo.
- המערך עשוי לכלול מספר רשומות של סורק אחד אם הסורק תומך במספר פרוטוקולים או שיטות חיבור.
בוחרים סורק מהמערך שהוחזר ושומרים את הערך של המאפיין scannerId שלו.

אפשר להשתמש במאפיינים של אובייקטים ספציפיים מסוג ScannerInfo כדי להבדיל בין כמה אובייקטים של אותו סורק. לאובייקטים מאותו סורק יהיה אותו ערך למאפיין deviceUuid. ScannerInfo מכיל גם את המאפיין imageFormats שמכיל מערך של סוגי תמונות נתמכים.

הגדרת הסורק

קוראים ל-openScanner() ומעבירים את מזהה הסורק שנשמר. הפונקציה מחזירה Promise שמתבצעת בו פתרון עם OpenScannerResponse. אובייקט התשובה מכיל:
- מאפיין scannerHandle, שצריך לשמור.
- נכס אפשרויות שמכיל מאפיינים ספציפיים לסורק, שתצטרכו להגדיר. מידע נוסף זמין במאמר 'אפשרויות אחזור מהסורק'.
(אופציונלי) אם אתם צריכים שהמשתמש יספק ערכים לאפשרויות של הסורק, תוכלו ליצור ממשק משתמש. תצטרכו את אפשרויות הסורק שסיפק השלב הקודם, ותצטרכו לאחזר את קבוצות האפשרויות שסופקו על ידי הסורק. מידע נוסף זמין במאמר יצירת ממשק משתמש.
יצירה של מערך של אובייקטים מסוג OptionSetting באמצעות ערכים פרוגרמטיים או ערכים שהמשתמשים סיפקו. מידע נוסף זמין במאמר 'הגדרת אפשרויות הסריקה'.
מעבירים את המערך של אובייקטי OptionSetting אל setOptions() כדי להגדיר אפשרויות לסורק. הפונקציה מחזירה Promise שמתבצעת בו פתרון עם SetOptionsResponse. האובייקט הזה מכיל גרסה מעודכנת של אפשרויות הסורק שאוחזרו בשלב 1 של הגדרת הסורק.

מכיוון ששינוי אפשרות אחת יכול לשנות את האילוצים על אפשרות אחרת, יכול להיות שתצטרכו לחזור על השלבים האלה כמה פעמים.

סריקה

יוצרים אובייקט StartScanOptions ומעבירים אותו אל startScan(). הפונקציה מחזירה Promise שמתבצע בו פתרון עם StartScanResponse. המאפיין job הוא מזהה שמשמש לקריאת נתוני הסריקה או לביטול הסריקה.
מעבירים את ה-handle של המשימה אל readScanData(). הפונקציה מחזירה Promise שמתבצעת בו פתרון עם אובייקט ReadScanDataResponse. אם הנתונים נקראו בהצלחה, המאפיין result שלהם יהיה שווה ל-SUCCESS והמאפיין data שלהם יכיל ArrayBuffer עם חלק מהסריקה. שימו לב ש-estimatedCompletion מכיל אחוז משוער מתוך סך כל הנתונים שנשלחו עד עכשיו.

הערה: אם הערך של result הוא SUCCESS אבל הערך של data ריק, צריך להמתין קצת לפני שמפעילים שוב את readScanData().
חוזרים על השלב הקודם עד שהנכס result שווה ל-EOF או לשגיאה.

כשמגיעים לסוף הסריקה, קוראים ל-closeScanner() עם הכינוי של הסורק שנשמר בשלב 3. הפונקציה מחזירה Promise שמתבצעת בו פתרון עם CloseScannerResponse. קריאה לפונקציה cancelScan() בכל שלב אחרי יצירת המשימה תגרום לסיום הסריקה.

אובייקטים של תגובה

כל השיטות מחזירות Promise שמתבצעת בו פתרון עם אובייקט תגובה מסוג כלשהו. רובם מכילים מאפיין result שהערך שלו הוא חבר בקבוצה OperationResult. חלק מהמאפיינים של אובייקטי התשובה לא יכילו ערכים, אלא אם לערך של result יהיה ערך ספציפי. היחסים האלה מתוארים במסמך העזרה של כל אובייקט תגובה.

לדוגמה, ל-OpenScannerResponse.scannerHandle יהיה ערך רק כאשר OpenScannerResponse.result שווה ל-SUCCESS.

אפשרויות סריקה

האפשרויות של סורק משתנות באופן משמעותי בהתאם למכשיר. לכן אי אפשר לשקף את אפשרויות הסורק ישירות ב-documentScan 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,
...
  },
...
}

בניית ממשק משתמש

השימוש ב-API הזה לא נדרש, אבל יכול להיות שתרצו לאפשר למשתמש לבחור את הערך של אפשרות מסוימת. לשם כך נדרש ממשק משתמש. משתמשים בOpenScannerResponse (שנפתח באמצעות openScanner()) כדי לאחזר את האפשרויות של הסורק המחובר, כפי שמתואר בקטע הקודם.

חלק מהסורקים מקובצים את האפשרויות בדרכים ספציפיות למכשיר. הן לא משפיעות על התנהגות האפשרויות, אבל מכיוון שיכול להיות שהקבוצות האלה מוזכרות במסמכי התיעוד של המוצר של הסורק, צריך להציג את הקבוצות האלה למשתמש. אפשר לאחזר את הקבוצות האלה באמצעות הפקודה getOptionGroups(). הפונקציה מחזירה Promise שמתמלא באובייקט GetOptionGroupsResponse. המאפיין groups מכיל מערך של קבוצות שספציפיות לסורק. אפשר להשתמש במידע בקבוצות האלה כדי לארגן את האפשרויות שמוצגות בOpenScannerResponse.

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

כפי שצוין בקטע 'הגדרת סורק', שינוי אפשרות אחת יכול לשנות את האילוצים על אפשרות אחרת. לכן, setOptionsResponse (אובייקט התגובה של setOptions()) מכיל נכס options נוסף. משתמשים באפשרות הזו כדי לעדכן את ממשק המשתמש. חוזרים על הפעולה לפי הצורך עד שמגדירים את כל האפשרויות.

הגדרת אפשרויות הסורק

כדי להגדיר את אפשרויות הסריקה, מעבירים מערך של אובייקטים מסוג OptionSetting ל-setOptions(). לדוגמה, ראו את הקטע סריקה של דף אחד בגודל Letter שבהמשך.

דוגמאות

אחזור דף כ-blob

בדוגמה הזו מוצגת דרך אחת לאחזור דף מהסורק כ-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" });
}

סריקת דף אחד בגודל Letter

בדוגמה הזו מוסבר איך לבחור סורק, להגדיר את האפשרויות שלו ולפתוח אותו. לאחר מכן הוא מאחזר את התוכן של דף אחד וסוגר את הסורק. בתהליך הזה נעשה שימוש ב-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

מאפיינים

משימה

string

ה-handle של המשימה שעבר ל-cancelScan().
תוצאה

OperationResult

תוצאת הביטול של הסריקה בקצה העורפי. אם התוצאה היא OperationResult.SUCCESS או OperationResult.CANCELLED, הסריקה בוטלה והסורק מוכן להתחיל סריקה חדשה. אם התוצאה היא OperationResult.DEVICE_BUSY , הסריקה עדיין מעבדת את הביטול המבוקש. מבצע הקריאה החוזרת צריך להמתין זמן קצר ולנסות שוב את הבקשה. ערכים אחרים של תוצאות מציינים שגיאה קבועה שאין לנסות שוב.

CloseScannerResponse

גרסה 125 ואילך של Chrome

מאפיינים

תוצאה

OperationResult

התוצאה של סגירת הסורק. גם אם הערך הזה לא SUCCESS, הכינוי לא יהיה חוקי ולא ניתן יהיה להשתמש בו לפעולות נוספות.
scannerHandle

string

אותו מזהה סורק שהוענק ל-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

התוצאה של אחזור קבוצות האפשרויות. אם הערך של this הוא SUCCESS, המאפיין groups יאוכלס.
scannerHandle

string

אותו מזהה סורק שהוענק ל-getOptionGroups.

GetScannerListResponse

גרסה 125 ואילך של Chrome

מאפיינים

תוצאה

OperationResult

תוצאת המיפוי. חשוב לזכור שיכול להיות שתקבלו תוצאות חלקיות גם אם הן מצביעות על שגיאה.
סורקים

ScannerInfo[]

רשימה של סורקים (עשויה להיות ריקה) שתואמים ל-DeviceFilter שצוין.

OpenScannerResponse

גרסה 125 ואילך של Chrome

מאפיינים

אפשרויות

אובייקט אופציונלי

אם הערך של result הוא SUCCESS, המערכת מספקת מיפוי של מפתח/ערך שבו המפתח הוא אפשרות ספציפית למכשיר והערך הוא מופע של ScannerOption.
תוצאה

OperationResult

התוצאה של פתיחת הסורק. אם הערך של הפרמטר הזה הוא SUCCESS, המאפיינים scannerHandle ו-options יאוכלסו.
scannerHandle

מחרוזת אופציונלי

אם result הוא SUCCESS, זהו הכינוי לסורק שאפשר להשתמש בו לביצוע פעולות נוספות.
scannerId

string

מזהה הסורק הועבר אל openScanner().

OperationResult

גרסה 125 ואילך של Chrome

enum שמציין את התוצאה של כל פעולה.

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

מאפיינים

list

string[] | number[] אופציונלי
מקסימלי

מספר אופציונלי
דקה

מספר אופציונלי
quant

מספר אופציונלי
סוג

ConstraintType

OptionGroup

גרסה 125 ואילך של Chrome

מאפיינים

חברים

string[]

מערך של שמות אפשרויות בסדר שסופק על ידי הנהג.
title

string

שם שאפשר להדפיס, למשל 'אפשרויות גיאומטריה'.

OptionSetting

גרסה 125 ואילך של Chrome

מאפיינים

שם

string

השם של האפשרות שרוצים להגדיר.
סוג

OptionType

מציין את סוג הנתונים של האפשרות. סוג הנתונים המבוקש חייב להתאים לסוג הנתונים האמיתי של האפשרות הבסיסית.
ערך

string | number | boolean | number[] אופציונלי

הערך שרוצים להגדיר. משאירים את הערך לא מוגדר כדי לבקש הגדרה אוטומטית לאפשרויות שבהן autoSettable מופעל. סוג הנתונים שצוין עבור value חייב להתאים ל-type.

OptionType

גרסה 125 ואילך של Chrome

סוג הנתונים של אפשרות.

Enum

"UNKNOWN"
סוג הנתונים של האפשרות לא ידוע. המאפיין value לא יוגדר.

"BOOL"
הנכס value יהיה אחד מהערכים truefalse.

"INT"
מספר שלם של 32 ביט עם סימן. המאפיין value יהיה מסוג long או long[], בהתאם למספר הערכים שהאפשרות יכולה לקבל.

'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.
משימה

string

השירות הזה מספק את ה-handle של המשימה שהועברה אל readScanData().
תוצאה

OperationResult

התוצאה של קריאת הנתונים. אם הערך שלו הוא SUCCESS, אז data מכיל את החלק הבא (שיכול להיות באורך אפס) של נתוני התמונה שזמין לקריאה. אם הערך שלו הוא EOF, ה-data מכיל את החלק האחרון של נתוני התמונה.

ScannerInfo

גרסה 125 ואילך של Chrome

מאפיינים

connectionType

ConnectionType

מציין איך הסורק מחובר למחשב.
deviceUuid

string

להתאמה לרשאות ScannerInfo אחרות שמפנות לאותו מכשיר פיזי.
imageFormats

string[]

מערך של סוגי MIME שאפשר לבקש עבור סריקות שהוחזרו.
יצרן

string

יצרן הסורק.
מודל

string

מודל הסורק, אם הוא זמין, או תיאור כללי.
שם

string

שם קריא לאנשים של הסורק שיוצג בממשק המשתמש.
protocolType

string

תיאור קריא לאנשים של הפרוטוקול או הנהג ששימשו לגישה לסורק, כמו Mopria,‏ WSD או epsonds. האפשרות הזו שימושית בעיקר כדי לאפשר למשתמש לבחור בין פרוטוקולים אם המכשיר תומך במספר פרוטוקולים.
scannerId

string

המזהה של סורק ספציפי.
מאובטח

boolean

אם הערך הוא true, לא ניתן ליירט את התעבורה של חיבור הסורק על ידי מאזין פסיבי, כמו TLS או USB.

ScannerOption

גרסה 125 ואילך של Chrome

מאפיינים

יכולת הגדרה

התאמה אישית

מציין אם אפשר לשנות את האפשרות ואיך עושים זאת.
אילוץ

OptionConstraint אופציונלי

הגדרת OptionConstraint באפשרות הסורק הנוכחית.
תיאור

string

תיאור ארוך יותר של האפשרות.
isActive

boolean

מציין שהאפשרות פעילה וניתן להגדיר אותה או לאחזר אותה. אם הערך הוא false, המאפיין value לא יוגדר.
isAdvanced

boolean

מציין שלא צריך להציג את האפשרות הזו בממשק המשתמש כברירת מחדל.
isAutoSettable

boolean

אפשר להגדיר אותו באופן אוטומטי על ידי מנהל ההתקן של הסורק.
isDetectable

boolean

האפשרות הזו יכולה להיות מזוהה באמצעות תוכנה.
isEmulated

boolean

אם הערך הוא True, מנהל ההתקן של הסורק ימול את האות.
שם

string

שם האפשרות, שמורכב מאותיות ASCII קטנות, מספרים ומקפים. אסור להשתמש בסימני הטעמה.
title

string

כותרת של שורה אחת להדפסה.
סוג

OptionType

סוג הנתונים שמכיל המאפיין value, שנדרש להגדרת האפשרות הזו.
יחידה

OptionUnit

יחידת המידה של האפשרות הזו.
ערך

string | number | boolean | number[] אופציונלי

הערך הנוכחי של האפשרות, אם רלוונטי. חשוב לזכור שסוג הנתונים של המאפיין הזה חייב להתאים לסוג הנתונים שצוין ב-type.

ScanOptions

מאפיינים

maxImages

מספר אופציונלי

מספר התמונות הסריקה המותרות. ערך ברירת המחדל הוא 1.
mimeTypes

string[] אופציונלי

סוגי ה-MIME שהמבצע קורא אותם מקבל.

ScanResults

מאפיינים

dataUrls

string[]

מערך של כתובות URL של תמונות נתונים בפורמט שאפשר להעביר כערך 'src' לתג תמונה.
mimeType

string

סוג ה-MIME של ה-dataUrls.

SetOptionResult

גרסה 125 ואילך של Chrome

מאפיינים

שם

string

השם של האפשרות שהוגדרה.
תוצאה

OperationResult

מציין את התוצאה של הגדרת האפשרות.

SetOptionsResponse

גרסה 125 ואילך של Chrome

מאפיינים

אפשרויות

אובייקט אופציונלי

מיפוי מעודכן של מפתח/ערך משמות האפשרויות לערכים של ScannerOption שמכילים את ההגדרה החדשה אחרי הניסיון להגדיר את כל האפשרויות שסופקו. למאפיין הזה יש את אותו מבנה כמו לנכס options ב-OpenScannerResponse.

הנכס הזה יוגדר גם אם חלק מהאפשרויות לא הוגדרו בהצלחה, אבל לא יוגדר אם אחזור ההגדרות המעודכנות נכשל (לדוגמה, אם הסורק התנתק באמצע הסריקה).
תוצאות

SetOptionResult[]

מערך של תוצאות, אחת לכל OptionSetting שהועברו.
scannerHandle

string

ה-handle של הסורק שמוענק ל-setOptions().

StartScanOptions

גרסה 125 ואילך של Chrome

מאפיינים

פורמט

string

קובע את סוג ה-MIME שבו יוחזרו הנתונים הסרוקים.
maxReadSize

מספר אופציונלי

אם מציינים ערך שאינו אפס, הוא מגביל את מספר הבייטים המקסימלי שיסוננו ויוחזרו בתגובה אחת של readScanData לערך הזה. הערך הקטן ביותר המותר הוא 32768 (32KB). אם לא מציינים את המאפיין הזה, גודל הקטע המוחזר עשוי להיות גדול כמו התמונה הסריקה כולה.

StartScanResponse

גרסה 125 ואילך של Chrome

מאפיינים

משימה

מחרוזת אופציונלי

אם הערך של result הוא SUCCESS, הוא מספק מזהה (handle) שאפשר להשתמש בו כדי לקרוא את נתוני הסריקה או לבטל את המשימה.
תוצאה

OperationResult

התוצאה של התחלת סריקה. אם הערך של this הוא SUCCESS, המאפיין job יאוכלס.
scannerHandle

string

מספק את אותו כינוי סורק שהוענק ל-startScan().

Methods

cancelScan()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

ביטול סריקה שהתחילה והחזרת Promise שמתבצעת בו פתרון עם אובייקט CancelScanResponse. אם משתמשים בקריאה חוזרת (callback), האובייקט מועבר אליה במקום זאת.

פרמטרים

משימה

string

ה-handle של משימה פעילה של סריקה שהוחזר בעבר מקריאה ל-startScan.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: CancelScanResponse) => void
```
- תשובה
  
  CancelScanResponse

החזרות

Promise<CancelScanResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

closeScanner()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

סגירת הסורק עם ה-handle שהוענק ומתן Promise שמתבצעת בו פתרון עם אובייקט CloseScannerResponse. אם משתמשים בקריאה חוזרת (callback), האובייקט מועבר אליה במקום זאת. גם אם התגובה לא מציינת הצלחה, הכינוי שסופק הופך ללא תקף ואסור להשתמש בו לביצוע פעולות נוספות.

פרמטרים

scannerHandle

string

ה-handle של סורק פתוח שהוחזר בעבר מבקשה ל-openScanner.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: CloseScannerResponse) => void
```
- תשובה
  
  CloseScannerResponse

החזרות

Promise<CloseScannerResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getOptionGroups()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

הפונקציה מקבלת את שמות הקבוצות ואת אפשרויות החברים מסורן שנפתח קודם לכן על ידי openScanner. השיטה הזו מחזירה Promise שמתבצעת בו פתרון עם אובייקט GetOptionGroupsResponse. אם מעבירים פונקציית קריאה חוזרת לפונקציה הזו, הנתונים המוחזרים מועברים אליה במקום זאת.

פרמטרים

scannerHandle

string

הכינוי של סורק פתוח שהוחזר משיחה ל-openScanner.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: GetOptionGroupsResponse) => void
```
- תשובה
  
  GetOptionGroupsResponse

החזרות

Promise<GetOptionGroupsResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getScannerList()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

הפונקציה מקבלת את רשימת הסורקים הזמינים ומחזירה Promise שמתבצעת בו פתרון עם אובייקט GetScannerListResponse. אם מעבירים פונקציית קריאה חוזרת לפונקציה הזו, הנתונים המוחזרים מועברים אליה במקום זאת.

פרמטרים

סינון

DeviceFilter

DeviceFilter שמציין אילו סוגי סורקים צריך להחזיר.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: GetScannerListResponse) => void
```
- תשובה
  
  GetScannerListResponse

החזרות

Promise<GetScannerListResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

openScanner()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

פתיחת סורק לגישה בלעדית והחזרת Promise שמתבצעת בו פתרון עם אובייקט OpenScannerResponse. אם מעבירים פונקציית קריאה חוזרת לפונקציה הזו, הנתונים המוחזרים מועברים אליה במקום זאת.

פרמטרים

scannerId

string

המזהה של סורק שרוצים לפתוח. הערך הזה מוחזר מקריאה קודמת ל-getScannerList.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: OpenScannerResponse) => void
```
- תשובה
  
  OpenScannerResponse

החזרות

Promise<OpenScannerResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

readScanData()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

הפונקציה קוראת את החלק הבא של נתוני התמונה הזמינים מתוך ה-handle של המשימה הפעילה, ומחזירה Promise שמתבצעת בו פתרון עם אובייקט ReadScanDataResponse. אם משתמשים בקריאה חוזרת (callback), האובייקט מועבר אליה במקום זאת.

**הערה:**התוצאה של התגובה יכולה להיות SUCCESS עם חבר data באורך אפס. המשמעות היא שהסורק עדיין פועל, אבל עדיין אין נתונים נוספים מוכנים. מבצע השיחה צריך להמתין זמן קצר ולנסות שוב.

כשמשימה הסריקה תסתיים, ערך התוצאה בתגובה יהיה EOF. התשובה הזו עשויה לכלול את המאפיין data שהוא לא אפס.

פרמטרים

משימה

string

הכינוי של המשימה הפעילה שהוחזר בעבר מ-startScan.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: ReadScanDataResponse) => void
```
- תשובה
  
  ReadScanDataResponse

החזרות

Promise<ReadScanDataResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

scan()

Promise

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

מבצעת סריקה של מסמך ומחזירה Promise שמתבצעת בו פתרון עם אובייקט ScanResults. אם מעבירים פונקציית קריאה חוזרת לפונקציה הזו, הנתונים המוחזרים מועברים אליה במקום זאת.

פרמטרים

אפשרויות

ScanOptions

אובייקט שמכיל פרמטרים של סריקה.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(result: ScanResults) => void
```
- תוצאה
  
  ScanResults

החזרות

Promise<ScanResults>

גרסה 96 ואילך של Chrome

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

setOptions()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
)

הפונקציה מגדירה אפשרויות בסורק שצוין ומחזירה Promise שמתבצעת בו פתרון עם אובייקט SetOptionsResponse שמכיל את התוצאה של הניסיון להגדיר כל ערך בסדר של האובייקט OptionSetting שהוענק. אם משתמשים בקריאה חוזרת (callback), האובייקט מועבר אליה במקום זאת.

פרמטרים

scannerHandle

string

הידית של הסורק שבה מגדירים את האפשרויות. זה צריך להיות ערך שהוחזר בעבר מקריאה ל-openScanner.
אפשרויות

OptionSetting[]

רשימה של אובייקטים מסוג OptionSetting שרוצים להחיל על הסורק.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: SetOptionsResponse) => void
```
- תשובה
  
  SetOptionsResponse

החזרות

Promise<SetOptionsResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

startScan()

Promise Chrome מגרסה 125 ואילך

chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

הפונקציה מתחילה סריקה בסורק שצוין ומחזירה Promise שמתבצעת בו פתרון עם StartScanResponse. אם משתמשים בקריאה חוזרת (callback), האובייקט מועבר אליה במקום זאת. אם הקריאה הצליחה, התגובה תכלול את ה-handle של המשימה, שאפשר להשתמש בו בקריאות הבאות כדי לקרוא נתוני סריקה או לבטל סריקה.

פרמטרים

scannerHandle

string

הידית של סורק פתוח. זה צריך להיות ערך שהוחזר בעבר מקריאה ל-openScanner.
אפשרויות

StartScanOptions

אובייקט StartScanOptions שמציין את האפשרויות שבהן נעשה שימוש בסריקה. המאפיין StartScanOptions.format חייב להתאים לאחת מהרשומות שמוחזרות ב-ScannerInfo של הסורק.
קריאה חוזרת (callback)

פונקציה אופציונלי

הפרמטר callback נראה כך:
```
(response: StartScanResponse) => void
```
- תשובה
  
  StartScanResponse

החזרות

Promise<StartScanResponse>

יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.