chrome.documentScan

תיאור

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

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

הרשאות

documentScan

זמינות

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

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

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

סריקה פשוטה

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

סריקה מורכבת

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

גילוי

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

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

  2. בוחרים סורק מהמערך שהוחזר ושומרים את הערך שלו נכס scannerId.

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

הגדרת הסורק

  1. קוראים אל openScanner() ומעבירים את מזהה הסורק השמור. היא מחזירה הבטחה שמסתיימת ב-OpenScannerResponse. אובייקט התשובה מכיל:

    • נכס scannerHandle, שצריך לשמור אותו.

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

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

  3. בניית מערך של אובייקטים ב-OptionSetting באמצעות פרוגרמטיות או ערכים שסופקו על ידי המשתמשים. מידע נוסף מופיע במאמר 'הגדרת אפשרויות הסורק' מידע.

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

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

סריקה

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

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

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

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

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

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

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

אפשרויות לסורקים

אפשרויות הסורק משתנות משמעותית בהתאם למכשיר. לכן לא ניתן לשקף את האפשרויות לסורק ישירות ב-DocumentScan API. תחבורה באזור את זה, OpenScannerResponse (מאוחזר באמצעות openScanner()) וגם SetOptionsResponse (אובייקט התשובה עבור setOptions()) כוללים נכס options שהוא אובייקט שמכיל אפשרויות ספציפיות לסורק. כל אפשרות היא מיפוי של מפתח/ערך כאשר המפתח הוא אפשרות ספציפית למכשיר והערך הוא מופע של ScannerOption

המבנה בדרך כלל נראה כך:

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

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

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

פיתוח ממשק משתמש

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

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

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

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

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

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

דוגמאות

אחזור דף כ-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" });
}

סריקה של עמוד אחד בגודל אות

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

מאפיינים

  • משימה

    מחרוזת

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

  • תוצאה

    OperationResult

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

CloseScannerResponse

Chrome 125+

מאפיינים

  • תוצאה

    OperationResult

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

  • scannerHandle

    מחרוזת

    אותה נקודת אחיזה של הסורק שהועברה אל closeScanner.

Configurability

Chrome 125+

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

Enum

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

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

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

ConnectionType

Chrome 125+

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

Enum

'לא מתאים'

"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

    ערך בוליאני אופציונלי

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

  • מאובטח

    ערך בוליאני אופציונלי

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

GetOptionGroupsResponse

Chrome 125+

מאפיינים

  • קבוצות

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

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

  • תוצאה

    OperationResult

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

  • scannerHandle

    מחרוזת

    אותה נקודת אחיזה של הסורק שהועברה אל getOptionGroups.

GetScannerListResponse

Chrome 125+

מאפיינים

  • תוצאה

    OperationResult

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

  • סורקים

    ScannerInfo[]

    רשימה כנראה ריקה של סורקים שתואמים ל-DeviceFilter שסופק.

OpenScannerResponse

Chrome 125+

מאפיינים

  • אפשרויות

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

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

  • תוצאה

    OperationResult

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

  • scannerHandle

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

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

  • scannerId

    מחרוזת

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

OperationResult

Chrome 125+

טיפוסים בני מנייה (enum) שמציין את התוצאה של כל פעולה.

Enum

"UNKNOWN"
אירעה תקלה לא ידועה או כללית.

"הצלחה"
הפעולה הצליחה.

"לא נתמך"
הפעולה לא נתמכת.

"CancelLED"
הפעולה בוטלה.

"DEVICE_BUSY"
המכשיר עמוס.

"INVALID"
הנתונים או הארגומנט שהועברו ל-method אינם חוקיים.

"WRONG_TYPE"
הערך שסופק מכיל נתונים שגויים עבור האפשרות הבסיסית.

"EOF"
אין נתונים נוספים.

"ADF_JAMMED"
פיד המסמכים תקוע.

"ADF_EMPTY"
פיד המסמכים ריק.

"COVER_OPEN"
הכיסוי של המיטה שטוחה פתוח.

"IO_ERROR"
אירעה שגיאה במהלך התקשורת עם המכשיר.

"ACCESS_DENIED"
המכשיר מחייב אימות.

"NO_MEMORY"
אין מספיק זיכרון ב-Chromebook כדי להשלים את הפעולה.

'לא ניתן להשיג'
אי אפשר לגשת למכשיר.

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

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

OptionConstraint

Chrome 125+

