chrome.documentScan

说明

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

权限

documentScan

可用性

Chrome 44 及更高版本 仅限 ChromeOS

文档扫描 API

Document Scan API 旨在让应用和扩展程序在附加的文件扫描器上查看纸质文档的内容。

类型

CancelScanResponse

Chrome 125 及更高版本

属性

  • 作业

    string

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

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

CloseScannerResponse

Chrome 125 及更高版本

属性

  • 关闭扫描程序的结果。即使此值不是 SUCCESS，句柄也无效，并且不应将其用于任何其他操作。

  • scannerHandle

    string

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

Configurability

Chrome 125 及更高版本

如何更改选项。

枚举

"NOT_CONFIGURABLE"
此选项为只读。

"SOFTWARE_CONFIGURABLE"
可以在软件中设置此选项。

"HARDWARE_CONFIGURABLE"
用户可通过切换或按下扫描仪上的按钮来设置此选项。

ConnectionType

Chrome 125 及更高版本

指示扫描仪与计算机之间的连接方式。

枚举

"UNSPECIFIED"

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

属性

  • 局部

    布尔值 选填

    仅退回直接连接到计算机的扫描仪。

  • 安全

    布尔值 选填

    仅返回使用安全传输（如 USB 或 TLS）的扫描仪。

GetOptionGroupsResponse

Chrome 125 及更高版本

属性

  • 组

    OptionGroup[] 可选

    如果 result 为 SUCCESS，则按照扫描程序驱动程序指定的顺序提供选项组列表。

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

  • scannerHandle

    string

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

GetScannerListResponse

Chrome 125 及更高版本

属性

  • 枚举结果。请注意，即使这表示存在错误，也可能返回部分结果。

  • 扫描仪

    ScannerInfo[]

    与提供的 DeviceFilter 匹配的扫描程序列表，该列表可能为空。

OpenScannerResponse

Chrome 125 及更高版本

属性

  • 选项

    对象（可选）

    如果 result 为 SUCCESS，则提供键值对映射，其中键是设备专属选项，值为 ScannerOption 的实例。

  • 打开扫描程序的结果。如果此值为 SUCCESS，系统将会填充 scannerHandle 和 options 属性。

  • scannerHandle

    字符串（可选）

    如果 result 为 SUCCESS，则为扫描器的句柄，可用于进一步操作。

  • scannerId

    string

    传递给 openScanner() 的扫描程序 ID。

OperationResult

Chrome 125 及更高版本

指示每个操作的结果的枚举。

枚举

"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

Chrome 125 及更高版本

属性

  • list

    string[]|number[] optional

  • max

    数字可选

  • 分钟

    数字可选

  • 定量

    数字可选

OptionGroup

Chrome 125 及更高版本

属性

  • 成员

    字符串[]

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

  • title

    string

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

OptionSetting

Chrome 125 及更高版本

属性

  • name

    string

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

  • 类型

    OptionType

    表示选项的数据类型。请求的数据类型必须与底层选项的实际数据类型一致。

  • 值

    string|number|boolean|number[] optional

    指示要设置的值。如果未设置，系统会请求自动设置已启用 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"
该值是一个像素数，例如扫描尺寸。

"BIT"
该值是位数，例如色深。

"MM"
该值以毫米为单位，例如扫描尺寸。

"DPI"
该值以每英寸的点数为单位，例如分辨率。

"PERCENT"
该值是一个百分比，例如亮度。

"MICROSECOND"
该值以微秒为单位，例如曝光时间。

ReadScanDataResponse

Chrome 125 及更高版本

属性

  • data

    ArrayBuffer 可选

    如果 result 为 SUCCESS，则包含扫描图片数据的下一个分块。如果 result 为 EOF，则包含扫描图片数据的最后一个块。

  • estimatedCompletion

    数字可选

    如果 result 为 SUCCESS，则表示目前已传送了多少总扫描数据（范围为 0 到 100）。

  • 作业

    string

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

  • 读取数据的结果。如果此字段的值为 SUCCESS，则 data 包含已准备好读取的下一个（长度可能为零）图片数据块。如果其值为 EOF，则 data 包含图像数据的最后一个块。

ScannerInfo

Chrome 125 及更高版本

属性

  • connectionType

    ConnectionType

    指示扫描仪与计算机之间的连接方式。

  • deviceUuid

    string

    用于匹配指向同一实体设备的其他 ScannerInfo 条目。

  • imageFormats

    字符串[]

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

  • 制造商

    string

    扫描仪制造商。

  • model

    string

    扫描仪型号（如果有），或一般性说明。

  • name

    string

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

  • protocolType

    string

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

  • scannerId

    string

    特定扫描程序的 ID。

  • 安全

    boolean

    如果为 true，扫描程序连接的传输不会被被动监听器（如 TLS 或 USB）拦截。

ScannerOption

Chrome 125 及更高版本

