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

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

列舉

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

屬性

  • 選項

    物件選用

    如果 result 為 SUCCESS，請提供鍵/值對應，其中鍵是裝置專用選項，值則是 ScannerOption 執行個體。

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

  • scannerHandle

    字串 選用

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

  • scannerId

    字串

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

OperationResult

Chrome 125 以上版本

指出每個作業結果的列舉項目。

列舉

「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

Chrome 125 以上版本

屬性

  • list

    string[]|number[] optional

  • 最高

    數字 選填

  • 分鐘

    數字 選填

  • 量化

    數字 選填

OptionGroup

Chrome 125 以上版本

屬性

  • 成員

    string[]

    一系列選項名稱 (按驅動程式提供的順序)。

  • title

    字串

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

OptionSetting

Chrome 125 以上版本

屬性

  • 名稱

    字串

    用於表示要設定的選項名稱。

  • 類型

    OptionType

    用於表示選項的資料類型。要求的資料類型必須與基礎選項的實際資料類型相符。

  • 值

    string|number|boolean|number[] optional

    指出要設定的值。如果不設定，系統會針對已啟用 autoSettable 的選項要求自動設定。您為 value 提供的資料類型必須與 type 相符。

OptionType

Chrome 125 以上版本

選項的資料類型。

列舉

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

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

"INT"
帶正負號的 32 位元整數。value 屬性將是長或長 []，視該選項是否接受多個值而定。

"FIXED"
範圍 -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"
這個值是百分比，例如亮度。

"MICROsec"
這個值的測量單位為微秒，例如曝光時間。

ReadScanDataResponse

Chrome 125 以上版本

屬性

  • 資料或曾存取這類資料的人員

    ArrayBuffer 選用

    如果 result 是 SUCCESS，則包含掃描圖片資料的「下一個」區塊。如果 result 是 EOF，則包含最後區塊掃描的圖片資料區塊。

  • estimatedCompletion

    數字 選填

    如果 result 為 SUCCESS，表示目前已提交的總掃描資料預估值，範圍介於 0 到 100 之間。

  • 工作

    字串

    提供傳送至 readScanData() 的工作控制代碼。

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

ScannerInfo

Chrome 125 以上版本

屬性

  • connectionType

    ConnectionType

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

  • deviceUuid

    字串

    用於比對指向同一實體裝置的其他 ScannerInfo 項目。

  • imageFormats

    string[]

    您可以針對傳回的掃描作業要求要求的 MIME 類型陣列。

  • 製造商

    字串

    掃描器製造商。

  • model

    字串

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

  • 名稱

    字串

    要在 UI 中顯示掃描器的人類可讀名稱。

  • protocolType

    字串

    用於存取掃描器的通訊協定或驅動程式說明，以人類可讀的方式說明，例如 Mopria、WSD 或 Epsonds。如果裝置支援多種通訊協定，這種做法主要可讓使用者選擇要使用何種通訊協定。

  • scannerId

    字串

    特定掃描器的 ID。

  • 安全

    boolean

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

ScannerOption

Chrome 125 以上版本

屬性

  • 可設定性

    可設定性

    指出能否變更選項以及變更方式。

  • 限制

    OptionConstraint (選用)

    針對目前的掃描器選項定義 OptionConstraint。

  • description

    字串

    選項的詳細說明。

  • isActive

    boolean

    表示選項已啟用且可以設定或擷取。如果設為 false，系統就不會設定 value 屬性。

  • isAdvanced

    boolean

    表示 UI 預設不應顯示此選項。

  • isAutoSettable

    boolean

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

  • isDetectable

    boolean

    表示可以從軟體偵測到此選項。

  • isEmulated

    boolean

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

  • 名稱

    字串

    選項名稱，由小寫 ASCII 字母、數字和破折號組成。不得輸入變音符號。

  • title

    字串

    可列印的單行標題。

  • 類型

    OptionType

    value 屬性中包含的資料類型，這是設定這個選項的必要項目。

  • 單位

    OptionUnit

    這個選項的測量單位。

  • 值

    string|number|boolean|number[] optional

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

ScanOptions

屬性

  • maxImages

    數字 選填

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

  • mimeTypes

    string[] 選填

    呼叫端接受的 MIME 類型。

ScanResults

屬性

  • dataUrls

    string[]

    資料圖片網址陣列，格式為「src」值傳送至圖片代碼。

  • mimeType

    字串

    dataUrls 的 MIME 類型。

SetOptionResult

Chrome 125 以上版本

屬性

  • 名稱

    字串

    表示已設定的選項名稱。

  • 指出設定選項的結果。

SetOptionsResponse

Chrome 125 以上版本

屬性

  • 選項

    物件選用

    嘗試設定所有提供的選項後，將鍵/值對應從選項名稱對應至 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()

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

取消已開始的掃描，並傳回透過 CancelScanResponse 物件解析的 Promise。如果使用回呼，物件會改為傳遞給它。

參數

傳回

  • Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

closeScanner()

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

使用傳入的控制代碼關閉掃描器，並傳回可透過 CloseScannerResponse 物件解析的 Promise。如果使用回呼，物件會改為傳遞給它。即使回應未成功，提供的控制代碼也會失效，不應用於後續作業。

參數

傳回

  • Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getOptionGroups()

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

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

參數

傳回

  • Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getScannerList()

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

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

參數

傳回

  • Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

openScanner()

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

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

參數

傳回

  • Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

readScanData()

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

從進行中的工作控制代碼讀取下一個可用的圖片資料區塊，並傳回透過 ReadScanDataResponse 物件解析的 Promise。如果使用回呼，物件會改為傳遞給它。

**注意：**如果回應結果為 SUCCESS 且長度為零的 data 成員，這個類型就會有效。這代表掃描器仍在運作，但目前還無法取得其他資料。來電者應等待一小段時間，然後再試一次。

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

參數

傳回

  • 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,
)

設定指定掃描器上的選項，並傳回可透過 SetOptionsResponse 物件解析的 Promise，其中包含按照傳入的 OptionSetting 物件順序設定每個值的結果。如果使用回呼，物件會改為傳遞給它。

參數

  • scannerHandle

    字串

    用來設定選項的掃描器控點。這必須是先前呼叫 openScanner 時傳回的值。

  • 選項

    OptionSetting[]

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    (response: SetOptionsResponse)=>void

傳回

  • 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 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。