chrome.documentScan

说明

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

Document Scan API 旨在让应用和扩展程序能够查看连接到文档扫描仪上的纸质文档的内容。

权限

documentScan

可用性

Chrome 44 及更高版本 仅限 ChromeOS
稍后添加的 API 成员的播出信息会随这些成员一起显示。

概念和用法

此 API 支持两种扫描证件的方式。如果您的用例可以与任何扫描器搭配使用，并且不需要控制配置，请使用 scan() 方法。更复杂的用例需要结合使用多种方法，而这些方法仅在 Chrome 124 及更高版本中受支持。

简单扫描

对于简单用例（即可以与任何扫描器搭配使用且不需要控制配置的用例），请调用 scan()。此方法接受 ScanOptions 对象，并返回一个使用 ScanResults 对象进行解析的 Promise。此选项的功能仅限于扫描次数和调用方接受的 MIME 类型。扫描结果会以网址的形式返回，以便在界面的 <img> 标记中显示。

复杂扫描

复杂扫描分为三个阶段完成，如本部分所述。此大纲未介绍响应中返回的每种方法参数或每个属性。本文仅旨在为您提供编写扫描器代码的一般性指南。

发现

  1. 调用 getScannerList()。可用扫描器会以一个 promise 的形式返回，该 promise 会解析为 GetScannerListResponse。

    • 响应对象包含一个 ScannerInfo 对象数组。
    • 如果扫描器支持多个协议或连接方法，该数组可能会包含单个扫描器的多个条目。

  2. 从返回的数组中选择一个扫描器，并保存其 scannerId 属性的值。

    使用各个 ScannerInfo 对象的属性来区分同一扫描器的多个对象。来自同一扫描器的对象的 deviceUuid 属性将具有相同的值。ScannerInfo 还包含一个 imageFormats 属性，其中包含一个支持的图片类型数组。

扫描器配置

  1. 调用 openScanner()，并传入已保存的扫描器 ID。它会返回一个 promise，由 OpenScannerResponse 来解析。响应对象包含：

    • scannerHandle 属性，您需要保存此属性。

    • 一个 options 属性，其中包含您需要设置的特定于扫描器的属性。如需了解详情，请参阅检索扫描器选项。

  2. （可选）如果您需要用户为扫描器选项提供值，请构建界面。您需要上一步提供的扫描器选项，并且需要检索扫描器提供的选项组。如需了解详情，请参阅构建界面。

  3. 使用程序化值或用户提供的值构建 OptionSetting 对象数组。如需了解详情，请参阅“设置扫描器选项”。

  4. 将 OptionSetting 对象数组传递给 setOptions()，以设置扫描器的选项。它会返回一个 promise，该 promise 会解析为 SetOptionsResponse。此对象包含在扫描器配置的步骤 1 中检索到的扫描器选项的更新版本。

    由于更改一个选项可能会改变另一个选项的约束条件，因此您可能需要重复这些步骤多次。

扫描

  1. 构造一个 StartScanOptions 对象，并将其传递给 startScan()。它会返回一个使用 StartScanResponse 进行解析的 Promise。其 job 属性是一个句柄，您可以使用该句柄来读取扫描数据或取消扫描。

  2. 将作业句柄传递给 readScanData()。它会返回一个 promise，由 ReadScanDataResponse 对象来解析。如果成功读取数据，其 result 属性等于 SUCCESS，其 data 属性包含包含部分扫描内容的 ArrayBuffer。请注意，estimatedCompletion 包含已提交总数据量的估算百分比。

  3. 重复上一步，直到 result 属性等于 EOF 或错误。

扫描结束时，使用第 3 步中保存的扫描器句柄调用 closeScanner()。它会返回一个 promise，由 CloseScannerResponse 来解析。在作业创建后，任何时候调用 cancelScan() 都会结束扫描。

响应对象

所有方法都会返回一个 promise，该 promise 会解析为某种类型的响应对象。其中大多数都包含一个 result 属性，其值是 OperationResult 的成员。除非 result 的值具有特定值，否则响应对象的某些属性将不包含值。每个响应对象的参考文档中都介绍了这些关系。

