browser.documentScan

重要事項： 這個 API 僅適用於 ChromeOS。

說明

使用 chrome.documentScan API 探索及擷取連接的文件掃描器中的圖片。

Document Scan API 可讓應用程式和擴充功能，在連接的文件掃描器上查看紙本文件的內容。

權限

documentScan

可用性

Chrome 44 以上版本 Chrome 148 以上版本為 browser.* 僅限 ChromeOS

之後新增的 API 成員，其有空與否狀態會與這些成員一起顯示。

概念和用途

這個 API 支援兩種掃描文件的方式。如果您的用途適用於任何掃描器，且不需要控制設定，請使用 scan() 方法。較複雜的用途需要結合多種方法，而這些方法僅適用於 Chrome 124 以上版本。

簡易掃描

如果是簡單的用途，也就是可與任何掃描器搭配使用，且不需要控制設定，請呼叫 scan()。這個方法會採用 ScanOptions 物件，並傳回以 ScanResults 物件解析的 Promise。這項功能的限制包括掃描次數，以及呼叫端接受的 MIME 類型。掃描結果會以網址形式傳回，並顯示在使用者介面的 <img> 標記中。

複雜掃描

複雜掃描作業分為三個階段，如本節所述。這份大綱並未說明每個方法引數或回應中傳回的每個屬性。僅供您做為編寫掃描器程式碼的一般指南。

注意： 多次呼叫 openScanner()、getScannerList() 或 startScan()，會取消先前呼叫這些方法所啟動的操作。如需具體資訊，請參閱這些方法的說明。

探索

1. 呼叫 getScannerList()。可用的掃描器會以 Promise 傳回，並解析為 GetScannerListResponse。

   • 回應物件包含 ScannerInfo 物件陣列。
   • 如果單一掃描器支援多種通訊協定或連線方法，陣列可能會包含該掃描器的多個項目。

2. 從傳回的陣列中選取掃描器，並儲存其 scannerId 屬性的值。

   使用個別 ScannerInfo 物件的屬性，區分同一掃描器的多個物件。來自同一個掃描器的物件，其 deviceUuid 屬性值會相同。ScannerInfo 也包含 imageFormats 屬性，其中含有支援的圖片類型陣列。

掃描器設定

1. 呼叫 openScanner()，傳入儲存的掃描器 ID。這個方法會傳回 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 或發生錯誤。

掃描結束時，請使用步驟 3 中儲存的掃描器控制代碼呼叫 closeScanner()。這個方法會傳回 Promise，並以 CloseScannerResponse 解析。在工作建立後，隨時呼叫 cancelScan() 都會結束掃描。

回應物件

所有方法都會傳回 Promise，並以某種回應物件解析。其中大部分都包含 result 屬性，其值為 OperationResult 的成員。除非 result 的值為特定值，否則回應物件的某些屬性不會包含值。每個回應物件的參考資料中，都會說明這些關係。

舉例來說，只有在 OpenScannerResponse.result 等於 SUCCESS 時，OpenScannerResponse.scannerHandle 才會有值。

掃描器選項

掃描器選項因裝置而異。因此，無法直接在 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，並示範如何使用 OperationResult 的值來使用 startScan() 和 readScanData()。

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

顯示設定

如其他部分所述，如要向使用者顯示掃描器的設定選項，除了呼叫 openScanner() 傳回的掃描器選項外，還需要呼叫 getOptionGroups()。這樣一來，系統就能向使用者顯示製造商定義群組中的選項。這個範例說明如何執行這項操作。

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 以上版本 Chrome 148 起為 browser.*

屬性

• 工作

  字串

  提供與傳遞至 cancelScan() 相同的工作控制代碼。

• 結果

  OperationResult

  後端的取消掃描結果。如果結果是 OperationResult.SUCCESS 或 OperationResult.CANCELLED，表示掃描作業已取消，掃描器已準備好開始新的掃描作業。如果結果為 OperationResult.DEVICE_BUSY，表示掃描器仍在處理取消要求，呼叫端應稍候片刻，然後再次嘗試要求。其他結果值表示永久錯誤，不應重試。

CloseScannerResponse

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 結果

  OperationResult

  關閉掃描器的結果。即使這個值不是 SUCCESS，控制代碼也會無效，不應再用於任何作業。

• scannerHandle

  字串

  與傳遞至 closeScanner 的掃描器控制代碼相同。

Configurability

