chrome.documentScan

说明

使用 chrome.documentScan API 从连接的文档扫描仪中发现和检索图片。

权限

documentScan

可用性

Chrome 44 及更高版本 仅限 ChromeOS

Document Scan API

文档扫描 API 旨在允许应用和扩展程序查看连接的文档扫描仪上的纸质文档的内容。

类型

CancelScanResponse

Chrome 125 及更高版本

属性

  • 作业

    字符串

    提供传递给 cancelScan() 的相同作业句柄。

  • 后端的取消扫描结果。如果结果为 OperationResult.SUCCESSOperationResult.CANCELLED,则表示扫描已取消,扫描器已准备好开始新的扫描。如果结果为 OperationResult.DEVICE_BUSY,则扫描器仍在处理请求的取消操作;调用者应等待一小段时间,然后再次尝试该请求。其他结果值表示不应重试的永久性错误。

CloseScannerResponse

Chrome 125 及更高版本

属性

  • 关闭扫描器的结果。即使此值不是 SUCCESS,句柄也会无效,不应将其用于任何进一步的操作。

  • scannerHandle

    字符串

    与传递给 closeScanner 的扫描器句柄相同。

Configurability

Chrome 125 及更高版本

如何更改选项。

枚举

“NOT_CONFIGURABLE”
相应选项为只读。

“SOFTWARE_CONFIGURABLE”
该选项可在软件中设置。

“HARDWARE_CONFIGURABLE”
用户可以通过切换扫描器上的按钮来设置此选项。

ConnectionType

Chrome 125 及更高版本

指示扫描器与计算机的连接方式。

枚举

"UNSPECIFIED"

“USB”

"NETWORK"

ConstraintType

Chrome 125 及更高版本

OptionConstraint 表示的限制条件的数据类型。

枚举

“INT_RANGE”
对一系列 OptionType.INT 值的限制。OptionConstraintminmaxquant 属性将为 long,而其 list 属性将处于未设置状态。

“FIXED_RANGE”
对一系列 OptionType.FIXED 值的限制。OptionConstraintminmaxquant 属性将为 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[] 可选

    如果 resultSUCCESS,则提供扫描器驱动程序提供的选项组列表(按顺序)。

  • 获取选项组的结果。如果此属性的值为 SUCCESS,系统将填充 groups 属性。

  • scannerHandle

    字符串

    与传递给 getOptionGroups 的扫描器句柄相同。

GetScannerListResponse

Chrome 125 及更高版本

属性

  • 枚举结果。请注意,即使此值指示存在错误,也可能会返回部分结果。

  • 扫描仪

    与所提供的 DeviceFilter 相匹配的扫描器列表(可能为空)。

OpenScannerResponse

Chrome 125 及更高版本

属性

  • 选项

    对象(可选)

    如果 resultSUCCESS,则提供键值映射,其中键是设备专用选项,值是 ScannerOption 的实例。

  • 打开扫描器的结果。如果此属性的值为 SUCCESS,则系统会填充 scannerHandleoptions 属性。

  • scannerHandle

    字符串(选填)

    如果 resultSUCCESS,则表示扫描器的句柄,可用于进一步操作。

  • scannerId

    字符串

    传递给 openScanner() 的扫描器 ID。

OperationResult

Chrome 125 及更高版本

一种枚举,用于指示每项操作的结果。

枚举

“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

Chrome 125 及更高版本

属性

  • list

    string[] | number[] 可选

  • max

    number 可选

  • 分钟

    number 可选

  • quant

    number 可选

OptionGroup

Chrome 125 及更高版本

属性

  • 成员

    字符串[]

    驱动程序提供的顺序中的选项名称数组。

  • title

    字符串

    提供可打印的标题,例如“几何图形选项”。

OptionSetting

Chrome 125 及更高版本