属性

  • 可配置性

    可配置性

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

  • 项限制条件

    OptionConstraint 可选

    定义当前扫描器选项的 OptionConstraint。

  • 说明

    string

    选项的详细描述。

  • isActive

    boolean

    表示选项有效，可以设置或检索。如果为 false，则将不会设置 value 属性。

  • isAdvanced

    boolean

    表示默认情况下界面不应显示此选项。

  • isAutoSettable

    boolean

    可由扫描仪驱动程序自动设置。

  • isDetectable

    boolean

    表示可以从软件中检测到此选项。

  • isEmulated

    boolean

    如果为 true，则由扫描器驱动程序进行模拟。

  • name

    string

    使用小写 ASCII 字母、数字和短划线的选项名称。不允许使用变音符号。

  • title

    string

    可打印的单行标题。

  • 类型

    OptionType

    value 属性中包含的数据类型，是设置此选项所需的类型。

  • 单位

    OptionUnit

    此选项的衡量单位。

  • 值

    string|number|boolean|number[] optional

    选项的当前值（如果相关）。请注意，此属性的数据类型必须与 type 中指定的数据类型一致。

ScanOptions

属性

  • maxImages

    数字可选

    允许的扫描图片数量。默认值为 1。

  • mimeTypes

    string[] 可选

    调用方接受的 MIME 类型。

ScanResults

属性

  • dataUrls

    字符串[]

    数据图片网址数组，采用的形式可作为“src”值传递给图片代码。

  • mimeType

    string

    dataUrls 的 MIME 类型。

SetOptionResult

Chrome 125 及更高版本

属性

  • name

    string

    表示已设置的选项的名称。

  • 表示设置选项的结果。

SetOptionsResponse

Chrome 125 及更高版本

属性

  • 选项

    对象（可选）

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

    即使某些选项设置失败，系统也会设置此属性；但如果无法检索更新后的配置（例如，如果扫描仪在扫描过程中断开连接），则该属性将取消设置。

  • 结果

    SetOptionResult[]

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

  • scannerHandle

    string

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

StartScanOptions

Chrome 125 及更高版本

属性

  • 格式

    string

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

  • maxReadSize

    数字可选

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

StartScanResponse

Chrome 125 及更高版本

属性

  • 作业

    字符串（可选）

    如果 result 为 SUCCESS，则提供一个可用于读取扫描数据或取消作业的句柄。

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

  • scannerHandle

    string

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

方法

cancelScan()

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

取消已启动的扫描，并返回使用 CancelScanResponse 对象解析的 Promise。如果使用回调，则改为向其传递该对象。

参数

返回

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

closeScanner()

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

使用传入的句柄关闭扫描器，并返回使用 CloseScannerResponse 对象解析的 Promise。如果使用回调，则改为向其传递该对象。即使响应不成功，提供的句柄也会变为无效，并且不应用于进一步的操作。

参数

返回

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

getOptionGroups()

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

从 openScanner 之前打开的扫描器获取群组名称和成员选项。此方法会返回使用 GetOptionGroupsResponse 对象解析的 promise。如果将回调函数传递给此函数，则返回的数据会改为传递给此函数。

参数

返回

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

getScannerList()

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

获取可用扫描器的列表，并返回使用 GetScannerListResponse 对象解析的 Promise。如果将回调函数传递给此函数，则返回的数据会改为传递给此函数。

参数

返回

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

openScanner()

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

打开独家访问扫描器，并返回使用 OpenScannerResponse 对象解析的 Promise。如果将回调函数传递给此函数，则返回的数据会改为传递给此函数。

参数

返回

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

readScanData()

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

从活跃的作业句柄中读取下一个可用图片数据块，并返回使用 ReadScanDataResponse 对象解析的 Promise。如果使用回调，则改为向其传递该对象。

**注意：**包含长度为零的 data 成员的响应结果 SUCCESS 有效。这意味着扫描仪仍在运行，但尚未准备好其他数据。调用方应稍等片刻，然后重试。

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

参数

返回

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

scan()

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

执行文档扫描，并返回使用 ScanResults 对象解析的 Promise。如果将回调函数传递给此函数，则返回的数据会改为传递给此函数。

参数

返回

  • Promise<ScanResults>

    Chrome 96 及更高版本

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

setOptions()

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

在指定的扫描器上设置选项，并返回通过 SetOptionsResponse 对象进行解析的 Promise，该对象包含尝试按传入 OptionSetting 对象的顺序设置每个值的结果。如果使用回调，则改为向其传递该对象。

参数

  • scannerHandle

    string

    要设置选项的扫描器的手柄。这应该是之前调用 openScanner 返回的值。

  • 选项

    OptionSetting[]

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (response: SetOptionsResponse)=>void

返回

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

startScan()

Promise Chrome 125 及更高版本 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

在指定的扫描器上启动扫描，并返回使用 StartScanResponse 解析的 Promise。如果使用回调，则改为向其传递该对象。如果调用成功，响应将包含一个作业句柄，该作业句柄可用于后续调用，以读取扫描数据或取消扫描。

参数

  • scannerHandle

    string

    打开的扫描仪的手柄。这应该是之前调用 openScanner 返回的值。

  • 指示用于扫描的选项的 StartScanOptions 对象。StartScanOptions.format 属性必须与扫描程序的 ScannerInfo 中返回的条目之一匹配。

  • callback

    函数（可选）

    callback 参数如下所示：

    (response: StartScanResponse)=>void

返回

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