Chrome 125 以上版本 Chrome 148 起為 browser.*

如何變更選項。

列舉

"NOT_CONFIGURABLE"
選項為唯讀。

「SOFTWARE_CONFIGURABLE」
可在軟體中設定選項。

"HARDWARE_CONFIGURABLE"
使用者可以切換或按下掃描器上的按鈕來設定選項。

ConnectionType

Chrome 125 以上版本 Chrome 148 起為 browser.*

表示掃描器與電腦的連線方式。

列舉

"UNSPECIFIED"

「USB」

"NETWORK"

ConstraintType

Chrome 125 以上版本 Chrome 148 起為 browser.*

由 OptionConstraint 表示的限制資料類型。

列舉

"INT_RANGE"
OptionType.INT 值範圍的限制。OptionConstraint 的 min、max 和 quant 屬性會是 long，而其 list 屬性則會取消設定。

"FIXED_RANGE"
OptionType.FIXED 值範圍的限制。OptionConstraint 的 min、max 和 quant 屬性會是 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 以上版本 Chrome 148 起為 browser.*

屬性

• local

  布林值 選填

  只傳回直接連接到電腦的掃描器。

• 安全

  布林值 選填

  只傳回使用安全傳輸方式 (例如 USB 或 TLS) 的掃描器。

GetOptionGroupsResponse

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 群組

  OptionGroup[] 選填

  如果 result 為 SUCCESS，則會按照掃描器驅動程式提供的順序，列出選項群組。

• 結果

  OperationResult

  取得選項群組的結果。如果這個值為 SUCCESS，系統會填入 groups 屬性。

• scannerHandle

  字串

  與傳遞至 getOptionGroups 的掃描器控制代碼相同。

GetScannerListResponse

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 結果

  OperationResult

  列舉結果。請注意，即使這表示發生錯誤，系統仍可能傳回部分結果。

• 掃描器

  ScannerInfo[]

  與提供的 DeviceFilter 相符的掃描器清單 (可能為空白)。

OpenScannerResponse

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 選項

  物件 選填

  如果 result 為 SUCCESS，則提供鍵/值對應，其中鍵為裝置專屬選項，值為 ScannerOption 的例項。

• 結果

  OperationResult

  開啟掃描器的結果。如果這個值為 SUCCESS，系統會填入 scannerHandle 和 options 屬性。

• scannerHandle

  字串 選填

  如果 result 為 SUCCESS，則為掃描器的控制代碼，可用於進一步操作。

• scannerId

  字串

  傳遞至 openScanner() 的掃描器 ID。

OperationResult

Chrome 125 以上版本 Chrome 148 起為 browser.*

表示每項作業結果的列舉。

列舉

「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 以上版本 Chrome 148 起為 browser.*

屬性

• list

  string[] | number[] 選填

• max

  數字 選填

• 分鐘

  數字 選填

• quant

  數字 選填

• 類型

  ConstraintType

OptionGroup

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 成員

  string[]

  選項名稱陣列，依驅動程式提供的順序排列。

• title

  字串

  提供可列印的標題，例如「幾何圖形選項」。

OptionSetting

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 名稱

  字串

  表示要設定的選項名稱。

• 類型

  OptionType

  指出選項的資料類型。要求的資料類型必須與基礎選項的實際資料類型相符。

• 值

  string | number | boolean | number[] 選填

  表示要設定的值。如果未設定，系統會自動設定已啟用 autoSettable 的選項。為 value 提供的資料類型必須與 type 相符。

OptionType

Chrome 125 以上版本 Chrome 148 起為 browser.*

選項的資料類型。

列舉

"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

Chrome 125 以上版本 Chrome 148 起為 browser.*

表示 ScannerOption.unit 的資料類型。

列舉

"UNITLESS"
值為無單位數字。例如，可以是門檻。

"PIXEL"
值為像素數量，例如掃描尺寸。

「BIT」
值為位元數，例如色彩深度。

「MM」
以公釐為單位的值，例如掃描尺寸。

「DPI」
這個值是以每英寸像素數為單位，例如解析度。

「PERCENT」
值為百分比，例如亮度。

「MICROSECOND」
以微秒為單位的值，例如曝光時間。

ReadScanDataResponse

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 資料

  ArrayBuffer 選用

  如果 result 為 SUCCESS，則包含掃描圖片資料的下一個區塊。如果 result 為 EOF，則包含掃描圖片資料的最後一個區塊。