例如，只有当 OpenScannerResponse.result 等于 SUCCESS 时，OpenScannerResponse.scannerHandle 才会有值。

扫描器选项

扫描器选项因设备而异。因此，无法直接在 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() 检索这些组。这将返回一个 promise，由 GetOptionGroupsResponse 对象来解析。其 groups 属性包含特定于扫描器的组数组。使用这些组中的信息整理 OpenScannerResponse 中的选项以进行显示。

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

如“扫描器配置”部分所述，更改一个选项可能会改变另一个选项的约束条件。这就是为什么 setOptionsResponse（setOptions() 的响应对象）包含另一个 options 属性的原因。您可以使用此方法更新界面。然后，根据需要重复上述步骤，直到设置完所有选项。

设置扫描器选项

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

示例

以 Blob 的形式检索页面

此示例展示了以 Blob 的形式从扫描器检索页面的方法之一，并演示了使用 OperationResult 的值使用 startScan() 和 readScanData()。

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" });
}

扫描一张信纸大小的页面

此示例展示了如何选择扫描器、设置其选项并打开它。然后，它会检索单个网页的内容并关闭扫描器。此过程演示了如何使用 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);
}

显示配置

如前所述，除了从对 openScanner() 的调用返回的扫描器选项之外，还需要调用 getOptionGroups() 才能向用户显示扫描器的配置选项。这样，系统就可以向制造商定义的群组中的用户显示选项。以下示例展示了如何执行此操作。

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.SUCCESS 或 OperationResult.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 值范围的约束。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

    number 可选

  • 分钟

    number 可选

  • quant

    number 可选

OptionGroup

Chrome 125 及更高版本

属性

  • 成员

    字符串[]

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

  • title

    字符串

    提供可打印的标题，例如“Geometry options”。

OptionSetting

Chrome 125 及更高版本

属性

  • name

    字符串

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

  • 类型

    OptionType

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

  • 值

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

    表示要设置的值。请将其保持未设置状态，以请求为已启用 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

    number 可选

    如果 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 字母、数字和短划线。不允许使用变音符号。

  • title

    字符串

    可打印的一行标题。

  • 类型

    OptionType

    value 属性中包含的数据类型，用于设置此选项。

  • 单位

    OptionUnit

    此选项的衡量单位。

  • 值

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

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

ScanOptions

属性

  • maxImages

    number 可选

    允许的扫描图片数量。默认值为 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

    number 可选

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

StartScanResponse

Chrome 125 及更高版本

属性

  • 作业

    字符串（选填）

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

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

  • scannerHandle

    字符串

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

方法

cancelScan()

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

取消已开始的扫描，并返回一个 promise，由 CancelScanResponse 对象解析。如果使用回调，则会改为将对象传递给它。

参数

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

closeScanner()

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

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

参数

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getOptionGroups()

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

从之前通过 openScanner 打开的扫描器获取群组名称和成员选项。此方法会返回一个 promise，由 GetOptionGroupsResponse 对象解析。如果向此函数传递回调，系统会改为将返回的数据传递给它。

参数

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getScannerList()

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

获取可用扫描器的列表，并返回一个 promise，由 GetScannerListResponse 对象解析。如果向此函数传递回调，系统会改为将返回的数据传递给它。

参数

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

openScanner()

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

打开扫描器以获得独占访问权限，并返回一个 promise，该 promise 会解析为 OpenScannerResponse 对象。如果向此函数传递回调，系统会改为将返回的数据传递给它。

参数

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

readScanData()

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

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

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

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

参数

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

scan()

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

执行文档扫描，并返回一个 promise，由 ScanResults 对象解析。如果向此函数传递回调，则系统会改为将返回的数据传递给它。

参数

  • 选项

    ScanOptions

    一个包含扫描参数的对象。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: ScanResults) => void

返回

  • Promise<ScanResults>

    Chrome 96 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

setOptions()

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

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

参数

  • scannerHandle

    字符串

    用于设置选项的扫描器句柄。这应是之前从调用 openScanner 返回的值。

  • 选项

    OptionSetting[]

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (response: SetOptionsResponse) => void

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

startScan()

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

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

参数

  • scannerHandle

    字符串

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

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (response: StartScanResponse) => void

返回

  • 清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。