此页面由 Cloud Translation API 翻译。

chrome.documentScan

说明

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

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

权限

documentScan

可用性

Chrome 44 及更高版本仅限 ChromeOS

对于稍后添加的 API 成员，空闲情况会随这些成员一起显示。

概念和用法

此 API 支持两种文档扫描方法。如果您的使用场景可以并且不需要控制配置，可以使用 scan() 方法结合使用。更复杂的用例需要组合使用多种方法，仅在 Chrome 124 及更高版本中受支持。

简单扫描

对于简单的应用场景，指的是能够使用任何扫描仪，需要控制配置，请调用 scan()。此方法采用 ScanOptions 对象，并返回使用 ScanResults 进行解析的 Promise 对象。此选项的功能受扫描次数和调用方将接受的 MIME 类型。扫描会以网址形式返回在界面的 <img> 标记中显示。

复杂扫描

如本部分所述，复杂扫描分三个阶段完成。本概述并未描述每个方法参数或返回的每个属性。它只是为您提供编写扫描器的一般指南代码。

发现

调用 getScannerList()。可用的扫描器为在 Promise 中返回，该 Promise 使用 GetScannerListResponse。
- 响应对象包含 ScannerInfo 数组对象的操作。
- 如果某个扫描程序符合该扫描程序的条件，则数组可以包含该扫描程序的多个条目支持多种协议或连接方法。
从返回的数组中选择扫描仪，并保存其值 scannerId 属性。

使用各个 ScannerInfo 对象的属性来区分同一扫描器的多个对象。对象来自同一个扫描器的 deviceUuid 属性值相同。 ScannerInfo 还包含一个 imageFormats 属性，该属性包含图片类型。

扫描器配置

调用 openScanner()，并传入已保存的扫描器 ID。它会返回一个使用 OpenScannerResponse 解析的 Promise。响应对象包含：
- 您需要保存一个 scannerHandle 属性。
- options 属性包含特定于扫描器的属性，您将所需的设置如需了解详情，请参阅“检索扫描器选项”。
（可选）如果您需要用户提供扫描器选项的值，构建界面您将需要然后，您需要检索由扫描程序如需了解详情，请参阅构建界面。
使用以下代码构造 OptionSetting 对象数组程序化价值或用户提供的值请参阅“设置扫描器选项”了解详情信息。
将 OptionSetting 对象数组传递给按 setOptions() 可设置扫描器选项。它它会返回使用 SetOptionsResponse。此对象包含一个在扫描器第 1 步中检索到的扫描器选项的更新版本配置。

由于更改其中一个选项可以更改另一个选项的约束条件，那么您可能需要重复这些执行多次操作。

扫描

构造一个 StartScanOptions 对象并向其传递发送至startScan()。它会返回可解析并使用 StartScanResponse。其 job 属性为将用于读取扫描数据或取消扫描的句柄。
将作业句柄传递给 readScanData()。它会返回一个使用 ReadScanDataResponse 对象。如果数据已读取则其 result 属性等于 SUCCESS 且其 data 属性包含 ArrayBuffer 包含部分扫描。请注意，estimatedCompletion 包含估算的在目前已传送的总数据中所占的百分比。

注意：如果 result 为 SUCCESS，但 data 为空，请稍等片刻，然后再重新调用 readScanData()。
重复上一步，直到 result 属性等于 EOF 或出现错误。

当扫描结束时，调用 closeScanner()（在步骤中保存了扫描器句柄） 3.它会返回一个使用 CloseScannerResponse。正在呼叫 cancelScan() 结束扫描。

响应对象

所有方法都会返回一个使用某种类型的响应对象进行解析的 promise。其中大多数都包含一个 result 属性，该属性的值是 OperationResult。响应对象的一些属性不会包含任何值，除非 result 的值具有特定值。这些各响应对象的参考文档中均对各响应类型进行了说明。

例如，OpenScannerResponse.scannerHandle 只有在满足以下条件时才会有一个值： OpenScannerResponse.result等于 SUCCESS。

扫描仪选项

扫描仪选项会因设备而异。因此，您无法直接在 documentScan API 中反映扫描器选项。出行也就是 OpenScannerResponse（使用 openScanner()）和 SetOptionsResponse（ setOptions() 包含 options 属性，该属性是对象包含特定于扫描器的选项。每个选项都是一个键值对映射，其中键是设备专用选项，值为 ScannerOption。

其结构通常如下所示：

{
  "key1": { scannerOptionInstance }
  "key2": { scannerOptionInstance }
}

