refresh date: 2026-09-25 robots: noindex
说明
使用 chrome.documentScan API 从连接的文件扫描器中发现和检索图片。
权限
documentScan可用性
Document Scan 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
指明扫描仪与计算机的连接方式。
枚举
"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"
操作成功。
“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
number 可选
-
分钟
number 可选
-
数量
number 可选
OptionGroup
属性
-
成员
字符串[]
按驱动程序提供的顺序排列的选项名称数组。
-
title
字符串
提供可打印的标题，例如“几何图形选项”。
OptionSetting
属性
-
name
字符串
指明要设置的选项的名称。
-
类型
指示选项的数据类型。请求的数据类型必须与底层选项的实际数据类型一致。
-
值
字符串 | 数字 | 布尔值 | 数字 [] （可选）
指明要设置的值。如果未设置，则系统会为已启用
autoSettable的选项请求自动设置。为value提供的数据类型必须与type匹配。
OptionType
选项的数据类型。
枚举
"UNKNOWN"
选项的数据类型未知。value 属性将被取消设置。
"BOOL"
value 属性将为 truefalse。
“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
属性
-
数据
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>
取消已启动的扫描，并返回一个使用 CancelScanResponse 对象解析的 Promise。如果使用回调，则会将对象传递给回调。
参数
-
作业
字符串
之前通过调用
startScan返回的活跃扫描作业的句柄。 -
callback
函数可选
callback参数如下所示：(response: CancelScanResponse) => void
-
Response
-
返回
-
Promise<CancelScanResponse>
返回一个 Promise，该 Promise 会解析结果。
只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
closeScanner()
chrome.documentScan.closeScanner(
scannerHandle: string,
callback?: function,
): Promise<CloseScannerResponse>
使用传入的句柄关闭扫描器，并返回一个使用 CloseScannerResponse 对象解析的 Promise。如果使用回调，则对象会改为传递给回调。即使响应不成功，提供的句柄也会失效，不应再用于后续操作。
参数
-
scannerHandle
字符串
指定之前通过调用
openScanner返回的打开扫描器的句柄。 -
callback
函数可选
callback参数如下所示：(response: CloseScannerResponse) => void
-
Response
-
返回
-
Promise<CloseScannerResponse>
返回一个 Promise，该 Promise 会解析结果。
只有 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>
返回一个 Promise，该 Promise 会解析结果。
只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
getScannerList()
chrome.documentScan.getScannerList(
filter: DeviceFilter,
callback?: function,
): Promise<GetScannerListResponse>
获取可用扫描仪的列表，并返回一个使用 GetScannerListResponse 对象进行解析的 Promise。如果向此函数传递了回调，则返回的数据会传递给该回调。
参数
-
过滤条件
一个
DeviceFilter，用于指示应返回哪些类型的扫描器。 -
callback
函数可选
callback参数如下所示：(response: GetScannerListResponse) => void
-
Response
-
返回
-
Promise<GetScannerListResponse>
返回一个 Promise，该 Promise 会解析为结果和扫描器列表。
只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
openScanner()
chrome.documentScan.openScanner(
scannerId: string,
callback?: function,
): Promise<OpenScannerResponse>
打开扫描器以进行独占访问，并返回一个使用 OpenScannerResponse 对象解析的 Promise。如果向此函数传递了回调，则返回的数据会传递给该回调。
参数
-
scannerId
字符串
要打开的扫描器的 ID。此值是之前调用
getScannerList时返回的值。 -
callback
函数可选
callback参数如下所示：(response: OpenScannerResponse) => void
-
Response
-
返回
-
Promise<OpenScannerResponse>
返回一个 Promise，该 Promise 会解析结果。
只有 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>
返回一个 Promise，该 Promise 会解析结果。
只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
scan()
chrome.documentScan.scan(
options: ScanOptions,
callback?: function,
): Promise<ScanResults>
执行文档扫描，并返回一个解析为 ScanResults 对象的 Promise。如果向此函数传递了回调，则返回的数据会传递给该回调。
参数
-
选项
包含扫描参数的对象。
-
callback
函数可选
callback参数如下所示：(result: ScanResults) => void
-
结果
-
返回
-
Promise<ScanResults>
Chrome 96 及更高版本返回一个 Promise，该 Promise 会解析为扫描结果。
只有 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>
返回一个 Promise，该 Promise 会解析结果。
只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
startScan()
chrome.documentScan.startScan(
scannerHandle: string,
options: StartScanOptions,
callback?: function,
): Promise<StartScanResponse>
在指定的扫描仪上启动扫描，并返回一个使用 StartScanResponse 解析的 Promise。如果使用回调，则对象会改为传递给回调。如果调用成功，响应中会包含一个作业句柄，可在后续调用中用于读取扫描数据或取消扫描。
参数
-
scannerHandle
字符串
打开的扫描器的句柄。这应该是之前调用
openScanner返回的值。 -
一个
StartScanOptions对象，用于指示扫描时要使用的选项。StartScanOptions.format属性必须与扫描器的ScannerInfo中返回的某个条目匹配。 -
callback
函数可选
callback参数如下所示：(response: StartScanResponse) => void
-
Response
-
返回
-
Promise<StartScanResponse>
返回一个 Promise，该 Promise 会解析结果。
只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。