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> בממשק המשתמש.

סריקה מורכבת

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

גילוי

  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 של הגדרת הסורק.

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

סריקה

  1. יוצרים אובייקט StartScanOptions ומעבירים אותו אל startScan(). הפונקציה מחזירה Promise שמתבצע בו פתרון עם StartScanResponse. המאפיין job הוא מזהה שמשמש לקריאת נתוני הסריקה או לביטול הסריקה.

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

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

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

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

החזרות

  • יש תמיכה ב-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

החזרות

  • יש תמיכה ב-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

החזרות

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

getScannerList()

Promise Chrome מגרסה 125 ואילך 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

הפונקציה מקבלת את רשימת הסורקים הזמינים ומחזירה 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

החזרות

  • יש תמיכה ב-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

החזרות

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

scan()

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

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

פרמטרים

  • אפשרויות

    ScanOptions

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

  • קריאה חוזרת (callback)

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

    הפרמטר callback נראה כך: 

    (result: ScanResults) => void

החזרות

  • 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

החזרות

  • יש תמיכה ב-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

החזרות

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