• estimatedCompletion

  數字 選填

  如果 result 為 SUCCESS，則表示目前已傳送的掃描資料總量預估值，範圍為 0 到 100。

• 工作

  字串

  提供傳遞至 readScanData() 的工作控制代碼。

• 結果

  OperationResult

  讀取資料的結果。如果值為 SUCCESS，則 data 包含下一個 (長度可能為零) 準備讀取的圖片資料區塊。如果值為 EOF，則 data 包含「最後」一個圖片資料區塊。

ScannerInfo

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• connectionType

  ConnectionType

  表示掃描器與電腦的連線方式。

• deviceUuid

  字串

  用於比對指向相同實體裝置的其他 ScannerInfo 項目。

• imageFormats

  string[]

  可要求傳回掃描結果的 MIME 類型陣列。

• 製造商

  字串

  掃描器製造商。

• 模型

  字串

  掃描器型號 (如有) 或一般說明。

• 名稱

  字串

  掃描器在使用者介面中顯示的名稱，應為人類可讀。

• protocolType

  字串

  人類可讀的通訊協定或驅動程式說明，用於存取掃描器，例如 Mopria、WSD 或 epsonds。如果裝置支援多種通訊協定，這項功能主要可讓使用者選擇通訊協定。

• scannerId

  字串

  特定掃描器的 ID。

• 安全

  布林值

  如果設為 True，掃描器連線的傳輸作業就無法由被動監聽器 (例如 TLS 或 USB) 攔截。

ScannerOption

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 可設定性

  可設定性

  指出是否可以變更選項，以及變更方式。

• 限制

  OptionConstraint 選用

  定義目前掃描器選項的 OptionConstraint。

• 說明

  字串

  選項的詳細說明。

• isActive

  布林值

  表示選項處於有效狀態，可設定或擷取。如果為 false，則不會設定 value 屬性。

• isAdvanced

  布林值

  表示 UI 預設不應顯示這個選項。

• isAutoSettable

  布林值

  可由掃描器驅動程式自動設定。

• isDetectable

  布林值

  表示可透過軟體偵測到這個選項。

• isEmulated

  布林值

  如果為 true，則由掃描器驅動程式模擬。

• 名稱

  字串

  選項名稱，使用小寫 ASCII 字母、數字和破折號。不得使用變音符號。

• title

  字串

  可列印的單行標題。

• 類型

  OptionType

  value 屬性包含的資料類型，設定這個選項時必須提供。

• 單位

  OptionUnit

  這個選項的計量單位。

• 值

  string | number | boolean | number[] 選填

  選項的目前值 (如適用)。請注意，這項屬性的資料類型必須與 type 中指定的資料類型相符。

ScanOptions

屬性

• maxImages

  數字 選填

  允許掃描的映像檔數量。預設值為 1。

• mimeTypes

  string[] 選填

  呼叫端接受的 MIME 類型。

ScanResults

屬性

• dataUrls

  string[]

  資料圖片網址陣列，格式可做為「src」值傳遞至圖片標記。

• mimeType

  字串

  dataUrls 的 MIME 類型。

SetOptionResult

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 名稱

  字串

  表示已設定的選項名稱。

• 結果

  OperationResult

  表示設定選項的結果。

SetOptionsResponse

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 選項

  物件 選填

  嘗試設定所有提供的選項後，從選項名稱到 ScannerOption 值的更新鍵/值對應，其中包含新設定。這與 OpenScannerResponse 中的 options 屬性結構相同。

  即使部分選項未設定成功，系統仍會設定這項屬性，但如果無法擷取更新後的設定 (例如掃描器在掃描過程中中斷連線)，系統就不會設定這項屬性。

• 結果

  SetOptionResult[]

  結果陣列，每個傳入的 OptionSetting 各有一個。

• scannerHandle

  字串

  提供傳遞至 setOptions() 的掃描器控制代碼。

StartScanOptions

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• format

  字串

  指定傳回掃描資料時使用的 MIME 類型。

• maxReadSize

  數字 選填

  如果指定非零值，則單一 readScanData 回應中傳回的掃描位元組數上限會限制為該值。允許的最小值為 32768 (32 KB)。如未指定這項屬性，傳回的區塊大小可能與整個掃描圖片一樣大。

StartScanResponse

Chrome 125 以上版本 Chrome 148 起為 browser.*

屬性

