# @capacitor-mlkit/document-scanner 中文文档

规范地址：https://npmcn.com/package/%40capacitor-mlkit/document-scanner/

版本：8\.2\.2
npm 元数据更新时间：2026-10-31T07:03:58.493Z
中文译文更新时间：2026-11-09T02:47:41.303Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capacitor-mlkit/document-scanner
原文对照：https://npmcn.com/package/%40capacitor-mlkit/document-scanner/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/mlkit/document-scanner
源码仓库：https://github.com/capawesome-team/capacitor-mlkit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：82.9 kB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-07-30T17:22:21.519Z
- 最新版本发布：2026-10-31T07:03:58.149Z
- 近 30 天下载量：76757（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 9 个）

## 中文简介

Android上的ML Kit文档扫描器的电容插件.

## 安装

```sh
npm install @capacitor-mlkit/document-scanner
```

也可以使用：`pnpm add @capacitor-mlkit/document-scanner`、`yarn add @capacitor-mlkit/document-scanner`、`bun add @capacitor-mlkit/document-scanner`

## README

# ML Kit 文档扫描器插件

非官方电容插件 [ML Kit 文档扫描器](https://developers.google.com/ml-kit/vision/doc-scanner)\[^1\]

[![Ship a fix in one command with Capawesome Cloud Live Updates, no store review](https://capawesome.io/assets/banners/cloud-ship-a-fix-in-one-command.png)](https://capawesome.io/)

## 使用大小写

文档扫描器插件通常用于应用程序需要将纸面文档与相机数字化时,例如:

-   **收支记录**:让用户扫描收据和发票作为JPEG图像或PDF文件进行费用跟踪.
-   **文档存档**:将合同、信件和其他文件数字化为多页PDF文件.
-   **提交的表格**:让用户在您的应用程序中扫描并提交签名的表格或辅助文档.
-   **清除文档相片**: 使用由ML驱动的图像清理能力去除扫描页上的污点和指头.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/document-scanner` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capacitor-mlkit/document-scanner
npx cap sync
```

### 机器人

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$mlkitDocumentScannerVersion` 版本 `com.google.android.gms:play-services-mlkit-document-scanner` (默认 : `16.0.0`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

## 使用量

以下例子显示了如何扫描文档以及如何检查并安装Google文档扫描器模块.

### 扫描文档

启动文档扫描程序,打开ML Kit文档扫描器 UI. 您可以允许图片库导入,限制页面数量,并选择结果格式和扫描器模式. 仅在Android上可用:

```typescript
import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const scanDocument = async () => {
  const result = await DocumentScanner.scanDocument({
    galleryImportAllowed: true,
    pageLimit: 5,
    resultFormats: 'JPEG_PDF',
    scannerMode: 'FULL',
  });

  console.log('Scanned images:', result.scannedImages);
  console.log('PDF info:', result.pdf);
};
```

在Android上,系统可能在扫描仪打开时破坏应用程序. 在这种情况下,承诺永远不会实现。 相反,结果是通过 `appRestoredResult` 一、导 言 [应用插件](https://capacitorjs.com/docs/apis/app#addlistenerapprestoredresult-) 当应用程序恢复时:

```typescript
import { App } from '@capacitor/app';

App.addListener('appRestoredResult', event => {
  if (event.pluginId !== 'DocumentScanner' || event.methodName !== 'scanDocument') {
    return;
  }
  if (event.success) {
    const scannedImages = event.data.scannedImages;
  } else {
    console.error(event.error?.message);
  }
});
```

### 检查并安装 Google 文件扫描器模块

文档扫描器模型,扫描逻辑,和UI流被Google Play服务动态下载. 检查模块是否可用, 并在需要时安装 。 安装只从此调用开始 `googleDocumentScannerModuleInstallProgress` 事件向您通报进展。 仅在Android上可用:

```typescript
import { DocumentScanner } from '@capacitor-mlkit/document-scanner';

const isGoogleDocumentScannerModuleAvailable = async () => {
  const result = await DocumentScanner.isGoogleDocumentScannerModuleAvailable();
  console.log('Is Google Document Scanner module available:', result.available);
};

const installGoogleDocumentScannerModule = async () => {
  await DocumentScanner.installGoogleDocumentScannerModule();
  console.log('Google Document Scanner module installation started.');
};

DocumentScanner.addListener('googleDocumentScannerModuleInstallProgress', (event) => {
  console.log('Installation progress:', event.progress, '%');
  console.log('Current state:', event.state);
});
```

## API 密码

-   [`scanDocument(...)`](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-scandocument)
-   [`isGoogleDocumentScannerModuleAvailable()`](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-isgoogledocumentscannermoduleavailable)
-   [`installGoogleDocumentScannerModule()`](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-installgoogledocumentscannermodule)
-   [`addListener('googleDocumentScannerModuleInstallProgress', ...)`](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-addlistenergoogledocumentscannermoduleinstallprogress-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-enums)

### 扫描文档(...)

```typescript
scanDocument(options: ScanOptions) => Promise<ScanResult>
```

开始文档扫描进程.

**请注意:** 打开 _机器人_,系统可能在扫描仪打开时破坏应用程序。 在这种情况下,承诺 决不会下定决心 相反,结果是通过 `appRestoredResult` 一、导 言 [应用插件](https://capacitorjs.com/docs/apis/app#addlistenerapprestoredresult-) 当应用程序恢复时.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ScanOptions](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-scanoptions)` |

**回返情况:** `Promise<[ScanResult](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-scanresult)>`

**自:** 7.3.0 (单位:千美元)

* * *

### 是GoogleDocumentScannerModuleAvailable( ) 文档扫描器

```typescript
isGoogleDocumentScannerModuleAvailable() => Promise<IsGoogleDocumentScannerModuleAvailableResult>
```

请检查google文档扫描器模块是否可用 .

如果Google文档扫描器模块不可用,您可以通过使用 `installGoogleDocumentScannerModule()`。 。 。 .

只能从Android上找到.

**回返情况:** `Promise<[IsGoogleDocumentScannerModuleAvailableResult](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-isgoogledocumentscannermoduleavailableresult)>`

**自:** 7.3.0 (单位:千美元)

* * *

### 安装 GoogleDocumentScannerModule ()

```typescript
installGoogleDocumentScannerModule() => Promise<void>
```

安装谷歌文档扫描器模块 .

**请注意**:这只开始安装. 这个 `googleDocumentScannerModuleInstallProgress` 事件听众会 安装完成后通知您.

只能从Android上找到.

**自:** 7.3.0 (单位:千美元)

* * *

### 添加倾听器( “ googleDocumentScannerModule Install Progress” ,...)

```typescript
addListener(eventName: 'googleDocumentScannerModuleInstallProgress', listenerFunc: (event: GoogleDocumentScannerModuleInstallProgressEvent) => void) => Promise<PluginListenerHandle>
```

当Google文档扫描器模块安装时调用.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'googleDocumentScannerModuleInstallProgress'` |
| **`listenerFunc`** | `(event: [GoogleDocumentScannerModuleInstallProgressEvent](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-googledocumentscannermoduleinstallprogressevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-pluginlistenerhandle)>`

**自:** 7.3.0 (单位:千美元)

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

只能从Android上找到.

**自:** 7.3.0 (单位:千美元)

* * *

### 接口

#### 扫描结果

文档扫描操作结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`scannedImages`** | `string[]` | 用于扫描图像页面的URI阵列(JPEG). 如果结果格式中请求“ JPEG ” 或“ JPEG PDF ” , 则显示 . | 7.3.0 (单位:千美元) |
| **`pdf`** | `[PdfInfo](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-pdfinfo)` | 关于生成的PDF的信息. 如果结果Formats中要求“ PDF” 或“ JPEG PDF ” , 则显示 . | 7.3.0 (单位:千美元) |

#### PdfInfo 数据

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`uri`** | `string` | 生成的 PDF 文件的 URI . | 7.3.0 (单位:千美元) |
| **`pageCount`** | `number` | PDF中的页数. | 7.3.0 (单位:千美元) |

#### 扫描选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`galleryImportAllowed`** | `boolean` | 是否允许从相册导入 . | `false` | 7.3.0 (单位:千美元) |
| **`pageLimit`** | `number` | 可扫描的最大页数. | `10` | 7.3.0 (单位:千美元) |
| **`resultFormats`** | `'JPEG' | 'PDF' | 'JPEG_PDF'` | 预期成果格式。 可以是"JPEG","PDF",也可以是"JPEG PDF". | `'JPEG_PDF'` | 7.3.0 (单位:千美元) |
| **`scannerMode`** | `'FULL' | 'BASE' | 'BASE_WITH_FILTER'` | 扫描仪模式。 BASE:基本编辑能力(剪接,旋转,重排页面等). BASE WITH FILTER:将图像过滤器(grayscale,自动图像增强等)添加到BASE模式. FulL:在BASE WITH FILTER模式中加入由ML驱动的图像清理能力(erase 污点,指等). 该模式还将允许未来的主要功能与Google Play服务更新一起被自动添加,而其他两种模式将保持其目前的功能集,仅接收到一些小的改进. | `"FULL"` | 7.3.0 (单位:千美元) |

#### Is Google DocumentScannerMudule Avail可生效文件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`available`** | `boolean` | 是否提供谷歌文档扫描器模块 . | 7.3.0 (单位:千美元) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 谷歌文档扫描器模块Install ProgressEvent

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`state`** | `[GoogleDocumentScannerModuleInstallState](https://npmcn.com/package/%40capacitor-mlkit/document-scanner/#readme-googledocumentscannermoduleinstallstate)` | 安装现状. | 7.3.0 (单位:千美元) |
| **`progress`** | `number` | 安装进度在0-100之间. | 7.3.0 (单位:千美元) |

### 数字

#### 谷歌文件扫描器模块Install State

| 成员 | 数值 | 自兹 |
| --- | --- | --- |
| **`UNKNOWN`** | `0` | 7.3.0 (单位:千美元) |
| **`PENDING`** | `1` | 7.3.0 (单位:千美元) |
| **`DOWNLOADING`** | `2` | 7.3.0 (单位:千美元) |
| **`CANCELED`** | `3` | 7.3.0 (单位:千美元) |
| **`COMPLETED`** | `4` | 7.3.0 (单位:千美元) |
| **`FAILED`** | `5` | 7.3.0 (单位:千美元) |
| **`INSTALLING`** | `6` | 7.3.0 (单位:千美元) |
| **`DOWNLOAD_PAUSED`** | `7` | 7.3.0 (单位:千美元) |

## 页:1

-   ML Kit文档扫描器模型,扫描逻辑,和UI流被Google Play服务动态下载. 用户可能必须在第一次使用前等待这些下载. 您可以使用 GoogleDocumentScannerModuleAvailable 并安装 GoogleDocumentScannerModule 方法来检查和安装模块,并听取 GoogleDocumentScannerModule Install 进度更新事件 .
-   这个API需要Android API级别21或以上.
-   它还需要最小的设备总RAM为1.7GB. 如果更低,则返回一个 `MlKitException` 有错误代码 `UNSUPPORTED` 当调用 API( 此插件将拒绝承诺) 时 .
-   认为生成文档文件需要时间并需要处理功率,所以仅请求输出格式(JPEG,或PDF,或两者兼用) `resultFormats` 选项.

## 财务问题

### 此插件支持哪些平台 ?

该插件只在Android上可用,因为基础的ML Kit文档扫描器由Google Play服务提供. 所有的方法都拒绝在其他平台上.

### 为什么文档扫描仪不能首先使用?

ML Kit文档扫描器模型,扫描逻辑,和UI流被Google Play服务动态下载,因此用户可能不得不等下载后再首次使用. 使用 `isGoogleDocumentScannerModuleAvailable()` 检查模块, `installGoogleDocumentScannerModule()` 安装,并听 `googleDocumentScannerModuleInstallProgress` 用于更新进度的事件.

### 从扫描中可以得到哪些结果格式?

您可以通过 : `resultFormats` 选项。 然后,结果包含一系列URI,用于扫描图像页面和/或关于生成的PDF的信息,包括其URI和页数. 由于生成文档文件需要时间和处理能力,所以只请求您实际需要的格式.

### 扫描器模式有什么区别?

这个 `BASE` 模式提供了基本的编辑能力,如裁剪、旋转和重排页面。 这个 `BASE_WITH_FILTER` 模式增加了图像过滤器,如灰度和自动图像增强等. 这个 `FULL` 模式(默认)额外提供由ML驱动的图像清理能力,例如去除污点和指头,并将随着Google Play服务的更新而自动接收未来的主要功能.

### 是否有设备要求?

是,API要求Android API级别为21级或以上,最低设备总RAM为1.7 GB. API 返回一个 `MlKitException` 有错误代码 `UNSUPPORTED` 而插件拒绝承诺.

### 用户可以导入已有相片而不是扫描吗 ?

是的,设置 `galleryImportAllowed` 选项到 `true` 允许从相册中导入页面。 默认已禁用 .

## 相关插件

-   [ML Kit 条码扫描](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/):用ML Kit Barcode扫描扫描条码和QR码.
-   [PDF 查看器](https://capawesome.io/docs/sdks/capacitor/pdf-viewer/): 在全屏本地查看器中显示 PDF 文档.
-   [文件打开器](https://capawesome.io/docs/sdks/capacitor/file-opener/): 打开带有默认应用程序的扫描文件.

## 术语和隐私

此插件使用 [Google ML Kit (Google ML Kit) 页面存档备份,存于互联网档案馆](https://developers.google.com/ml-kit)数字 :

-   [术语和隐私](https://developers.google.com/ml-kit/terms)
-   [Android 数据披露](https://developers.google.com/ml-kit/android-data-disclosure)
-   [iOS 数据披露](https://developers.google.com/ml-kit/ios-data-disclosure)

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/document-scanner/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-mlkit/blob/main/packages/document-scanner/LICENSE)。 。 。 .

\[^1\]: 这个项目不附属于Google LLC或其任何子公司或子公司,也不获得其认可、支持、赞助或批准.

## 常见问题

### @capacitor-mlkit/document-scanner 是什么？

Android上的ML Kit文档扫描器的电容插件\.

### 如何安装 @capacitor-mlkit/document-scanner？

在项目目录运行 npm install @capacitor-mlkit/document-scanner，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capacitor-mlkit/document-scanner 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capacitor-mlkit/document-scanner 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capacitor-mlkit/document-scanner 可以商用吗？

@capacitor-mlkit/document-scanner 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @capacitor-mlkit/document-scanner 的下载量有多少？

根据 npm 官方下载统计，@capacitor-mlkit/document-scanner 在 2026/10/09 – 2026/11/07 这 30 天内被下载 76,757 次，日均约 2,559 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capacitor-mlkit/document-scanner 还在维护吗？

最新版本 8\.2\.2 发布于 2026/10/31（9 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 9 个；首次发布于 2025/07/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。