refresh date: 2026-09-25 robots: noindex
說明
使用 chrome.documentScan API 探索及擷取連接的文件掃描器中的圖片。
權限
documentScan可用性
Document Scan API
Document Scan API 可讓應用程式和擴充功能，在連接的文件掃描器上查看紙本文件的內容。
類型
CancelScanResponse
屬性
-
工作
字串
提供與傳遞至
cancelScan()相同的工作控制代碼。 -
後端的取消掃描結果。如果結果是
OperationResult.SUCCESS或OperationResult.CANCELLED，表示掃描作業已取消，掃描器已準備好開始新的掃描作業。如果結果為OperationResult.DEVICE_BUSY，表示掃描器仍在處理取消要求，呼叫端應稍候片刻，然後再次嘗試要求。其他結果值表示永久錯誤，不應重試。
CloseScannerResponse
屬性
-
關閉掃描器的結果。即使這個值不是
SUCCESS，控制代碼也會無效，不應再用於任何作業。 -
scannerHandle
字串
與傳遞至
closeScanner的掃描器控制代碼相同。
Configurability
如何變更選項。
列舉
"NOT_CONFIGURABLE"
選項為唯讀。
「SOFTWARE_CONFIGURABLE」
可在軟體中設定選項。
"HARDWARE_CONFIGURABLE"
使用者可以切換或按下掃描器上的按鈕來設定選項。
ConnectionType
表示掃描器與電腦的連線方式。
列舉
"UNSPECIFIED"
「USB」
"NETWORK"
列舉
"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
屬性
-
local
布林值 選填
只傳回直接連接到電腦的掃描器。
-
安全
布林值 選填
只傳回使用安全傳輸方式 (例如 USB 或 TLS) 的掃描器。
GetOptionGroupsResponse
屬性
-
群組
OptionGroup[] 選填
如果
result為SUCCESS，則會按照掃描器驅動程式提供的順序，列出選項群組。 -
取得選項群組的結果。如果這個值為
SUCCESS，系統會填入groups屬性。 -
scannerHandle
字串
與傳遞至
getOptionGroups的掃描器控制代碼相同。
GetScannerListResponse
屬性
-
列舉結果。請注意，即使這表示發生錯誤，系統仍可能傳回部分結果。
-
掃描器
與提供的
DeviceFilter相符的掃描器清單 (可能為空白)。
OpenScannerResponse
屬性
-
選項
物件 選填
如果
result為SUCCESS，則提供鍵/值對應，其中鍵為裝置專屬選項，值為ScannerOption的例項。 -
開啟掃描器的結果。如果這個值為
SUCCESS，系統會填入scannerHandle和options屬性。 -
scannerHandle
字串 選填
如果
result為SUCCESS，則為掃描器的控制代碼，可用於進一步操作。 -
scannerId
字串
傳遞至
openScanner()的掃描器 ID。
OperationResult
表示每項作業結果的列舉。
列舉
「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
屬性
-
list
string[] | number[] 選填
-
max
數字 選填
-
分鐘
數字 選填
-
quant
數字 選填
OptionGroup
屬性
-
成員
string[]
選項名稱陣列，依驅動程式提供的順序排列。
-
title
字串
提供可列印的標題，例如「幾何圖形選項」。
OptionSetting
屬性
-
名稱
字串
表示要設定的選項名稱。
-
類型
指出選項的資料類型。要求的資料類型必須與基礎選項的實際資料類型相符。
-
值
string | number | boolean | number[] 選填
表示要設定的值。如果未設定，系統會自動設定已啟用
autoSettable的選項。為value提供的資料類型必須與type相符。
OptionType
選項的資料類型。
列舉
"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() 擷取群組清單及其成員選項。
列舉
"UNITLESS"
值為無單位數字。例如，可以是門檻。
"PIXEL"
值為像素數量，例如掃描尺寸。
「BIT」
值為位元數，例如色彩深度。
「MM」
以公釐為單位的值，例如掃描尺寸。
「DPI」
這個值是以每英寸像素數為單位，例如解析度。
「PERCENT」
值為百分比，例如亮度。
「MICROSECOND」
以微秒為單位的值，例如曝光時間。
ReadScanDataResponse
屬性
-
資料
ArrayBuffer 選用
如果
result為SUCCESS，則包含掃描圖片資料的下一個區塊。如果result為EOF，則包含掃描圖片資料的最後一個區塊。 -
estimatedCompletion
數字 選填
如果
result為SUCCESS，則表示目前已傳送的掃描資料總量預估值，範圍為 0 到 100。 -
工作
字串
提供傳遞至
readScanData()的工作控制代碼。 -
讀取資料的結果。如果值為
SUCCESS，則data包含下一個 (長度可能為零) 準備讀取的圖片資料區塊。如果值為EOF，則data包含「最後」一個圖片資料區塊。
ScannerInfo
屬性
-
connectionType
表示掃描器與電腦的連線方式。
-
deviceUuid
字串
用於比對指向相同實體裝置的其他
ScannerInfo項目。 -
imageFormats
string[]
可要求傳回掃描結果的 MIME 類型陣列。
-
製造商
字串
掃描器製造商。
-
模型
字串
掃描器型號 (如有) 或一般說明。
-
名稱
字串
掃描器在使用者介面中顯示的名稱，應為人類可讀。
-
protocolType
字串
人類可讀的通訊協定或驅動程式說明，用於存取掃描器，例如 Mopria、WSD 或 epsonds。如果裝置支援多種通訊協定，這項功能主要可讓使用者選擇通訊協定。
-
scannerId
字串
特定掃描器的 ID。
-
安全
布林值
如果設為 True，掃描器連線的傳輸作業就無法由被動監聽器 (例如 TLS 或 USB) 攔截。
ScannerOption
屬性
-
可設定性
指出是否可以變更選項，以及變更方式。
-
限制
定義目前掃描器選項的
OptionConstraint。 -
說明
字串
選項的詳細說明。
-
isActive
布林值
表示選項處於有效狀態，可設定或擷取。如果為 false，則不會設定
value屬性。 -
isAdvanced
布林值
表示 UI 預設不應顯示這個選項。
-
isAutoSettable
布林值
可由掃描器驅動程式自動設定。
-
isDetectable
布林值
表示可透過軟體偵測到這個選項。
-
isEmulated
布林值
如果為 true，則由掃描器驅動程式模擬。
-
名稱
字串
選項名稱，使用小寫 ASCII 字母、數字和破折號。不得使用變音符號。
-
title
字串
可列印的單行標題。
-
類型
value屬性包含的資料類型，設定這個選項時必須提供。 -
單位
這個選項的計量單位。
-
值
string | number | boolean | number[] 選填
選項的目前值 (如適用)。請注意，這項屬性的資料類型必須與
type中指定的資料類型相符。
ScanOptions
屬性
-
maxImages
數字 選填
允許掃描的映像檔數量。預設值為 1。
-
mimeTypes
string[] 選填
呼叫端接受的 MIME 類型。
ScanResults
屬性
-
dataUrls
string[]
資料圖片網址陣列，格式可做為「src」值傳遞至圖片標記。
-
mimeType
字串
dataUrls的 MIME 類型。
SetOptionResult
屬性
-
名稱
字串
表示已設定的選項名稱。
-
表示設定選項的結果。
SetOptionsResponse
屬性
-
選項
物件 選填
嘗試設定所有提供的選項後，從選項名稱到
ScannerOption值的更新鍵/值對應，其中包含新設定。這與OpenScannerResponse中的options屬性結構相同。即使部分選項未設定成功，系統仍會設定這項屬性，但如果無法擷取更新後的設定 (例如掃描器在掃描過程中中斷連線)，系統就不會設定這項屬性。
-
結果
結果陣列，每個傳入的
OptionSetting各有一個。 -
scannerHandle
字串
提供傳遞至
setOptions()的掃描器控制代碼。
StartScanOptions
屬性
-
format
字串
指定傳回掃描資料時使用的 MIME 類型。
-
maxReadSize
數字 選填
如果指定非零值，則單一
readScanData回應中傳回的掃描位元組數上限會限制為該值。允許的最小值為 32768 (32 KB)。如未指定這項屬性，傳回的區塊大小可能與整個掃描圖片一樣大。
StartScanResponse
屬性
-
工作
字串 選填
如果
result為SUCCESS，則提供可用於讀取掃描資料或取消工作的控制代碼。 -
啟動掃描的結果。如果這個值為
SUCCESS，系統會填入job屬性。 -
scannerHandle
字串
提供傳遞至
startScan()的相同掃描器控制代碼。
方法
cancelScan()
chrome.documentScan.cancelScan(
job: string,
callback?: function,
): Promise<CancelScanResponse>
取消已啟動的掃描作業，並傳回透過 CancelScanResponse 物件解析的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。
參數
-
工作
字串
先前呼叫
startScan後傳回的作用中掃描工作控制代碼。 -
callback
函式 選填
callback參數如下：(response: CancelScanResponse) => void
傳回
-
Promise<CancelScanResponse>
傳回 Promise，並解析結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
closeScanner()
chrome.documentScan.closeScanner(
scannerHandle: string,
callback?: function,
): Promise<CloseScannerResponse>
使用傳入的控制代碼關閉掃描器，並傳回會解析為 CloseScannerResponse 物件的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。即使回應不成功，提供的控制代碼也會失效，不應再用於後續作業。
參數
-
scannerHandle
字串
指定先前呼叫
openScanner後傳回的開啟掃描器控制代碼。 -
callback
函式 選填
callback參數如下：(response: CloseScannerResponse) => void
傳回
-
Promise<CloseScannerResponse>
傳回 Promise，並解析結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
getOptionGroups()
chrome.documentScan.getOptionGroups(
scannerHandle: string,
callback?: function,
): Promise<GetOptionGroupsResponse>
從先前由 openScanner 開啟的掃描器中，取得群組名稱和成員選項。這個方法會傳回 Promise，並以 GetOptionGroupsResponse 物件解析。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。
參數
-
scannerHandle
字串
呼叫
openScanner後傳回的開啟掃描器控制代碼。 -
callback
函式 選填
callback參數如下：(response: GetOptionGroupsResponse) => void
傳回
-
Promise<GetOptionGroupsResponse>
傳回 Promise，並解析結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
getScannerList()
chrome.documentScan.getScannerList(
filter: DeviceFilter,
callback?: function,
): Promise<GetScannerListResponse>
取得可用掃描器清單，並傳回以 GetScannerListResponse 物件解析的 Promise。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。
參數
-
篩選器
DeviceFilter，指出應傳回哪些類型的掃描器。 -
callback
函式 選填
callback參數如下：(response: GetScannerListResponse) => void
傳回
-
Promise<GetScannerListResponse>
傳回 Promise，其中包含結果和掃描器清單。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
openScanner()
chrome.documentScan.openScanner(
scannerId: string,
callback?: function,
): Promise<OpenScannerResponse>
開啟掃描器以取得專屬存取權，並傳回會解析為 OpenScannerResponse 物件的 Promise。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。
參數
-
scannerId
字串
要開啟的掃描器 ID。這個值是先前呼叫
getScannerList後傳回的值。 -
callback
函式 選填
callback參數如下：(response: OpenScannerResponse) => void
傳回
-
Promise<OpenScannerResponse>
傳回 Promise，並解析結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
readScanData()
chrome.documentScan.readScanData(
job: string,
callback?: function,
): Promise<ReadScanDataResponse>
從有效工作控制代碼讀取下一個可用的圖片資料區塊，並傳回會解析為 ReadScanDataResponse 物件的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。
**注意：**回應結果可以為 SUCCESS，且 data 成員長度為零。這表示掃描器仍在運作，但尚未準備好其他資料。呼叫端應稍候片刻，然後再試一次。
掃描工作完成後，回應會顯示 EOF 的結果值。這項回應可能包含最終非零 data 成員。
參數
-
工作
字串
先前從
startScan傳回的使用中工作控制代碼。 -
callback
函式 選填
callback參數如下：(response: ReadScanDataResponse) => void
傳回
-
Promise<ReadScanDataResponse>
傳回 Promise，並解析結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
scan()
chrome.documentScan.scan(
options: ScanOptions,
callback?: function,
): Promise<ScanResults>
執行文件掃描，並傳回 Promise，其會解析為 ScanResults 物件。如果回呼傳遞至這個函式，傳回的資料會改為傳遞至回呼。
參數
-
選項
包含掃描參數的物件。
-
callback
函式 選填
callback參數如下：(result: ScanResults) => void
-
結果
-
傳回
-
Promise<ScanResults>
Chrome 96 以上版本傳回 Promise，並解析掃描結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
setOptions()
chrome.documentScan.setOptions(
scannerHandle: string,
options: OptionSetting[],
callback?: function,
): Promise<SetOptionsResponse>
設定指定掃描器的選項，並傳回 Promise，其解析為 SetOptionsResponse 物件，其中包含嘗試按照傳入 OptionSetting 物件的順序設定每個值的結果。如果使用回呼，系統會改為將物件傳遞至回呼。
參數
-
scannerHandle
字串
要設定選項的掃描器控點。這個值應為先前呼叫
openScanner後傳回的值。 -
選項
要套用至掃描器的
OptionSetting物件清單。 -
callback
函式 選填
callback參數如下：(response: SetOptionsResponse) => void
傳回
-
Promise<SetOptionsResponse>
傳回 Promise，並解析結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。
startScan()
chrome.documentScan.startScan(
scannerHandle: string,
options: StartScanOptions,
callback?: function,
): Promise<StartScanResponse>
在指定掃描器上啟動掃描，並傳回會解析為 StartScanResponse 的 Promise。如果使用回呼，系統會改為將物件傳遞至回呼。如果呼叫成功，回應會包含工作控制代碼，可用於後續呼叫，讀取掃描資料或取消掃描。
參數
-
scannerHandle
字串
開啟掃描器的控點。這個值應為先前呼叫
openScanner後傳回的值。 -
StartScanOptions物件，用於指出掃描時要使用的選項。StartScanOptions.format屬性必須與掃描器ScannerInfo中傳回的其中一個項目相符。 -
callback
函式 選填
callback參數如下：(response: StartScanResponse) => void
傳回
-
Promise<StartScanResponse>
傳回 Promise，並解析結果。
Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。