chrome.documentScan

תיאור

אפשר להשתמש ב-chrome.documentScan API כדי לגלות ולאחזר תמונות מסורקי מסמכים שמצורפים.

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

הרשאות

documentScan

זמינות

‫Chrome 44 ואילך ChromeOS בלבד
הזמינות לחברי API שנוספו מאוחר יותר מוצגת עם החברים האלה.

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

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

סריקה פשוטה

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

סריקה מורכבת

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

Discovery

  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 מכיל אחוז משוער מסך הנתונים שהועברו עד עכשיו.

  3. חוזרים על השלב הקודם עד שהמאפיין result שווה ל-EOF או לשגיאה.

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

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

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

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

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

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

‫Chrome 125 ואילך

מאפיינים

  • משימה

    מחרוזת

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

  • תוצאה

    OperationResult

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

CloseScannerResponse

‫Chrome 125 ואילך

מאפיינים

  • תוצאה

    OperationResult

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

  • scannerHandle

    מחרוזת

    אותו ה-handle של הסורק שהועבר אל closeScanner.

Configurability

‫Chrome 125 ואילך

איך אפשר לשנות אפשרות.

Enum

‫NOT_CONFIGURABLE
האפשרות היא לקריאה בלבד.

‫SOFTWARE_CONFIGURABLE
אפשר להגדיר את האפשרות בתוכנה.

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

ConnectionType

‫Chrome 125 ואילך

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

Enum

‫"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

‫Chrome 125 ואילך

סוג הנתונים של האילוץ שמיוצג על ידי 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

‫Chrome 125 ואילך

מאפיינים

  • local

    boolean אופציונלי

    יוחזרו רק סורקים שמחוברים ישירות למחשב.

  • מאובטח

    boolean אופציונלי

    רק סורקים שמשתמשים בהעברה מאובטחת, כמו USB או TLS.

GetOptionGroupsResponse

‫Chrome 125 ואילך

מאפיינים

  • קבוצות

    ‫OptionGroup[] אופציונלי

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

  • תוצאה

    OperationResult

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

  • scannerHandle

    מחרוזת

    אותו ה-handle של הסורק שהועבר אל getOptionGroups.

GetScannerListResponse

‫Chrome 125 ואילך

מאפיינים

  • תוצאה

    OperationResult

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

  • סורקים

    ScannerInfo[]

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

OpenScannerResponse

‫Chrome 125 ואילך

מאפיינים

  • options

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

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

  • תוצאה

    OperationResult

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

  • scannerHandle

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

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

  • scannerId

    מחרוזת

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

OperationResult

‫Chrome 125 ואילך

סוג 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
לא ניתן לגשת למכשיר.

‫MISSING
המכשיר מנותק.

‫INTERNAL_ERROR
אירעה שגיאה במקום אחר ולא באפליקציה שמבצעת את השיחה.

OptionConstraint

‫Chrome 125 ואילך

מאפיינים

  • list

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

  • מקסימלי

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

  • דק'

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

  • quant

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

OptionGroup

‫Chrome 125 ואילך

מאפיינים

  • חברים

    string[]

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

  • title

    מחרוזת

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

OptionSetting

‫Chrome 125 ואילך

מאפיינים

  • שם

    מחרוזת

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

  • סוג

    OptionType

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

  • ערך

    string | number | boolean | number[] optional

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

OptionType

‫Chrome 125 ואילך

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

Enum

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

‫BOOL
המאפיין value יהיה אחד מהערכים truefalse.

‫INT
מספר שלם חתום בן 32 ביט. המאפיין value יהיה long או long[], בהתאם לשאלה אם האפשרות מקבלת יותר מערך אחד.

‫FIXED
מספר כפול בטווח ‎-32768-32767.9999 עם רזולוציה של ‎1/65535. המאפיין value יהיה double או double[] ‎, בהתאם לשאלה אם האפשרות מקבלת יותר מערך אחד. ערכים מסוג double שלא ניתן לייצג בדיוק יעוגלו לטווח ולדיוק הזמינים.

‫"STRING"
רצף של בייטים כלשהם, למעט NUL (‎'\0'). המאפיין value יהיה DOMString.

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

‫GROUP
אפשרות קיבוץ. אין ערך. הוא נכלל לצורך תאימות, אבל בדרך כלל לא יוחזר בערכים של ScannerOption. משתמשים ב-getOptionGroups() כדי לאחזר את רשימת הקבוצות עם אפשרויות החברים שלהן.

OptionUnit

‫Chrome 125 ואילך

מציין את סוג הנתונים של ScannerOption.unit.

Enum

‫UNITLESS
הערך הוא מספר ללא יחידה. לדוגמה, יכול להיות שזה ערך סף.

‫'PIXEL'
הערך הוא מספר פיקסלים, לדוגמה, מידות סריקה.

‫"BIT"
הערך הוא מספר הביטים, למשל עומק הצבע.

‫MM
הערך נמדד במילימטרים, למשל מידות סריקה.

‫'DPI'
הערך נמדד בנקודות לאינץ', לדוגמה, רזולוציה.

‫PERCENT
הערך הוא אחוז, למשל בהירות.

‫MICROSECOND
הערך נמדד במיקרו-שניות, למשל זמן החשיפה.

ReadScanDataResponse

‫Chrome 125 ואילך

מאפיינים

  • נתונים

    ‫ArrayBuffer אופציונלי

    אם result הוא SUCCESS, מכיל את המקטע הבא של נתוני תמונות שנסרקו. אם result הוא EOF, מכיל את נתוני התמונה הסרוקים האחרונים.

  • estimatedCompletion

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

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

  • משימה

    מחרוזת

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

  • תוצאה

    OperationResult

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

