说明
使用 chrome.documentScan
API 从连接的文档扫描仪中发现和检索图片。
权限
documentScan
可用性
Document Scan API
文档扫描 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
属性
-
局部
布尔值(可选)
仅返回直接连接到计算机的扫描仪。
-
安全
布尔值(可选)
仅返回使用安全传输方式(例如 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”
操作成功。
“不支持”
不支持该操作。
“已取消”
相应操作已取消。
“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
number 可选
-
分钟
number 可选
-
quant
number 可选
OptionGroup
属性
-
成员
字符串[]
驱动程序提供的顺序中的选项名称数组。
-
title
字符串
提供可打印的标题,例如“几何图形选项”。
OptionSetting
属性
-
name
字符串
指明要设置的选项的名称。
-
类型
表示选项的数据类型。所请求的数据类型必须与底层选项的实际数据类型相匹配。
-
值
字符串 | 数值 | 布尔值 | 数值数组 可选
表示要设置的值。如果将此字段留空,系统将自动为已启用
autoSettable
的选项设置值。为value
提供的数据类型必须与type
一致。
OptionType
选项的数据类型。
枚举
“UNKNOWN”
相应选项的数据类型未知。value
属性将被取消设置。
“BOOL”
value
属性将为 true
false 之一。
“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”
该值是像素数,例如扫描尺寸。
“位”
该值是位数,例如颜色深度。
“MM”
该值以毫米为单位,例如扫描尺寸。
“DPI”
该值以每英寸的点数(例如分辨率)为单位进行衡量。
“PERCENT”
值是百分比,例如亮度。
“MICROSECOND”
该值以微秒为单位,例如曝光时间。
ReadScanDataResponse
属性
-
数据
ArrayBuffer 可选
如果
result
为SUCCESS
,则包含扫描的图片数据的下一个块。如果result
为EOF
,则包含扫描的图片数据的最后一块。 -
estimatedCompletion
number 可选
如果
result
为SUCCESS
,则表示到目前为止已传送的扫描数据占总扫描数据的百分比估计值,范围为 0 到 100。 -
作业
字符串
提供传递给
readScanData()
的作业句柄。 -
读取数据的结果。如果其值为
SUCCESS
,则data
包含准备好读取的下一个(可能为零长度)图片数据块。如果其值为EOF
,则data
包含图像数据的最后一个块。
ScannerInfo
属性
-
connectionType
指示扫描器与计算机的连接方式。
-
deviceUuid
字符串
用于与其他指向同一物理设备的
ScannerInfo
条目进行匹配。 -
imageFormats
字符串[]
可为返回的扫描结果请求的 MIME 类型数组。
-
制造商
字符串
扫描器制造商。
-
模型
字符串
扫描器型号(如果有)或一般说明。
-
name
字符串
扫描器在界面中显示的直观易懂的名称。
-
protocolType
字符串
用于访问扫描仪的协议或驱动程序的人类可读说明,例如 Mopria、WSD 或 epsonds。如果设备支持多种协议,此属性主要用于允许用户在这些协议之间进行选择。
-
scannerId
字符串
特定扫描器的 ID。
-
安全
布尔值
如果为 true,扫描器连接的传输无法被被动监听器(例如 TLS 或 USB)拦截。
ScannerOption
属性
-
可配置性
指示相应选项是否可以更改以及如何更改。
-
项限制条件
在当前扫描器选项上定义
OptionConstraint
。 -
说明
字符串
选项的详细说明。
-
isActive
布尔值
表示相应选项处于有效状态,可以设置或检索。如果为 false,则不会设置
value
属性。 -
isAdvanced
布尔值
表示界面不应默认显示此选项。
-
isAutoSettable
布尔值
可由扫描仪驱动程序自动设置。
-
isDetectable
布尔值
表示此选项可从软件中检测到。
-
isEmulated
布尔值
如果为 true,则由扫描器驱动程序进行模拟。
-
name
字符串
使用小写 ASCII 字母、数字和短划线的选项名称。不允许使用变音符号。
-
title
字符串
可打印的单行标题。
-
类型
value
属性中包含的数据类型,设置此选项时需要用到该数据类型。 -
单位
相应选项的计量单位。
-
值
字符串 | 数值 | 布尔值 | 数值数组 可选
选项的当前值(如果相关)。请注意,此属性的数据类型必须与
type
中指定的数据类型一致。
ScanOptions
属性
-
maxImages
number 可选
允许扫描的图片数量。默认值为 1。
-
mimeTypes
string[] 可选
调用方接受的 MIME 类型。
ScanResults
属性
-
dataUrls
字符串[]
一个数据图片网址数组,其格式可作为“src”值传递给图片标记。
-
mimeType
字符串
dataUrls
的 MIME 类型。
SetOptionResult
属性
-
name
字符串
指明所设置选项的名称。
-
指示设置选项的结果。
SetOptionsResponse
属性
-
选项
对象(可选)
一个更新后的键值映射,其中包含从选项名称到
ScannerOption
值的映射,这些值包含尝试设置所有提供的选项后的新配置。此属性的结构与OpenScannerResponse
中的options
属性相同。即使某些选项未成功设置,系统也会设置此属性;但如果检索更新后的配置失败(例如,扫描器在扫描过程中断开连接),系统将取消设置此属性。
-
结果
一个结果数组,每个传入的
OptionSetting
对应一个结果。 -
scannerHandle
字符串
提供传递给
setOptions()
的扫描器句柄。
StartScanOptions
属性
-
格式
字符串
指定返回扫描数据的 MIME 类型。
-
maxReadSize
number 可选
如果指定了非零值,则将单个
readScanData
响应中返回的最大扫描字节数限制为该值。允许的最小值是 32768(32 KB)。如果未指定此属性,则返回的块的大小可能与整个扫描的图片一样大。
StartScanResponse
属性
-
作业
字符串(选填)
如果
result
为SUCCESS
,则提供可用于读取扫描数据或取消作业的句柄。 -
启动扫描的结果。如果此属性的值为
SUCCESS
,系统将填充job
属性。 -
scannerHandle
字符串
提供传递给
startScan()
的相同扫描器句柄。
方法
cancelScan()
chrome.documentScan.cancelScan(
job: string,
callback?: function,
): Promise<CancelScanResponse>
取消已开始的扫描,并返回一个 Promise,该 Promise 会解析为 CancelScanResponse
对象。如果使用回调,则会将对象传递给回调。
参数
-
作业
字符串
之前从对
startScan
的调用返回的有效扫描作业的句柄。 -
callback
函数 可选
callback
参数如下所示:(response: CancelScanResponse) => void
-
Response
-
返回
-
Promise<CancelScanResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
closeScanner()
chrome.documentScan.closeScanner(
scannerHandle: string,
callback?: function,
): Promise<CloseScannerResponse>
使用传入的句柄关闭扫描器,并返回一个 Promise,该 Promise 会解析为 CloseScannerResponse
对象。如果使用回调,则会将对象传递给回调。即使响应不成功,所提供的句柄也会失效,不应再用于后续操作。
参数
-
scannerHandle
字符串
指定之前从对
openScanner
的调用返回的开放扫描器的句柄。 -
callback
函数 可选
callback
参数如下所示:(response: CloseScannerResponse) => void
-
Response
-
返回
-
Promise<CloseScannerResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getOptionGroups()
chrome.documentScan.getOptionGroups(
scannerHandle: string,
callback?: function,
): Promise<GetOptionGroupsResponse>
从之前通过 openScanner
打开的扫描器获取群组名称和成员选项。此方法会返回一个 Promise,该 Promise 会解析为一个 GetOptionGroupsResponse
对象。如果向此函数传递了回调,则返回的数据会传递给该回调。
参数
-
scannerHandle
字符串
通过调用
openScanner
返回的已打开扫描器的句柄。 -
callback
函数 可选
callback
参数如下所示:(response: GetOptionGroupsResponse) => void
-
Response
-
返回
-
Promise<GetOptionGroupsResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getScannerList()
chrome.documentScan.getScannerList(
filter: DeviceFilter,
callback?: function,
): Promise<GetScannerListResponse>
获取可用扫描器的列表,并返回一个 Promise,该 Promise 会解析为 GetScannerListResponse
对象。如果向此函数传递了回调,则返回的数据会传递给该回调。
参数
-
filter
一个
DeviceFilter
,用于指示应返回哪些类型的扫描器。 -
callback
函数 可选
callback
参数如下所示:(response: GetScannerListResponse) => void
-
Response
-
返回
-
Promise<GetScannerListResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
openScanner()
chrome.documentScan.openScanner(
scannerId: string,
callback?: function,
): Promise<OpenScannerResponse>
打开扫描器以进行独占访问,并返回一个 Promise,该 Promise 会解析为 OpenScannerResponse
对象。如果向此函数传递了回调,则返回的数据会传递给该回调。
参数
-
scannerId
字符串
要打开的扫描器的 ID。此值是从之前对
getScannerList
的调用返回的值之一。 -
callback
函数 可选
callback
参数如下所示:(response: OpenScannerResponse) => void
-
Response
-
返回
-
Promise<OpenScannerResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
readScanData()
chrome.documentScan.readScanData(
job: string,
callback?: function,
): Promise<ReadScanDataResponse>
从有效作业句柄读取下一块可用的图片数据,并返回一个 Promise,该 Promise 会解析为 ReadScanDataResponse
对象。如果使用回调,则会将对象传递给回调。
**注意:**响应结果为 SUCCESS
且 data
成员的长度为零是有效的。这意味着扫描器仍在工作,但尚未准备好其他数据。来电者应稍等片刻,然后重试。
扫描作业完成后,响应将包含结果值 EOF
。此响应可能包含一个最终的非零 data
成员。
参数
-
作业
字符串
之前从
startScan
返回的有效作业句柄。 -
callback
函数 可选
callback
参数如下所示:(response: ReadScanDataResponse) => void
-
Response
-
返回
-
Promise<ReadScanDataResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
scan()
chrome.documentScan.scan(
options: ScanOptions,
callback?: function,
): Promise<ScanResults>
执行文档扫描,并返回一个 Promise,该 Promise 会解析为 ScanResults
对象。如果向此函数传递了回调,则返回的数据会传递给该回调。
参数
-
选项
包含扫描参数的对象。
-
callback
函数 可选
callback
参数如下所示:(result: ScanResults) => void
-
结果
-
返回
-
Promise<ScanResults>
Chrome 96 及更高版本仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setOptions()
chrome.documentScan.setOptions(
scannerHandle: string,
options: OptionSetting[],
callback?: function,
): Promise<SetOptionsResponse>
为指定扫描器设置选项,并返回一个 Promise,该 Promise 会解析为一个 SetOptionsResponse
对象,其中包含尝试按传入的 OptionSetting
对象中的顺序设置每个值的结果。如果使用回调,则会将对象传递给回调。
参数
-
scannerHandle
字符串
要设置选项的扫描器的句柄。此值应为之前从对
openScanner
的调用返回的值。 -
选项
要应用于扫描器的
OptionSetting
对象列表。 -
callback
函数 可选
callback
参数如下所示:(response: SetOptionsResponse) => void
-
Response
-
返回
-
Promise<SetOptionsResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
startScan()
chrome.documentScan.startScan(
scannerHandle: string,
options: StartScanOptions,
callback?: function,
): Promise<StartScanResponse>
在指定的扫描器上开始扫描,并返回一个 Promise,该 Promise 会解析为 StartScanResponse
。如果使用回调,则会将对象传递给回调。如果调用成功,响应会包含一个作业句柄,可在后续调用中使用该句柄来读取扫描数据或取消扫描。
参数
-
scannerHandle
字符串
打开的扫描器的句柄。此值应为之前从对
openScanner
的调用返回的值。 -
一个
StartScanOptions
对象,用于指示扫描时要使用的选项。StartScanOptions.format
属性必须与扫描器ScannerInfo
中返回的某个条目匹配。 -
callback
函数 可选
callback
参数如下所示:(response: StartScanResponse) => void
-
Response
-
返回
-
Promise<StartScanResponse>
仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。