chrome.documentScan

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

說明

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

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

權限

documentScan

可用性

Chrome 44 以上版本 ChromeOS 專屬

後來新增的 API 成員會顯示在這些成員的「可用性」欄位中。

概念和用法

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

簡單掃描

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

複雜掃描

複雜掃描作業會分三個階段完成，詳情請參閱本節說明。這份大綱並未說明回應中傳回的每個方法引數或每個屬性。這只是為了提供編寫掃描器程式碼的一般指南。

注意： 呼叫 openScanner()、getScannerList() 或 startScan() 超過一次，會取消先前呼叫這些方法所啟動的作業。請參閱這些方法的說明，瞭解詳細資訊。

探索

1. 呼叫 getScannerList()。可用的掃描器會透過 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()。它會傳回承諾，並以 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()，即可設定掃描器選項。如需範例，請參閱以下「掃描一張 A4 大小的頁面」一節。

範例

將網頁擷取為 Blob

本範例說明如何從掃描器擷取頁面做為 blob，並示範如何使用 OperationResult 的值使用 startScan() 和 readScanData()。

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

掃描一個 A4 大小的頁面

本範例說明如何選取掃描器、設定選項並開啟掃描器。接著，它會擷取單一網頁的內容，並關閉掃描器。這個程序示範如何使用 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);
}

顯示設定

如前文所述，除了呼叫 openScanner() 傳回的掃描器選項外，您還必須呼叫 getOptionGroups()，才能向使用者顯示掃描器的設定選項。這樣一來，系統就能向製造商定義群組中的使用者顯示選項。以下範例說明如何執行這項操作。

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 以上版本

如何變更選項。

列舉

"NOT_CONFIGURABLE"
這個選項為唯讀。

"SOFTWARE_CONFIGURABLE"
可在軟體中設定的選項。

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

ConnectionType

Chrome 125 以上版本

表示掃描器如何連接到電腦。

列舉

"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

Chrome 125 以上版本

由 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 以上版本

屬性

• 局部

  boolean 選填

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

• 安全

  boolean 選填

  只傳回使用安全傳輸方式 (例如 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

  string 選填

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

• scannerId

  字串

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

OperationResult

Chrome 125 以上版本

列舉，用於指出每項作業的結果。

列舉

「UNKNOWN」
發生不明或一般性錯誤。

"SUCCESS"
作業成功。

「UNSUPPORTED」
系統不支援這項作業。

"CANCELLED"
作業已取消。

"DEVICE_BUSY"
裝置忙碌中。

「INVALID」
傳遞至方法的資料或引數無效。

"WRONG_TYPE"
所提供的值是基礎選項的錯誤資料類型。

「EOF」
沒有其他資料可用。

"ADF_JAMMED"
文件送紙器發生卡紙。

"ADF_EMPTY"
文件送紙器為空。

"COVER_OPEN"
平板蓋已開啟。

"IO_ERROR"
與裝置通訊時發生錯誤。

"ACCESS_DENIED"
裝置需要驗證。

"NO_MEMORY"
Chromebook 的記憶體不足，無法完成作業。

「UNREACHABLE」
無法連線至裝置。

"MISSING"
裝置已中斷連線。

"INTERNAL_ERROR"
除了呼叫應用程式以外，其他位置發生錯誤。

OptionConstraint

Chrome 125 以上版本

屬性

• list

  string[] | number[] 選填

• 最高

  號碼 選填

• 分鐘

  號碼 選填

• quant

  號碼 選填

• 類型

  ConstraintType

OptionGroup

Chrome 125 以上版本

屬性

• 成員

  string[]

  以駕駛員提供的順序，列出選項名稱的陣列。

• title

  字串

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

OptionSetting

Chrome 125 以上版本

屬性

• 名稱

  字串

  指出要設定的選項名稱。

• 類型

  OptionType

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

• 值

  字串 | 數字 | 布林值 | 數字陣列 選用

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

OptionType

Chrome 125 以上版本

選項的資料類型。

列舉

"UNKNOWN"
選項的資料類型不明。系統會取消設定 value 屬性。

「BOOL」
value 屬性會是 truefalse 其中一個值。

"INT"
已簽署的 32 位元整數。value 屬性會是 long 或 long[]，視選項是否採用多個值而定。

「FIXED」
double 值介於 -32768 到 32767.9999，解析度為 1/65535。value 屬性會是 double 或 double[]，取決於選項是否採用多個值。無法精確表示的雙精確度值會四捨五入至可用的範圍和精確度。

"STRING"
任何位元組序列 (除了 NUL 以外)。value 屬性會是 DOMString。

「BUTTON」
這類選項沒有值。相反地，設定這類選項會在掃描器驅動程式中造成選項專屬的副作用。舉例來說，掃描器驅動程式可以使用按鈕類型選項，提供選取預設值的管道，或指示自動文件進紙器前進到下一張紙張。

「GROUP」
分組選項。無值。這項資訊是為了相容性而納入，但通常不會以 ScannerOption 值傳回。使用 getOptionGroups() 擷取群組清單及其成員選項。

OptionUnit

Chrome 125 以上版本

表示 ScannerOption.unit 的資料類型。

列舉

"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

  字串

  特定掃描器的 ID。

• 安全

  布林值

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

ScannerOption

Chrome 125 以上版本

屬性

• 可設定性

  可設定性

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

• 限制

  OptionConstraint 選填

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

• 說明

  字串

  選項的詳細說明。

• isActive

  布林值

  表示選項處於有效狀態，可進行設定或擷取。如果設為 False，系統就不會設定 value 屬性。

• isAdvanced

  布林值

  表示 UI 不應在預設情況下顯示此選項。

• isAutoSettable

  布林值

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

• isDetectable

  布林值

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

• isEmulated

  布林值

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

• 名稱

  字串

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

• title

  字串

  可列印的單行標題。

• 類型

  OptionType

  value 屬性中包含的資料類型，這是設定這個選項所需的內容。

• 單位

  OptionUnit

  這個選項的測量單位。

• 值

  字串 | 數字 | 布林值 | 數字陣列 選用

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

ScanOptions

屬性

• maxImages

  號碼 選填

  允許掃描的圖片數量。預設值為 1。

• mimeTypes

  string[] 選填

  呼叫端接受的 MIME 類型。

ScanResults

屬性

• dataUrls

  string[]

  資料圖片網址陣列，可做為「src」值傳遞至圖片代碼。

• mimeType

  字串

  dataUrls 的 MIME 類型。

SetOptionResult

Chrome 125 以上版本

屬性

• 名稱

  字串

  指出已設定的選項名稱。

• 結果

  OperationResult

  指出設定選項的結果。

SetOptionsResponse

Chrome 125 以上版本

屬性

• 選項

  物件 選填

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

  即使部分選項未成功設定，系統也會設定這個屬性，但如果擷取更新的設定失敗 (例如掃描器在掃描期間中斷連線)，系統就會取消設定。

• 結果

  SetOptionResult[]

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

• scannerHandle

  字串

  提供傳遞至 setOptions() 的掃描器句柄。

StartScanOptions

Chrome 125 以上版本

屬性

• format

  字串

  指定要以何種 MIME 類型傳回掃描資料。

• maxReadSize

  號碼 選填

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

StartScanResponse

Chrome 125 以上版本

屬性

• 工作

  string 選填

  如果 result 為 SUCCESS，則會提供可用於讀取掃描資料或取消工作之句柄。

• 結果

  OperationResult

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

• scannerHandle

  字串

  提供與傳遞至 startScan() 相同的掃描器句柄。

方法

cancelScan()

Promise Chrome 125 以上版本

chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

取消已開始的掃描作業，並傳回會以 CancelScanResponse 物件解析的 Promise。如果使用回呼，系統會改為將物件傳遞給回呼。

參數

• 工作

  字串

  先前從呼叫 startScan 傳回的有效掃描作業句柄。

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: CancelScanResponse) => void

  • 回應

    CancelScanResponse