例如，假设某个扫描仪会返回名为“source”的选项。和 “Resolution”。返回的 options 对象的结构大致如下所示：如下例所示。为简单起见，只有部分 ScannerOption 响应。

{
  "source": {
    "name": "source",
    "type": OptionType.STRING,
...
},
  "resolution": {
    "name": "resolution",
    "type": OptionType.INT,
...
  },
...
}

构建界面

虽然并非使用此 API 的必要条件，但您可能需要让用户自行选择特定选项这需要界面。使用 OpenScannerResponse（打开者） openScanner()) 检索扫描程序。

某些扫描仪会以设备特定方式对选项进行分组。它们不影响选项但由于扫描仪的产品中可能会提及这些群体文档，则应向用户显示此类组。您可以检索这些通过调用 getOptionGroups() 创建群组。这将返回一个使用 GetOptionGroupsResponse 对象。现在是 groups 属性包含特定于扫描程序的一组组。使用以下内容中的信息：这些组来整理 OpenScannerResponse 用于显示。

{
  scannerHandle: "123456",
  result: SUCCESS,
  groups: [
    {
      title: "Standard",
      members: [ "resolution", "mode", "source" ]
    }
  ]
}

如扫描器配置下所述，更改一个选项可能会改变限制条件另一个选项这就是为什么 setOptionsResponse（ setOptions()) 包含另一个 options 属性。使用以便更新界面然后根据需要重复操作，直到所有选项都填好。

设置扫描器选项

通过传递一个数组，以设置扫描器选项 OptionSetting 对象 setOptions()。如需查看示例，请参阅下面的扫描一个字母大小的页面部分。

示例

将页面检索为 Blob

此示例展示了一种以 Blob 的形式从扫描器检索网页的方法，演示了如何使用 startScan() 和 readScanData() OperationResult。

async function pageAsBlob(handle) {
  let response = await chrome.documentScan.startScan(
      handle, {format: "image/jpeg"});
  if (response.result != chrome.documentScan.OperationResult.SUCCESS) {
    return null;
  }
  const job = response.job;

  let imgParts = [];
  response = await chrome.documentScan.readScanData(job);
  while (response.result == chrome.documentScan.OperationResult.SUCCESS) {
    if (response.data && response.data.byteLength > 0) {
        imgParts.push(response.data);
    } else {
      // Delay so hardware can make progress.
      await new Promise(r => setTimeout(r, 100));
    }
    response = await chrome.documentScan.readScanData(job);
  }
  if (response.result != chrome.documentScan.OperationResult.EOF) {
    return null;
  }
  if (response.data && response.data.byteLength > 0) {
    imgParts.push(response.data);
  }
  return new Blob(imgParts, { type: "image/jpeg" });
}

扫描 1 个字母大小的页面

此示例展示了如何选择扫描器、设置其选项并打开扫描器。它然后检索单个页面的内容并关闭扫描器。此过程演示了如何使用 getScannerList()、openScanner()、setOptions() 和 closeScanner()。请注意，可通过调用上一个示例中的 pageAsBlob() 函数。

async function scan() {
    let response = await chrome.documentScan.getScannerList({ secure: true });
    let scanner = await chrome.documentScan.openScanner(
        response.scanners[0].scannerId);
    const handle = scanner.scannerHandle;

    let options = [];
    for (source of scanner.options["source"].constraint.list) {
        if (source.includes("ADF")) {
            options.push({
                name: "source",
                type: chrome.documentScan.OptionType.STRING,
                value: { value: source }
            });
            break;
        }
    }
    options.push({
        name: "tl-x",
        type: chrome.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-x",
        type: chrome.documentScan.OptionType.FIXED,
        value: 215.9  // 8.5" in mm
    });
    options.push({
        name: "tl-y",
        type: chrome.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-y",
        type: chrome.documentScan.OptionType.FIXED,
        value: 279.4  // 11" in mm
    });
    response = await chrome.documentScan.setOptions(handle, options);

    let imgBlob = await pageAsBlob(handle);
    if (imgBlob != null) {
        // Insert imgBlob into DOM, save to disk, etc
    }
    await chrome.documentScan.closeScanner(handle);
}

显示配置

如其他部分所述，向用户显示扫描程序的配置选项需要调用 getOptionGroups() 以及从对 openScanner() 的调用。这样，相应用户便可看到相应选项制造商定义的组以下示例展示了如何执行此操作。