属性

  • name

    字符串

    指明要设置的选项的名称。

  • 类型

    表示选项的数据类型。所请求的数据类型必须与底层选项的实际数据类型相匹配。

  • 字符串 | 数值 | 布尔值 | 数值数组 可选

    表示要设置的值。如果将此字段留空,系统将自动为已启用 autoSettable 的选项设置值。为 value 提供的数据类型必须与 type 一致。

OptionType

Chrome 125 及更高版本

选项的数据类型。

枚举

“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() 可检索包含成员选项的群组列表。

OptionUnit

Chrome 125 及更高版本

指明 ScannerOption.unit 的数据类型。

枚举

“UNITLESS”
相应值是一个无单位的数字。例如,它可以是阈值。

“PIXEL”
该值是像素数,例如扫描尺寸。

“位”
该值是位数,例如颜色深度。

“MM”
该值以毫米为单位,例如扫描尺寸。

“DPI”
该值以每英寸的点数(例如分辨率)为单位进行衡量。

“PERCENT”
值是百分比,例如亮度。

“MICROSECOND”
该值以微秒为单位,例如曝光时间。

ReadScanDataResponse

Chrome 125 及更高版本

属性

  • 数据

    ArrayBuffer 可选

    如果 resultSUCCESS,则包含扫描的图片数据的下一个块。如果 resultEOF,则包含扫描的图片数据的最后一块。

  • estimatedCompletion

    number 可选

    如果 resultSUCCESS,则表示到目前为止已传送的扫描数据占总扫描数据的百分比估计值,范围为 0 到 100。

  • 作业

    字符串

    提供传递给 readScanData() 的作业句柄。

  • 读取数据的结果。如果其值为 SUCCESS,则 data 包含准备好读取的下一个(可能为零长度)图片数据块。如果其值为 EOF,则 data 包含图像数据的最后一个块。

ScannerInfo

Chrome 125 及更高版本

属性

  • connectionType

    指示扫描器与计算机的连接方式。

  • deviceUuid

    字符串

    用于与其他指向同一物理设备的 ScannerInfo 条目进行匹配。

  • imageFormats

    字符串[]

    可为返回的扫描结果请求的 MIME 类型数组。

  • 制造商

    字符串

    扫描器制造商。

  • 模型

    字符串

    扫描器型号(如果有)或一般说明。

  • name

    字符串

    扫描器在界面中显示的直观易懂的名称。

  • protocolType

    字符串

    用于访问扫描仪的协议或驱动程序的人类可读说明,例如 Mopria、WSD 或 epsonds。如果设备支持多种协议,此属性主要用于允许用户在这些协议之间进行选择。

  • scannerId

    字符串

    特定扫描器的 ID。

  • 安全

    布尔值

    如果为 true,扫描器连接的传输无法被被动监听器(例如 TLS 或 USB)拦截。

ScannerOption

Chrome 125 及更高版本

属性

  • 可配置性

    指示相应选项是否可以更改以及如何更改。

  • 项限制条件

    在当前扫描器选项上定义 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

Chrome 125 及更高版本

属性

  • name

    字符串

    指明所设置选项的名称。

  • 指示设置选项的结果。

SetOptionsResponse

Chrome 125 及更高版本

属性

  • 选项

    对象(可选)

    一个更新后的键值映射,其中包含从选项名称到 ScannerOption 值的映射,这些值包含尝试设置所有提供的选项后的新配置。此属性的结构与 OpenScannerResponse 中的 options 属性相同。

    即使某些选项未成功设置,系统也会设置此属性;但如果检索更新后的配置失败(例如,扫描器在扫描过程中断开连接),系统将取消设置此属性。

  • 结果

    一个结果数组,每个传入的 OptionSetting 对应一个结果。

  • scannerHandle

    字符串

    提供传递给 setOptions() 的扫描器句柄。

StartScanOptions

Chrome 125 及更高版本

