說明
使用 chrome.documentScan
API 即可從附加的文件掃描器探索及擷取圖片。
權限
documentScan
適用國家/地區
文件掃描 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
指出掃描器與電腦的連線方式。
列舉
列舉
"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
屬性
-
局部
布林值 (選用)
只傳回直接附加至電腦的掃描器。
-
安全
布林值 (選用)
只傳回使用安全傳輸的掃描器,例如 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」
發生不明或一般錯誤。
"成功"
作業成功。
"UNSUPPORTED"
不支援這項作業。
"CANCELLED"
作業已取消。
「DEVICE_BUSY」
裝置忙碌中。
"無效"
傳遞到方法的資料或引數無效。
"WRONG_TYPE"
提供的值是基礎選項的資料類型錯誤。
"EOF"
沒有其他資料。
"ADF_JAMMED"
文件饋送器無法正常運作。
"ADF_EMPTY"
文件饋送器沒有內容。
"COVER_OPEN"
扁平的外蓋已開啟。
"IO_ERROR"
與裝置通訊時發生錯誤。
"ACCESS_DENIED"
裝置需要驗證。
「NO_MEMORY」
Chromebook 的可用記憶體不足,因此無法完成這項作業。
「無法連線」
無法連上裝置。
「MISSING」
裝置已中斷連線。
"INTERNAL_ERROR"
發出呼叫的應用程式以外的位置發生錯誤。
OptionConstraint
屬性
-
list
string[] | number[] 選填
-
max
數字 選填
-
分鐘
數字 選填
-
量化
數字 選填
OptionGroup
屬性
-
成員
string[]
一系列選項名稱 (按驅動程式提供的順序)。
-
title
字串
提供可列印的標題,例如「幾何圖形選項」。
OptionSetting
屬性
-
名稱
字串
用於表示要設定的選項名稱。
-
類型
用於表示選項的資料類型。要求的資料類型必須與基礎選項的實際資料類型相符。
-
值
string | number | 布林值 | number[] 選用
指出要設定的值。如果不設定,系統會針對已啟用
autoSettable
的選項要求自動設定。您為value
提供的資料類型必須與type
相符。
OptionType
選項的資料類型。
列舉
"UNKNOWN"
不明的選項資料類型。系統會設定 value
屬性。
"BOOL"
value
屬性會是 true
false 其中之一。
"INT"
帶正負號的 32 位元整數。value
屬性將是長或長 [],視該選項是否接受多個值而定。
"FIXED"
範圍 -32768-32767.9999 的兩倍,解析度為 1/65535。value
屬性為雙精度浮點數或雙精度浮點值 [],視選項是否接受多個值而定。無法確切表示的雙精度值會四捨五入至可用的範圍和精確度。
"STRING"
除 NUL (「\0」除外) 的任何位元組序列。value
屬性將是 DOMString。
"BUTTON"
這種類型的選項沒有任何值。反之,設定這類選項後,掃描器驅動程式中會產生特定選項的副作用。舉例來說,掃描器驅動程式可使用按鈕類型選項,以此方式選取預設值,或是指示自動文件饋送器前往下一張投影片。
"GROUP"
分組選項。沒有任何值。這是為了確保相容性,但通常不會在 ScannerOption
值中傳回。使用 getOptionGroups()
擷取包含成員選項的群組清單。
列舉
"UNITLESS"
這個值是無單位數字。例如閾值。
"PIXEL"
這個值是像素數,例如掃描尺寸。
"BIT"
這個值是位元數,例如色彩深度。
"MM"
值的測量單位為公釐,例如掃描尺寸。
"DPI"
這個值是以每英寸像素數為單位,例如解析度。
"PERCENT"
這個值是百分比,例如亮度。
"MICROsec"
這個值的測量單位為微秒,例如曝光時間。
ReadScanDataResponse
屬性
-
資料或曾存取這類資料的人員
ArrayBuffer 選用
如果
result
是SUCCESS
,則包含掃描圖片資料的「下一個」區塊。如果result
是EOF
,則包含最後區塊掃描的圖片資料區塊。 -
estimatedCompletion
數字 選填
如果
result
為SUCCESS
,表示目前已提交的總掃描資料預估值,範圍介於 0 到 100 之間。 -
工作
字串
提供傳送至
readScanData()
的工作控制代碼。 -
讀取資料的結果。如果值為
SUCCESS
,則data
會包含「next」 (長度可能是零) 的圖片資料區塊,可供讀取。如果值為EOF
,則data
會包含「最後一個」圖片資料區塊。
ScannerInfo
屬性
-
connectionType
指出掃描器與電腦的連線方式。
-
deviceUuid
字串
用於比對指向同一實體裝置的其他
ScannerInfo
項目。 -
imageFormats
string[]
您可以針對傳回的掃描作業要求要求的 MIME 類型陣列。
-
製造商
字串
掃描器製造商。
-
model
字串
掃描器模型 (如有),或是一般說明。
-
名稱
字串
要在 UI 中顯示掃描器的人類可讀名稱。
-
protocolType
字串
用於存取掃描器的通訊協定或驅動程式說明,以人類可讀的方式說明,例如 Mopria、WSD 或 Epsonds。如果裝置支援多種通訊協定,這種做法主要可讓使用者選擇要使用何種通訊協定。
-
scannerId
字串
特定掃描器的 ID。
-
安全
boolean
如果為 true,掃描器連線的傳輸作業無法由被動事件監聽器 (例如 TLS 或 USB) 攔截。
ScannerOption
屬性
-
可設定性
指出能否變更選項以及變更方式。
-
限制
OptionConstraint (選用)
針對目前的掃描器選項定義
OptionConstraint
。 -
description
字串
選項的詳細說明。
-
isActive
boolean
表示選項已啟用且可以設定或擷取。如果設為 false,系統就不會設定
value
屬性。 -
isAdvanced
boolean
表示 UI 預設不應顯示此選項。
-
isAutoSettable
boolean
可由掃描器驅動程式自動設定。
-
isDetectable
boolean
表示可以從軟體偵測到此選項。
-
isEmulated
boolean
如果為 true,將由掃描器驅動程式模擬。
-
名稱
字串
選項名稱,由小寫 ASCII 字母、數字和破折號組成。不得輸入變音符號。
-
title
字串
可列印的單行標題。
-
類型
value
屬性中包含的資料類型,這是設定這個選項的必要項目。 -
單位
這個選項的測量單位。
-
值
string | number | 布林值 | 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,
)
取消已開始的掃描,並傳回透過 CancelScanResponse
物件解析的 Promise。如果使用回呼,物件會改為傳遞給它。
參數
-
工作
字串
先前呼叫
startScan
而傳回的執行中掃描工作的控制代碼。 -
回呼
函式選用
callback
參數如下所示:(response: CancelScanResponse) => void
傳回
-
Promise<CancelScanResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
closeScanner()
chrome.documentScan.closeScanner(
scannerHandle: string,
callback?: function,
)
使用傳入的控制代碼關閉掃描器,並傳回可透過 CloseScannerResponse
物件解析的 Promise。如果使用回呼,物件會改為傳遞給它。即使回應未成功,提供的控制代碼也會失效,不應用於後續作業。
參數
-
scannerHandle
字串
指定先前呼叫
openScanner
時傳回的開放式掃描器控制代碼。 -
回呼
函式選用
callback
參數如下所示:(response: CloseScannerResponse) => void
傳回
-
Promise<CloseScannerResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getOptionGroups()
chrome.documentScan.getOptionGroups(
scannerHandle: string,
callback?: function,
)
從 openScanner
先前開啟的掃描器取得群組名稱和成員選項。這個方法會傳回 Promise,且該 Promise 透過 GetOptionGroupsResponse
物件解析。如果將回呼傳送至此函式,則傳回的資料會改為傳遞給這個函式。
參數
-
scannerHandle
字串
呼叫
openScanner
傳回的開放式掃描器控制代碼。 -
回呼
函式選用
callback
參數如下所示:(response: GetOptionGroupsResponse) => void
傳回
-
Promise<GetOptionGroupsResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getScannerList()
chrome.documentScan.getScannerList(
filter: DeviceFilter,
callback?: function,
)
取得可用的掃描器清單,並傳回可透過 GetScannerListResponse
物件解析的 Promise。如果將回呼傳送至此函式,則傳回的資料會改為傳遞給這個函式。
參數
-
篩選器
DeviceFilter
,用於指出應傳回哪些類型的掃描器。 -
回呼
函式選用
callback
參數如下所示:(response: GetScannerListResponse) => void
傳回
-
Promise<GetScannerListResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
openScanner()
chrome.documentScan.openScanner(
scannerId: string,
callback?: function,
)
開啟掃描器取得專屬存取權,並傳回透過 OpenScannerResponse
物件解析的 Promise。如果將回呼傳送至此函式,則傳回的資料會改為傳遞給這個函式。
參數
-
scannerId
字串
要開啟的掃描器 ID。這個值是先前呼叫
getScannerList
時傳回的一個值。 -
回呼
函式選用
callback
參數如下所示:(response: OpenScannerResponse) => void
傳回
-
Promise<OpenScannerResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
readScanData()
chrome.documentScan.readScanData(
job: string,
callback?: function,
)
從進行中的工作控制代碼讀取下一個可用的圖片資料區塊,並傳回透過 ReadScanDataResponse
物件解析的 Promise。如果使用回呼,物件會改為傳遞給它。
**注意:**如果回應結果為 SUCCESS
且長度為零的 data
成員,這個類型就會有效。這代表掃描器仍在運作,但目前還無法取得其他資料。來電者應等待一小段時間,然後再試一次。
掃描工作完成後,回應的值會是 EOF
。這項回覆可能包含非零的 data
最終成員。
參數
-
工作
字串
先前從
startScan
傳回的執行中工作控制代碼。 -
回呼
函式選用
callback
參數如下所示:(response: ReadScanDataResponse) => void
傳回
-
Promise<ReadScanDataResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
scan()
chrome.documentScan.scan(
options: ScanOptions,
callback?: function,
)
執行文件掃描並傳回可透過 ScanResults
物件解析的 Promise。如果將回呼傳送至此函式,則傳回的資料會改為傳遞給這個函式。
參數
-
選項
包含掃描參數的物件。
-
回呼
函式選用
callback
參數如下所示:(result: ScanResults) => void
-
結果
-
傳回
-
Promise<ScanResults>
Chrome 96 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
setOptions()
chrome.documentScan.setOptions(
scannerHandle: string,
options: OptionSetting[],
callback?: function,
)
設定指定掃描器上的選項,並傳回可透過 SetOptionsResponse
物件解析的 Promise,其中包含按照傳入的 OptionSetting
物件順序設定每個值的結果。如果使用回呼,物件會改為傳遞給它。
參數
-
scannerHandle
字串
用來設定選項的掃描器控點。這必須是先前呼叫
openScanner
時傳回的值。 -
選項
要套用至掃描器的
OptionSetting
物件清單。 -
回呼
函式選用
callback
參數如下所示:(response: SetOptionsResponse) => void
傳回
-
Promise<SetOptionsResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
startScan()
chrome.documentScan.startScan(
scannerHandle: string,
options: StartScanOptions,
callback?: function,
)
在指定掃描器上開始掃描,並傳回可透過 StartScanResponse
解析的 Promise。如果使用回呼,物件會改為傳遞給它。如果呼叫成功,回應會包含工作控制代碼,可用於後續呼叫來讀取掃描資料或取消掃描作業。
參數
-
scannerHandle
字串
開啟掃描器的控點。這必須是先前呼叫
openScanner
時傳回的值。 -
StartScanOptions
物件,指出掃描作業要使用的選項。StartScanOptions.format
屬性必須與掃描器ScannerInfo
中傳回的其中一個項目相符。 -
回呼
函式選用
callback
參數如下所示:(response: StartScanResponse) => void
傳回
-
Promise<StartScanResponse>
Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。