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