chrome.documentScan

說明

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

權限

documentScan

可用性

Chrome 44 以上版本 僅適用於 ChromeOS

Document Scan API

文件掃描 API 的設計宗旨，是讓應用程式和擴充功能查看連接的文件掃描器上的紙本文件內容。

類型

CancelScanResponse

Chrome 125 以上版本

屬性

  • 工作

    字串

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

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

CloseScannerResponse

Chrome 125 以上版本

屬性

  • 關閉掃描器後，即使這個值不是 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 以上版本

屬性

  • local

    布林值 選填

    請只退回直接連接電腦的掃描器。

  • 安全

    布林值 選填

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

GetOptionGroupsResponse

Chrome 125 以上版本

屬性

  • 群組

    OptionGroup[] 選用

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

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

  • scannerHandle

    字串

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

GetScannerListResponse

Chrome 125 以上版本

屬性

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

  • 掃描器

    ScannerInfo[]

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

OpenScannerResponse

Chrome 125 以上版本

屬性

  • 選項

    object 選填

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

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

  • scannerHandle

    字串 選填

    如果 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[] 選用

  • max

    號碼 選填

  • 分鐘

    號碼 選填

  • quant

    號碼 選填

OptionGroup

Chrome 125 以上版本

屬性

  • 成員

    string[]

    驅動程式提供的選項名稱陣列。

  • title

    字串

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

OptionSetting

Chrome 125 以上版本

屬性

  • 名稱

    字串

    指出要設定的選項名稱。

  • 類型

    OptionType

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

  • 值

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

    指出要設定的值。如要為已啟用 autoSettable 的選項要求自動設定，請將此欄位設為未設定。為 value 提供的資料類型必須與 type 相符。

OptionType

Chrome 125 以上版本

選項的資料類型。

列舉

「UNKNOWN」
選項的資料類型不明。value 屬性將取消設定。

「BOOL」
value true 屬性將為「false」。

「INT」
帶正負號的 32 位元整數。value 屬性會是 long 或 long[]，視選項是否採用多個值而定。

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

「STRING」
任何位元組序列，但 NUL (「\0」) 除外。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() 的工作控制代碼。

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

ScannerInfo

Chrome 125 以上版本

屬性

  • connectionType

    ConnectionType

    指出掃描器與電腦的連線方式。

  • deviceUuid

    字串

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

  • imageFormats

    string[]

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

  • 製造商

    字串

    掃描器製造商。

  • 模型

    字串

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

  • 名稱

    字串

    掃描器在 UI 中顯示的名稱，方便使用者辨識。

  • 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

    字串陣列 選用

    呼叫端接受的 MIME 類型。

ScanResults

屬性

  • dataUrls

    string[]

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

  • mimeType

    字串

    dataUrls 的 MIME 類型。

SetOptionResult

Chrome 125 以上版本

屬性

  • 名稱

    字串

    指出已設定的選項名稱。

  • 指出設定選項的結果。

SetOptionsResponse

Chrome 125 以上版本

屬性

  • 選項

    object 選填

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

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

  • 結果

    SetOptionResult[]

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

  • scannerHandle

    字串

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

StartScanOptions

Chrome 125 以上版本

屬性

  • format

    字串

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

  • maxReadSize

    號碼 選填

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

StartScanResponse

Chrome 125 以上版本

屬性

  • 工作

    字串 選填

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

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

  • scannerHandle

    字串

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

方法

cancelScan()

承諾 Chrome 125 以上版本 
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
): Promise<CancelScanResponse>

取消已啟動的掃描作業，並傳回 Promise，該 Promise 會以 CancelScanResponse 物件解析。如果使用回呼，則會將物件傳遞至回呼。

參數

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

closeScanner()

承諾 Chrome 125 以上版本 
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
): Promise<CloseScannerResponse>

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

參數

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getOptionGroups()

承諾 Chrome 125 以上版本 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
): Promise<GetOptionGroupsResponse>

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

參數

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getScannerList()

承諾 Chrome 125 以上版本 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
): Promise<GetScannerListResponse>

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

參數

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

openScanner()

承諾 Chrome 125 以上版本 
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
): Promise<OpenScannerResponse>

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

參數

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

readScanData()

承諾 Chrome 125 以上版本 
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
): Promise<ReadScanDataResponse>

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

**注意：**回應結果可以是 SUCCESS，且 data 成員長度為零。這表示掃描器仍在運作，但尚未準備好額外資料。通話者應稍待片刻，然後再試一次。

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

參數

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

scan()

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

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

參數

傳回

  • Promise<ScanResults>

    Chrome 96 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setOptions()

承諾 Chrome 125 以上版本 
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
): Promise<SetOptionsResponse>

在指定的掃描器上設定選項，並傳回 Promise，該 Promise 會使用 SetOptionsResponse 物件解析，其中包含嘗試依傳入的 OptionSetting 物件順序設定每個值的結果。如果使用回呼，則會將物件傳遞至回呼。

參數

  • scannerHandle

    字串

    掃描器的控制代碼，用於設定選項。這個值應是先前呼叫 openScanner 時傳回的值。

  • 選項

    OptionSetting[]

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

  • callback

    函式 選用

    callback 參數如下： 

    (response: SetOptionsResponse) => void

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

startScan()

承諾 Chrome 125 以上版本 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
): Promise<StartScanResponse>

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

參數

  • scannerHandle

    字串

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

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

  • callback

    函式 選用

    callback 參數如下： 

    (response: StartScanResponse) => void

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。