傳回

• Promise<CancelScanResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

closeScanner()

Promise Chrome 125 以上版本

chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

使用傳入的句柄關閉掃描器，並傳回會以 CloseScannerResponse 物件解析的 Promise。如果使用回呼，系統會改為將物件傳遞給回呼。即使回應失敗，提供的句柄也會失效，因此不應用於後續作業。

參數

• scannerHandle

  字串

  指定先前從呼叫 openScanner 傳回的已開啟掃描器的句柄。

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: CloseScannerResponse) => void

  • 回應

    CloseScannerResponse

傳回

• Promise<CloseScannerResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getOptionGroups()

Promise Chrome 125 以上版本

chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

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

參數

• scannerHandle

  字串

  從呼叫 openScanner 傳回的已開啟掃描器的句柄。

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: GetOptionGroupsResponse) => void

  • 回應

    GetOptionGroupsResponse

傳回

• Promise<GetOptionGroupsResponseGetOptionGroupsResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getScannerList()

Promise Chrome 125 以上版本

chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

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

參數

• 篩選器

  DeviceFilter

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

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: GetScannerListResponse) => void

  • 回應

    GetScannerListResponse

傳回

• Promise<GetScannerListResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

openScanner()

Promise Chrome 125 以上版本

chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

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

參數

• scannerId

  字串

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

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: OpenScannerResponse) => void

  • 回應

    OpenScannerResponse

傳回

• Promise<OpenScannerResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

readScanData()

Promise Chrome 125 以上版本

chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

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

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

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

參數

• 工作

  字串

  先前從 startScan 傳回的有效工作句柄。

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: ReadScanDataResponse) => void

  • 回應

    ReadScanDataResponse

傳回

• Promise<ReadScanDataResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

scan()

Promise

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

執行文件掃描作業，並傳回 Promise，該 Promise 會以 ScanResults 物件解析。如果回呼傳遞至此函式，則會改為傳遞傳回的資料。

參數

• 選項

  ScanOptions

  包含掃描參數的物件。

• 回呼

  函式 選填

  callback 參數如下所示：

  (result: ScanResults) => void

  • 結果

    ScanResults

傳回

• Promise<ScanResults>

  Chrome 96 以上版本

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setOptions()

Promise Chrome 125 以上版本

chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
)

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

參數

• scannerHandle

  字串

  掃描器的把手，用於設定選項。這個值應為先前呼叫 openScanner 時傳回的值。

• 選項

  OptionSetting[]

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

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: SetOptionsResponse) => void

  • 回應

    SetOptionsResponse

傳回

• Promise<SetOptionsResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

startScan()

Promise Chrome 125 以上版本

chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

在指定的掃描器上啟動掃描作業，並傳回 Promise，該 Promise 會透過 StartScanResponse 解析。如果使用回呼，系統會改為將物件傳遞給回呼。如果呼叫成功，回應會包含工作句柄，可在後續呼叫中用於讀取掃描資料或取消掃描。

參數

• scannerHandle

  字串

  已開啟掃描器的句柄。這個值應為先前呼叫 openScanner 時傳回的值。

• 選項

  StartScanOptions

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

• 回呼

  函式 選填

  callback 參數如下所示：

  (response: StartScanResponse) => void

  • 回應

    StartScanResponse

傳回

• Promise<StartScanResponse>

  承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。