chrome.documentScan

说明

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

权限

documentScan

可用性

Chrome 44 及更高版本 仅限 ChromeOS

Document Scan API

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

类型

CancelScanResponse

Chrome 125 及更高版本

属性

  • 作业

    字符串

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

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

CloseScannerResponse

Chrome 125 及更高版本

属性

  • 关闭扫描器的结果。即使此值不是 SUCCESS，该句柄也无效，不得用于任何进一步的操作。

  • scannerHandle

    字符串

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

Configurability

Chrome 125 及更高版本

如何更改选项。

枚举

"NOT_CONFIGURABLE"
此选项是只读的。

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

"HARDWARE_CONFIGURABLE"
此选项可由用户切换或按下扫描仪上的相应按钮设置。

ConnectionType

Chrome 125 及更高版本

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

枚举

"未指定"

“USB”

“NETWORK”

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

    字符串

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

GetScannerListResponse

Chrome 125 及更高版本

属性

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

  • 扫描仪

    ScannerInfo[]

    与提供的 DeviceFilter 匹配的扫描器列表（可能为空）。

OpenScannerResponse

Chrome 125 及更高版本

属性

  • 选项

    对象（可选）

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

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

  • scannerHandle

    字符串（可选）

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

  • scannerId

    字符串

    传递给 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[]（选填）

  • max

    编号（选填）

  • 分钟

    编号（选填）

  • 量化

    编号（选填）

OptionGroup

Chrome 125 及更高版本

属性

  • 成员

    字符串[]

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

  • 标题

    字符串

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

OptionSetting

Chrome 125 及更高版本

属性

  • name

    字符串

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

  • 类型

    OptionType

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

  • 值

    string |数字 |boolean |number[]（选填）

    指示要设置的值。如果未设置此政策，系统会为已启用 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 及更高版本

属性

  • 数据

    ArrayBuffer 可选

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

  • estimatedCompletion

    编号（选填）

    如果 result 为 SUCCESS，则表示到目前为止已传送总扫描数据量的估算值，范围为 0 到 100。

  • 作业

    字符串

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

  • 读取数据的结果。如果值为 SUCCESS，则 data 包含可供读取的下一个图像数据块（可能长度为零）。如果值为 EOF，则 data 包含图像数据的最后一个块。

ScannerInfo

Chrome 125 及更高版本

属性

  • connectionType

    ConnectionType

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

  • deviceUuid

    字符串

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

  • imageFormats

    字符串[]

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

  • 制造商

    字符串

    扫描仪制造商。

  • 模型

    字符串

    扫描器型号（如果有），或通用说明。

  • name

    字符串

    显示在界面中的扫描器的人类可读名称。

  • protocolType

    字符串

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

  • scannerId

    字符串

    特定扫描器的 ID。

  • 安全

    布尔值

    如果为 true，则被动监听器（如 TLS 或 USB）无法拦截扫描器连接的传输。

ScannerOption

Chrome 125 及更高版本

属性

  • 可配置性

    可配置性

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

  • 项限制条件

    OptionConstraint 可选

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

  • 说明

    字符串

    选项的较长说明。

  • isActive

    布尔值

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

  • isAdvanced

    布尔值

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

  • isAutoSettable

    布尔值

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

  • isDetectable

    布尔值

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

  • isEmulated

    布尔值

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

  • name

    字符串

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

  • 标题

    字符串

    可打印的单行标题。

  • 类型

    OptionType

    value 属性中包含的数据类型，设置此选项时需要使用该属性。

  • 单位

    OptionUnit

    此选项的计量单位。

  • 值

    string |数字 |boolean |number[]（选填）

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

ScanOptions

属性

  • maxImages

    编号（选填）

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

  • mimeTypes

    string[] 选填

    调用方接受的 MIME 类型。

ScanResults

属性

  • dataUrls

    字符串[]

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

  • mimeType

    字符串

    dataUrls 的 MIME 类型。

SetOptionResult

Chrome 125 及更高版本

属性

  • name

    字符串

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

  • 表示设置选项的结果。

SetOptionsResponse

Chrome 125 及更高版本

属性

  • 选项

    对象（可选）

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

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

  • 结果

    SetOptionResult[]

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

  • scannerHandle

    字符串

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

StartScanOptions

Chrome 125 及更高版本

属性

  • 格式

    字符串

    指定要在其中返回扫描数据的 MIME 类型。

  • maxReadSize

    编号（选填）

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

StartScanResponse

Chrome 125 及更高版本

属性

  • 作业

    字符串（可选）

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

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

  • scannerHandle

    字符串

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

方法

cancelScan()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

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

参数

返回

  • Promise&lt;CancelScanResponse&gt;

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

closeScanner()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

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

参数

返回

  • Promise&lt;CloseScannerResponse&gt;

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

getOptionGroups()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

从 openScanner 之前打开的扫描仪获取群组名称和成员选项。此方法会返回使用 GetOptionGroupsResponse 对象进行解析的 Promise。如果向此函数传递了回调，则系统将改为向其传递返回的数据。

参数

返回

  • Promise&lt;GetOptionGroupsResponse&gt;

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

getScannerList()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

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

参数

返回

  • Promise&lt;GetScannerListResponse&gt;

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

openScanner()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

打开独占访问扫描程序，并返回使用 OpenScannerResponse 对象解析的 Promise。如果向此函数传递了回调，则系统将改为向其传递返回的数据。

参数

返回

  • Promise&lt;OpenScannerResponse&gt;

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

readScanData()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

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

**注意：**响应结果为 SUCCESS 且 data 成员长度为零的情况是有效的。这意味着扫描器仍在运行，但尚未准备好其他数据。调用方应等待一小段时间，然后重试。

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

参数

返回

  • Promise&lt;ReadScanDataResponse&gt;

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

scan()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.documentScan.scan(
  options: ScanOptions,
  callback?: function,
)

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

参数

返回

  • Promise&lt;ScanResults&gt;

    Chrome 96 及更高版本

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

setOptions()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
)

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

参数

  • scannerHandle

    字符串

    要设置选项的扫描仪的手柄。此值应该是之前通过调用 openScanner 返回的值。

  • 选项

    OptionSetting[]

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (response: SetOptionsResponse) => void

返回

  • Promise&lt;SetOptionsResponse&gt;

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

startScan()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

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

参数

  • scannerHandle

    字符串

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

  • StartScanOptions 对象，指示要用于扫描的选项。StartScanOptions.format 属性必须与扫描器的 ScannerInfo 中返回的某个条目匹配。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (response: StartScanResponse) => void

返回

  • Promise&lt;StartScanResponse&gt;

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