chrome.documentScan

說明

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

權限

documentScan

可用性

Chrome 44 以上版本 僅適用於 ChromeOS

文件掃描 API

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

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

列舉

「未指定」

「USB」

「網路」

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

屬性

  • 局部

    布林值 選填

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

  • 安全

    布林值 選填

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

GetOptionGroupsResponse

Chrome 125 以上版本

屬性

  • 群組

    OptionGroup[] 選用

    如果 result 為 SUCCESS，請按照掃描器驅動程式提供的順序提供選項群組清單。

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

  • scannerHandle

    字串

    傳遞至 getOptionGroups 的掃描器控點相同。

GetScannerListResponse

Chrome 125 以上版本

屬性

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

  • 掃描器

    ScannerInfo[]

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

OpenScannerResponse

Chrome 125 以上版本

屬性

  • 選項

    物件 optional

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

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

  • scannerHandle

    string optional

    如果 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 的記憶體不足，無法完成執行作業。

「無法配對」
無法連線至裝置。

「MISSING」
裝置已中斷連線。

"INTERNAL_ERROR"
呼叫應用程式以外的地方發生錯誤。

OptionConstraint

Chrome 125 以上版本

屬性

  • list

    string[] |number[] 選填

  • 最高

    編號 選填

  • 分鐘

    編號 選填

  • 量化

    編號 選填

OptionGroup

Chrome 125 以上版本

屬性

  • 成員

    string[]

    由駕駛人提供順序的選項名稱陣列。

  • title

    字串

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

OptionSetting

Chrome 125 以上版本

屬性

  • 名稱

    字串

    指出要設定的選項名稱。

  • 類型

    OptionType

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

  • 值

    string |數字 |boolean |number[] 選填

    指出要設定的值。啟用 autoSettable 後，如果這些選項已啟用自動設定，請勿設定。為 value 提供的資料類型必須與 type 相符。

OptionType

Chrome 125 以上版本

選項的資料類型。

列舉

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

"BOOL"
value 屬性會是 truefalse 其中之一。

"INT"
帶正負號 32 位元整數。value 屬性可能會很長或長 []，視選項是否包含多個值而定。

「已修正」
介於 -32768-32767.9999 之間的雙倍，解析度為 1/65535。value 屬性會是雙倍或雙倍 []，取決於這個選項是否包含多個值。無法準確表示的雙精度值會四捨五入為可用範圍和精確度。

"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 類型陣列。

  • 製造商

    字串

    掃描器製造商。

  • 模型

    字串

    掃描器模型 (如有)，或是一般說明。

  • 名稱

    字串

    使用者可理解的名稱，供掃描器顯示在使用者介面中。

  • 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

    此選項的測量單位。

  • 值

    string |數字 |boolean |number[] 選填

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

ScanOptions

屬性

  • maxImages

    編號 選填

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

  • mimeTypes

    string[] 選填

    呼叫端接受的 MIME 類型。

ScanResults

屬性

  • dataUrls

    string[]

    資料圖片網址陣列，可透過「src」傳送值加到圖片廣告代碼中。

  • mimeType

    字串

    dataUrls 的 MIME 類型。

SetOptionResult

Chrome 125 以上版本

屬性

  • 名稱

    字串

    表示已設定的選項名稱。

  • 表示設定選項的結果。

SetOptionsResponse

Chrome 125 以上版本

屬性

  • 選項

    物件 optional

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

    即使部分選項沒有成功設定，系統仍會設定這個屬性；但如果擷取更新的設定失敗，系統就不會設定這個屬性 (例如掃描期間中斷掃描器)。

  • 結果

    SetOptionResult[]

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

  • scannerHandle

    字串

    提供傳遞至 setOptions() 的掃描器控點。

StartScanOptions

Chrome 125 以上版本

屬性

  • format

    字串

    指定要傳回掃描資料的 MIME 類型。

  • maxReadSize

    編號 選填

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

StartScanResponse

Chrome 125 以上版本

屬性

  • 工作

    string optional

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

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

  • scannerHandle

    字串

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

方法

cancelScan()

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

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

參數

傳回

  • Promise<CancelScanResponse>

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

closeScanner()

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

使用傳入的控點關閉掃描器，並傳回透過 CloseScannerResponse 物件解析的 Promise。如果使用回呼，則會將物件傳遞至回呼。即使回應未成功，提供的帳號代碼也會失效，不應用於進一步的作業。

參數

傳回

  • Promise<CloseScannerResponse>

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getOptionGroups()

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

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

參數

傳回

  • Promise<GetOptionGroupsResponse>

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getScannerList()

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

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

參數

傳回

  • Promise<GetScannerListResponse>

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

openScanner()

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

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

參數

傳回

  • Promise<OpenScannerResponse>

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

readScanData()

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

這個外掛程式能讀取執行中工作處理常式的下一個可用圖片區塊，並傳回使用 ReadScanDataResponse 物件解析的 Promise。如果使用回呼，則會將物件傳遞至回呼。

**注意：**如果回應結果包含長度為零的 data 成員，SUCCESS 就會視為有效。這代表掃描器仍在執行，但尚未備妥其他資料。呼叫端應等待一小段時間，然後再試一次。

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

參數

傳回

  • Promise<ReadScanDataResponse>

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

scan()

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

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

參數

傳回

  • Promise<ScanResults>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

setOptions()

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

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

參數

  • scannerHandle

    字串

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

  • 選項

    OptionSetting[]

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (response: SetOptionsResponse) => void

傳回

  • Promise<SetOptionsResponse>

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

startScan()

Promise Chrome 125 以上版本 
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 及以上版本，其他平台需要使用回呼。