מאפיינים

  • list

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

  • מקסימלי

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

  • דקה

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

  • קוונטי

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

OptionGroup

Chrome 125+

מאפיינים

  • חברים

    String[]

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

  • title

    מחרוזת

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

OptionSetting

Chrome 125+

מאפיינים

  • שם

    מחרוזת

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

  • סוג

    OptionType

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

  • ערך

    string | מספר | boolean | מספר[] אופציונלי

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

OptionType

Chrome 125+

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

Enum

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

"BOOL"
המאפיין value יהיה אחד מהערכים trueFALSE.

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

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

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

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

"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.

  • משימה

    מחרוזת

    כאן מזינים את כינוי המשימה שהועברה אל 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 אופציונלי

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

  • תיאור

    מחרוזת

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

  • isActive

    בוליאני

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

  • isAdvanced

    בוליאני

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

  • isAutoSettable

    בוליאני

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

  • isDetectable

    בוליאני

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

  • isEmulated

    בוליאני

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

  • שם

    מחרוזת

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

  • title

    מחרוזת

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

  • סוג

    OptionType

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

  • יחידה

    OptionUnit

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

  • ערך

    string | מספר | boolean | מספר[] אופציונלי

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

ScanOptions

מאפיינים

  • maxImages

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

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

  • mimeTypes

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

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

ScanResults

מאפיינים

  • dataUrls

    String[]

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

  • mimeType

    מחרוזת

    סוג MIME של dataUrls.

SetOptionResult

Chrome 125+

מאפיינים

  • שם

    מחרוזת

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

  • תוצאה

    OperationResult

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

SetOptionsResponse

Chrome 125+

מאפיינים

  • אפשרויות

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

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

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

  • תוצאות

    SetOptionResult[]

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

  • scannerHandle

    מחרוזת

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

StartScanOptions

Chrome 125+

מאפיינים

  • פורמט

    מחרוזת

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

  • maxReadSize

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

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

StartScanResponse

Chrome 125+

מאפיינים

  • משימה

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

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

  • תוצאה

    OperationResult

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

  • scannerHandle

    מחרוזת

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

שיטות

cancelScan()

הבטחה Chrome 125 ואילך 
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

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

פרמטרים

  • משימה

    מחרוזת

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

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

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

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

    (response: CancelScanResponse) => void

החזרות

  • Promise&lt;CancelScanResponse&gt;

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

closeScanner()

הבטחה Chrome 125 ואילך 
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

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

פרמטרים

  • scannerHandle

    מחרוזת

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

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

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

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

    (response: CloseScannerResponse) => void

החזרות

  • Promise&lt;CloseScannerResponse&gt;

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

getOptionGroups()

הבטחה Chrome 125 ואילך 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

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

פרמטרים

  • scannerHandle

    מחרוזת

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

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

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

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

    (response: GetOptionGroupsResponse) => void

החזרות

  • Promise&lt;GetOptionGroupsResponse&gt;

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

getScannerList()

הבטחה Chrome 125 ואילך 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

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

פרמטרים

החזרות

  • Promise&lt;GetScannerListResponse&gt;

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

openScanner()

הבטחה Chrome 125 ואילך 
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

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

פרמטרים

  • scannerId

    מחרוזת

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

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

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

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

    (response: OpenScannerResponse) => void

החזרות

  • Promise&lt;OpenScannerResponse&gt;

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

readScanData()

הבטחה Chrome 125 ואילך 
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

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

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

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

פרמטרים

  • משימה

    מחרוזת

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

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

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

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

    (response: ReadScanDataResponse) => void

החזרות

  • Promise&lt;ReadScanDataResponse&gt;

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

scan()

הבטחה 
chrome.documentScan.scan(
  options: ScanOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    ScanOptions

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

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

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

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

    (result: ScanResults) => void

החזרות

  • Promise&lt;ScanResults&gt;

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

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

setOptions()

הבטחה Chrome 125 ואילך 
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
)

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

פרמטרים

  • scannerHandle

    מחרוזת

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

  • אפשרויות

    OptionSetting[]

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

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

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

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

    (response: SetOptionsResponse) => void

החזרות

  • Promise&lt;SetOptionsResponse&gt;

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

startScan()

הבטחה Chrome 125 ואילך 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

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

פרמטרים

  • scannerHandle

    מחרוזת

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

  • אפשרויות

    StartScanOptions

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

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

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

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

    (response: StartScanResponse) => void

החזרות

  • Promise&lt;StartScanResponse&gt;

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