• 工作

  字串 選填

  如果 result 為 SUCCESS，則提供可用於讀取掃描資料或取消工作的控制代碼。

• 結果

  OperationResult

  啟動掃描的結果。如果這個值為 SUCCESS，系統會填入 job 屬性。

• scannerHandle

  字串

  提供傳遞至 startScan() 的相同掃描器控制代碼。

方法

cancelScan()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

取消已啟動的掃描作業，並傳回透過 CancelScanResponse 物件解析的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。

參數

• 工作

  字串

  先前呼叫 startScan 後傳回的作用中掃描工作控制代碼。

傳回

• Promise<CancelScanResponse>

  傳回 Promise，並解析結果。

closeScanner()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

使用傳入的控制代碼關閉掃描器，並傳回會解析為 CloseScannerResponse 物件的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。即使回應不成功，提供的控制代碼也會失效，不應再用於後續作業。

參數

• scannerHandle

  字串

  指定先前呼叫 openScanner 後傳回的開啟掃描器控制代碼。

傳回

• Promise<CloseScannerResponse>

  傳回 Promise，並解析結果。

getOptionGroups()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

從先前由 openScanner 開啟的掃描器中，取得群組名稱和成員選項。這個方法會傳回 Promise，並以 GetOptionGroupsResponse 物件解析。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。

參數

• scannerHandle

  字串

  呼叫 openScanner 後傳回的開啟掃描器控制代碼。

傳回

• Promise<GetOptionGroupsResponse>

  傳回 Promise，並解析結果。

getScannerList()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

取得可用掃描器清單，並傳回以 GetScannerListResponse 物件解析的 Promise。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。

參數

• 篩選器

  DeviceFilter

  DeviceFilter，指出應傳回哪些類型的掃描器。

傳回

• Promise<GetScannerListResponse>

  傳回 Promise，其中包含結果和掃描器清單。

openScanner()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

開啟掃描器以取得專屬存取權，並傳回會解析為 OpenScannerResponse 物件的 Promise。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。

參數

• scannerId

  字串

  要開啟的掃描器 ID。這個值是先前呼叫 getScannerList 後傳回的值。

傳回

• Promise<OpenScannerResponse>

  傳回 Promise，並解析結果。

readScanData()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

從有效工作控制代碼讀取下一個可用的圖片資料區塊，並傳回會解析為 ReadScanDataResponse 物件的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。

**注意：**回應結果可以為 SUCCESS，且 data 成員長度為零。這表示掃描器仍在運作，但尚未準備好其他資料。呼叫端應稍候片刻，然後再試一次。

掃描工作完成後，回應會顯示 EOF 的結果值。這項回應可能包含最終非零 data 成員。

參數

• 工作

  字串

  先前從 startScan 傳回的使用中工作控制代碼。

傳回

• Promise<ReadScanDataResponse>

  傳回 Promise，並解析結果。

scan()

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

執行文件掃描，並傳回 Promise，其會解析為 ScanResults 物件。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。

參數

• 選項

  ScanOptions

  包含掃描參數的物件。

傳回

• Promise<ScanResults>

  Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

  傳回 Promise，並解析掃描結果。

setOptions()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

設定指定掃描器的選項，並傳回 Promise，其解析為 SetOptionsResponse 物件，其中包含嘗試按照傳入 OptionSetting 物件的順序設定每個值的結果。如果使用回呼，系統會改為將物件傳遞至回呼。

參數

• scannerHandle

  字串

  要設定選項的掃描器控點。這個值應為先前呼叫 openScanner 後傳回的值。

• 選項

  OptionSetting[]

  要套用至掃描器的 OptionSetting 物件清單。

傳回

• Promise<SetOptionsResponse>

  傳回 Promise，並解析結果。

startScan()

Chrome 125 以上版本 Chrome 148 起為 browser.*

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

在指定掃描器上啟動掃描，並傳回會解析為 StartScanResponse 的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。如果呼叫成功，回應會包含工作控制代碼，可用於後續呼叫，讀取掃描資料或取消掃描。

參數

• scannerHandle

  字串

  開啟掃描器的控點。這個值應為先前呼叫 openScanner 後傳回的值。

• 選項

  StartScanOptions

  StartScanOptions 物件，用於指出掃描時要使用的選項。StartScanOptions.format 屬性必須與掃描器 ScannerInfo 中傳回的其中一個項目相符。

傳回

• Promise<StartScanResponse>

  傳回 Promise，並解析結果。