ScannerInfo

‫Chrome 125 ואילך

מאפיינים

  • connectionType

    ConnectionType

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

  • deviceUuid

    מחרוזת

    לצורך התאמה לערכים אחרים של ScannerInfo שמפנים לאותו מכשיר פיזי.

  • imageFormats

    string[]

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

  • יצרן

    מחרוזת

    יצרן הסורק.

  • מודל

    מחרוזת

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

  • שם

    מחרוזת

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

  • protocolType

    מחרוזת

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

  • scannerId

    מחרוזת

    המזהה של סורק ספציפי.

  • מאובטח

    בוליאני

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

ScannerOption

‫Chrome 125 ואילך

מאפיינים

  • יכולת הגדרה

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

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

  • מגבלה

    ‫OptionConstraint optional

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

  • תיאור

    מחרוזת

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

  • isActive

    בוליאני

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

  • isAdvanced

    בוליאני

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

  • isAutoSettable

    בוליאני

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

  • isDetectable

    בוליאני

    מציין שאפשר לזהות את האפשרות הזו מתוכנה.

  • isEmulated

    בוליאני

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

  • שם

    מחרוזת

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

  • title

    מחרוזת

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

  • סוג

    OptionType

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

  • יחידה

    OptionUnit

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

  • ערך

    string | number | boolean | number[] optional

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

ScanOptions

מאפיינים

  • maxImages

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

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

  • mimeTypes

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

    סוגי ה-MIME שהמתקשר מקבל.

ScanResults

מאפיינים

  • dataUrls

    string[]

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

  • mimeType

    מחרוזת

    סוג ה-MIME של dataUrls.

SetOptionResult

‫Chrome 125 ואילך

מאפיינים

  • שם

    מחרוזת

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

  • תוצאה

    OperationResult

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

SetOptionsResponse

‫Chrome 125 ואילך

מאפיינים

  • options

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

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

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

  • תוצאות

    SetOptionResult[]

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

  • scannerHandle

    מחרוזת

    השירות הזה מספק את נקודת האחיזה של הסורק שמועברת אל setOptions().

StartScanOptions

‫Chrome 125 ואילך

מאפיינים

  • פורמט

    מחרוזת

    מציין את סוג ה-MIME שבו יוחזרו הנתונים שנסרקו.

  • maxReadSize

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

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

StartScanResponse

‫Chrome 125 ואילך

מאפיינים

  • משימה

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

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

  • תוצאה

    OperationResult

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

  • scannerHandle

    מחרוזת

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

Methods

cancelScan()

‫Chrome 125 ואילך 
chrome.documentScan.cancelScan(
  job: string,
): Promise<CancelScanResponse>

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

פרמטרים

  • משימה

    מחרוזת

    הכינוי של משימת סריקה פעילה שהוחזר בעבר מקריאה אל startScan.

החזרות

  • מחזירה הבטחה (Promise) שמושלמת עם התוצאה.

closeScanner()

‫Chrome 125 ואילך 
chrome.documentScan.closeScanner(
  scannerHandle: string,
): Promise<CloseScannerResponse>

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

פרמטרים

  • scannerHandle

    מחרוזת

    מציין את ה-handle של סורק פתוח שהוחזר קודם מקריאה אל openScanner.

החזרות

getOptionGroups()

‫Chrome 125 ואילך 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
): Promise<GetOptionGroupsResponse>

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

פרמטרים

  • scannerHandle

    מחרוזת

    המאגר של סורק פתוח שהוחזר מקריאה אל openScanner.

החזרות

getScannerList()

‫Chrome 125 ואילך 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
): Promise<GetScannerListResponse>

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

פרמטרים

  • סינון

    DeviceFilter

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

החזרות

  • מחזירה הבטחה (Promise) שנפתרת עם התוצאה ורשימת הסורקים.

openScanner()

‫Chrome 125 ואילך 
chrome.documentScan.openScanner(
  scannerId: string,
): Promise<OpenScannerResponse>

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

פרמטרים

  • scannerId

    מחרוזת

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

החזרות

  • מחזירה הבטחה (Promise) שנפתרת עם התוצאה.

readScanData()

‫Chrome 125 ואילך 
chrome.documentScan.readScanData(
  job: string,
): Promise<ReadScanDataResponse>

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

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

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

פרמטרים

  • משימה

    מחרוזת

    הכינוי של המשימה הפעילה הוחזר בעבר מ-startScan.

החזרות

scan()

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

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

פרמטרים

  • options

    ScanOptions

    אובייקט שמכיל פרמטרים של סריקה.

החזרות

  • Promise<ScanResults>

    ‫Chrome 96 ואילך

    מחזירה הבטחה (Promise) שנפתרת עם תוצאות הסריקה.

setOptions()

‫Chrome 125 ואילך 
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
): Promise<SetOptionsResponse>

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

פרמטרים

  • scannerHandle

    מחרוזת

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

  • options

    OptionSetting[]

    רשימה של OptionSetting אובייקטים להחלה על הסורק.

החזרות

  • מחזירה הבטחה (Promise) שנפתרת עם התוצאה.

startScan()

‫Chrome 125 ואילך 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
): Promise<StartScanResponse>

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

פרמטרים

  • scannerHandle

    מחרוזת

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

  • אובייקט StartScanOptions שמציין את האפשרויות שבהן יש להשתמש לסריקה. הערך של המאפיין StartScanOptions.format צריך להיות זהה לאחד מהערכים שמוחזרים ב-ScannerInfo של הסורק.

החזרות

  • מחזירה הבטחה (Promise) שמושלמת עם התוצאה.