browser.documentScan

חשוב: ה-API הזה פועל רק ב-ChromeOS.

תיאור

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

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

הרשאות

documentScan

זמינות

Chrome 44 ואילך browser.* ‎ מגרסה 148 של Chrome ChromeOS בלבד

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

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

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

סריקה פשוטה

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

סריקה מורכבת

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

הערה: קריאה ל-openScanner(), ל-getScannerList() או ל-startScan() יותר מפעם אחת תבטל את הפעולות שהתחילו בקריאות קודמות לשיטות האלה. לפרטים נוספים, קראו את התיאורים של השיטות האלה.

Discovery

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. מעבירים את נקודת האחיזה של המשימה אל readScanData(). היא מחזירה Promise שמתקבל עם אובייקט ReadScanDataResponse. אם הנתונים נקראו בהצלחה, המאפיין result שווה ל-SUCCESS והמאפיין data מכיל ArrayBuffer עם חלק מהסריקה. שימו לב שהשדה estimatedCompletion מכיל אחוז משוער של כל הנתונים שהועברו עד עכשיו.

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

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 }
}

לדוגמה, נניח שיש סורק שמחזיר אפשרויות בשם "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 browser.documentScan.startScan(
      handle, {format: "image/jpeg"});
  if (response.result != browser.documentScan.OperationResult.SUCCESS) {
    return null;
  }
  const job = response.job;

  let imgParts = [];
  response = await browser.documentScan.readScanData(job);
  while (response.result == browser.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 browser.documentScan.readScanData(job);
  }
  if (response.result != browser.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 browser.documentScan.getScannerList({ secure: true });
    let scanner = await browser.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: browser.documentScan.OptionType.STRING,
                value: { value: source }
            });
            break;
        }
    }
    options.push({
        name: "tl-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 215.9  // 8.5" in mm
    });
    options.push({
        name: "tl-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 279.4  // 11" in mm
    });
    response = await browser.documentScan.setOptions(handle, options);

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

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

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

async function showConfig() {
  let response = await browser.documentScan.getScannerList({ secure: true });
  let scanner = await browser.documentScan.openScanner(
      response.scanners[0].scannerId);
  let groups = await browser.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 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• משימה

  מחרוזת

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

• תוצאה

  OperationResult

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

CloseScannerResponse

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• תוצאה

  OperationResult

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

• scannerHandle

  מחרוזת

  אותו מזהה סורק שהועבר אל closeScanner.

Configurability

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

טיפוסים בני מנייה (enum)

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

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

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

ConnectionType

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

טיפוסים בני מנייה (enum)

"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

סוג הנתונים של האילוץ שמיוצג על ידי 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 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• local

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

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

• מאובטח

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

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

GetOptionGroupsResponse

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• קבוצות

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

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

• תוצאה

  OperationResult

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

• scannerHandle

  מחרוזת

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

GetScannerListResponse

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• תוצאה

  OperationResult

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

• סורקים

  ScannerInfo[]

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

OpenScannerResponse

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• אפשרויות

  object optional

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

• תוצאה

  OperationResult

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

• scannerHandle

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

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

• scannerId

  מחרוזת

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

OperationResult

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

טיפוסים בני מנייה (enum)

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

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

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

‫"CANCELLED"
הפעולה בוטלה.

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

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

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

"EOF"
אין יותר נתונים זמינים.

"ADF_JAMMED"
מזין המסמכים תקוע.

"ADF_EMPTY"
מזין המסמכים ריק.

‫"COVER_OPEN"
המכסה של הסורק השטוח פתוח.

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

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

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

"UNREACHABLE"
לא ניתן לגשת למכשיר.

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

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

OptionConstraint

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• list

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

• מקסימלי

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

• דק'

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

• quant

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

• סוג

  ConstraintType

OptionGroup

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• חברים

  string[]‎

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

• title

  מחרוזת

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

OptionSetting

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• שם

  מחרוזת

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

• סוג

  OptionType

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

• ערך

  string | number | boolean | number[] optional

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

OptionType

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

טיפוסים בני מנייה (enum)

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

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

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

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

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

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

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

OptionUnit

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

טיפוסים בני מנייה (enum)

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

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

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

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

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

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

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

ReadScanDataResponse

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• נתונים

  ‫ArrayBuffer אופציונלי

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

• estimatedCompletion

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

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

• משימה

  מחרוזת

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

• תוצאה

  OperationResult

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

ScannerInfo

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• connectionType

  ConnectionType

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

• deviceUuid

  מחרוזת

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

• imageFormats

  string[]‎

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

• יצרן

  מחרוזת

  יצרן הסורק.

• מודל

  מחרוזת

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

• שם

  מחרוזת

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

• protocolType

  מחרוזת

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

• scannerId

  מחרוזת

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

• מאובטח

  בוליאני

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

ScannerOption

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

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

  יכולת הגדרה

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

• מגבלה

  ‫OptionConstraint אופציונלי

  מגדיר את 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 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• שם

  מחרוזת

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

• תוצאה

  OperationResult

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

SetOptionsResponse

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• אפשרויות

  object optional

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

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

• תוצאות

  SetOptionResult[]

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

• scannerHandle

  מחרוזת

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

StartScanOptions

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• פורמט

  מחרוזת

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

• maxReadSize

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

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

StartScanResponse

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

מאפיינים

• משימה

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

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

• תוצאה

  OperationResult

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

• scannerHandle

  מחרוזת

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

Methods

cancelScan()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

פרמטרים

• משימה

  מחרוזת

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

החזרות

• ‫Promise<CancelScanResponse>

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

closeScanner()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

פרמטרים

• scannerHandle

  מחרוזת

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

החזרות

• Promise<CloseScannerResponse>

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

getOptionGroups()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

פרמטרים

• scannerHandle

  מחרוזת

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

החזרות

• Promise<GetOptionGroupsResponse>

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

getScannerList()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

פרמטרים

• סינון

  DeviceFilter

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

החזרות

• Promise<GetScannerListResponse>

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

openScanner()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

פרמטרים

• scannerId

  מחרוזת

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

החזרות

• Promise<OpenScannerResponse>

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

readScanData()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

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

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

פרמטרים

• משימה

  מחרוזת

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

החזרות

• Promise<ReadScanDataResponse>

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

scan()

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

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

פרמטרים

• אפשרויות

  ScanOptions

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

החזרות

• Promise<ScanResults>

  ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

setOptions()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

פרמטרים

• scannerHandle

  מחרוזת

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

• אפשרויות

  OptionSetting[]

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

החזרות

• Promise<SetOptionsResponse>

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

startScan()

‫Chrome 125 ואילך ‫‎browser.* ‎ החל מ-Chrome 148

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

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

פרמטרים

• scannerHandle

  מחרוזת

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

• אפשרויות

  StartScanOptions

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

החזרות

• Promise<StartScanResponse>

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