属性

  • 格式

    字符串

    指定返回扫描数据的 MIME 类型。

  • maxReadSize

    number 可选

    如果指定了非零值,则将单个 readScanData 响应中返回的最大扫描字节数限制为该值。允许的最小值是 32768(32 KB)。如果未指定此属性,则返回的块的大小可能与整个扫描的图片一样大。

StartScanResponse

Chrome 125 及更高版本

属性

  • 作业

    字符串(选填)

    如果 resultSUCCESS,则提供可用于读取扫描数据或取消作业的句柄。

  • 启动扫描的结果。如果此属性的值为 SUCCESS,系统将填充 job 属性。

  • scannerHandle

    字符串

    提供传递给 startScan() 的相同扫描器句柄。

方法

cancelScan()

Promise Chrome 125 及更高版本
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)
: Promise<CancelScanResponse>

取消已开始的扫描,并返回一个 Promise,该 Promise 会解析为 CancelScanResponse 对象。如果使用回调,则会将对象传递给回调。

参数

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

closeScanner()

Promise Chrome 125 及更高版本
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)
: Promise<CloseScannerResponse>

使用传入的句柄关闭扫描器,并返回一个 Promise,该 Promise 会解析为 CloseScannerResponse 对象。如果使用回调,则会将对象传递给回调。即使响应不成功,所提供的句柄也会失效,不应再用于后续操作。

参数

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

getOptionGroups()

Promise Chrome 125 及更高版本
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)
: Promise<GetOptionGroupsResponse>

从之前通过 openScanner 打开的扫描器获取群组名称和成员选项。此方法会返回一个 Promise,该 Promise 会解析为一个 GetOptionGroupsResponse 对象。如果向此函数传递了回调,则返回的数据会传递给该回调。

参数

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

getScannerList()

Promise Chrome 125 及更高版本
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)
: Promise<GetScannerListResponse>

获取可用扫描器的列表,并返回一个 Promise,该 Promise 会解析为 GetScannerListResponse 对象。如果向此函数传递了回调,则返回的数据会传递给该回调。

参数

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

openScanner()

Promise Chrome 125 及更高版本
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)
: Promise<OpenScannerResponse>

打开扫描器以进行独占访问,并返回一个 Promise,该 Promise 会解析为 OpenScannerResponse 对象。如果向此函数传递了回调,则返回的数据会传递给该回调。

参数

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

readScanData()

Promise Chrome 125 及更高版本
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)
: Promise<ReadScanDataResponse>

从有效作业句柄读取下一块可用的图片数据,并返回一个 Promise,该 Promise 会解析为 ReadScanDataResponse 对象。如果使用回调,则会将对象传递给回调。

**注意:**响应结果为 SUCCESSdata 成员的长度为零是有效的。这意味着扫描器仍在工作,但尚未准备好其他数据。来电者应稍等片刻,然后重试。

扫描作业完成后,响应将包含结果值 EOF。此响应可能包含一个最终的非零 data 成员。

参数

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

scan()

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

执行文档扫描,并返回一个 Promise,该 Promise 会解析为 ScanResults 对象。如果向此函数传递了回调,则返回的数据会传递给该回调。

参数

返回

  • Promise<ScanResults>

    Chrome 96 及更高版本

    仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

setOptions()

Promise Chrome 125 及更高版本
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
)
: Promise<SetOptionsResponse>

为指定扫描器设置选项,并返回一个 Promise,该 Promise 会解析为一个 SetOptionsResponse 对象,其中包含尝试按传入的 OptionSetting 对象中的顺序设置每个值的结果。如果使用回调,则会将对象传递给回调。

参数

  • scannerHandle

    字符串

    要设置选项的扫描器的句柄。此值应为之前从对 openScanner 的调用返回的值。

  • 选项

    要应用于扫描器的 OptionSetting 对象列表。

  • callback

    函数 可选

    callback 参数如下所示:

    (response: SetOptionsResponse) => void

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

startScan()

Promise Chrome 125 及更高版本
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

返回

  • 仅 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。