async function showConfig() {
  let response = await chrome.documentScan.getScannerList({ secure: true });
  let scanner = await chrome.documentScan.openScanner(
      response.scanners[0].scannerId);
  let groups = await chrome.documentScan.getOptionGroups(scanner.scannerHandle);

  for (const group of groups.groups) {
    console.log("=== " + group.title + " ===");
    for (const member of group.members) {
      const option = scanner.options[member];
      if (option.isActive) {
        console.log("  " + option.name + " = " + option.value);
      } else {
        console.log("  " + option.name + " is inactive");
      }
    }
  }
}

类型

CancelScanResponse

Chrome 125 及更高版本

属性

作业

字符串

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

OperationResult

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

CloseScannerResponse

Chrome 125 及更高版本

属性

结果

OperationResult

关闭扫描器的结果。即使此值不是 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，则按照扫描器驱动程序提供的顺序提供选项组列表。
结果

OperationResult

获取选项组的结果。如果此值为 SUCCESS，则填充 groups 属性。
scannerHandle

字符串

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

GetScannerListResponse

Chrome 125 及更高版本

属性

结果

OperationResult

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

ScannerInfo[]

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

OpenScannerResponse

Chrome 125 及更高版本

属性

选项

对象（可选）

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

OperationResult

打开扫描器的结果。如果此值为 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

编号（选填）
分钟

编号（选填）
量化

编号（选填）
类型

ConstraintType

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() 的作业句柄。
结果

OperationResult

读取数据的结果。如果值为 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

字符串

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

OperationResult

表示设置选项的结果。

SetOptionsResponse

Chrome 125 及更高版本

属性

选项

对象（可选）

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

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

SetOptionResult[]

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

字符串

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

StartScanOptions

Chrome 125 及更高版本

属性

格式

字符串

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

编号（选填）

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

StartScanResponse

Chrome 125 及更高版本

属性

作业

字符串（可选）

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

OperationResult

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

字符串

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

方法

cancelScan()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本

chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

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

参数

作业

字符串

之前因调用 startScan 而返回的有效扫描作业的句柄。
callback

函数（可选）

callback 参数如下所示：
```
(response: CancelScanResponse) => void
```
- Response
  
  CancelScanResponse

Promise<CancelScanResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

closeScanner()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本

chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

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

参数

scannerHandle

字符串

指定之前因调用 openScanner 而返回的某个已打开扫描器的句柄。
callback

函数（可选）

callback 参数如下所示：
```
(response: CloseScannerResponse) => void
```
- Response
  
  CloseScannerResponse

Promise<CloseScannerResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getOptionGroups()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本

chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

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

参数

scannerHandle

字符串

通过调用 openScanner 返回的已打开扫描器的句柄。
callback

函数（可选）

callback 参数如下所示：
```
(response: GetOptionGroupsResponse) => void
```
- Response
  
  GetOptionGroupsResponse

Promise<GetOptionGroupsResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getScannerList()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本

chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

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

参数

filter

DeviceFilter

一个 DeviceFilter，用于指明应返回哪些类型的扫描器。
callback

函数（可选）

callback 参数如下所示：
```
(response: GetScannerListResponse) => void
```
- Response
  
  GetScannerListResponse

Promise<GetScannerListResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

openScanner()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本

chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

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

参数

scannerId

字符串

要打开的扫描仪的 ID。此值是上次调用 getScannerList 后返回的值。
callback

函数（可选）

callback 参数如下所示：
```
(response: OpenScannerResponse) => void
```
- Response
  
  OpenScannerResponse

Promise<OpenScannerResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

readScanData()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 125 及更高版本

chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

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

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

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

参数

作业

字符串

之前从 startScan 返回的有效作业句柄。
callback

函数（可选）

callback 参数如下所示：
```
(response: ReadScanDataResponse) => void
```
- Response
  
  ReadScanDataResponse

Promise<ReadScanDataResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

scan()

<ph type="x-smartling-placeholder"></ph> 承诺

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

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

参数

选项

ScanOptions

包含扫描参数的对象。
callback

函数（可选）

callback 参数如下所示：
```
(result: ScanResults) => void
```
- 结果
  
  ScanResults

Promise<ScanResults>

Chrome 96 及更高版本

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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
```
- Response
  
  SetOptionsResponse

Promise<SetOptionsResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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 对象，指示要用于扫描的选项。StartScanOptions.format 属性必须与扫描器的 ScannerInfo 中返回的某个条目匹配。
callback

函数（可选）

callback 参数如下所示：
```
(response: StartScanResponse) => void
```
- Response
  
  StartScanResponse

Promise<StartScanResponse>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。