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

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

版本：8\.4\.17
npm 元数据更新时间：2026-11-02T13:08:40.342Z
中文译文更新时间：2026-11-09T02:31:27.277Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-document-scanner
原文对照：https://npmcn.com/package/%40capgo/capacitor-document-scanner/?lang=original
项目主页：https://capgo.app/docs/plugins/document-scanner/
源码仓库：https://github.com/Cap-go/capacitor-document-scanner

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

- 包体积（解压后）：160 kB，31 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-10-09T02:37:19.040Z
- 最新版本发布：2026-11-02T13:08:39.787Z
- 近 30 天下载量：112231（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 58 个）

## 中文简介

扫描文档iOS和Android的电容插件

## 安装

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

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

## README

# @ capgo/ 电容- document- scanner

用本地扫描仪扫描纸文档 UI: VisionKit 在iOS上和Google ML Kit 在Android上查找页面边缘,修复视角并返回干净的图像. 在您的应用程序中添加收件, ID 或合同抓取, 不建立相机屏幕 .

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-document-scanner)](https://capgo.app/?ref=plugin_document_scanner)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_document_scanner)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_document_scanner) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-document-scanner` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-document-scanner到我的Capacitor应用上,并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_document_scanner) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_document_scanner)

![Example app on iOS scanning a handwritten page: the scanner finds the page edges and the scanned image appears in the app](https://raw.githubusercontent.com/Cap-go/capacitor-document-scanner/main/.github/assets/readme-demo.webp)

## 主要特点

-   **原生扫描仪 UI**数字 : `scanDocument()` 打开iOS上的VisionKit文档相机和Android上的ML Kit文档扫描器,并自动进行边缘检测和视角校正.
-   **多页扫描**: 在一个会话中获取最多24页,或通过 `maxNumDocuments: 1` 用于单页模式。 Android在那页之后就停了 在iOS上,相机只在 `iosVisionKitSwizzle` 启用;默认的二进制在保存后将额外页面放下.
-   **作物和审查**:Android总是提供收成和旋转. 在iOS上,VisionKit在"保存"前显示其审查屏幕. 每次捕捉后强迫编辑器都是选入的 swizzle. 见 [iOS App Store 审查](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-ios-app-store-review-and-the-visionkit-swizzle)。 。 。 .
-   **图像清理**: 调奏 `brightness` 财务报告和审定财务报表 `contrast` 在两个平台上。 关于Android, `scannerMode` 添加过滤器和ML清洗可以去除污点和手指.
-   **灵活产出**: 获取文件路径或基数64字符串 `responseType`外加一个 `success` 或者说 `cancel` 状态.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 不支持网络 : `scanDocument()` 拒绝为未执行.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/文档-扫描器/](https://capgo.app/docs/plugins/document-scanner/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-document-scanner` plugin in my project.
```

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

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

## 重要说明

### Android 模拟器限制

ML Kit 文档扫描器 **对Android模拟器不起作用**这是Google Play Services和ML Kit对模拟设备的限制。 当测试您的应用程序时 :

-   使用一个 **物理和机器人设备** 用于测试文档扫描
-   QQ Android 仿真器将显示错误 : “ Android 仿真器上不支持文档扫描器 ”

这一限制是由于:

-   Google Play 服务与模拟环境的相容性问题
-   ML Kit 文件扫描器需要实际的硬件相机能力
-   缺乏必要 ML Kit 运行时组件的模拟器

**用于开发和测试,始终使用真正的Android设备.**

### iOS App Store 评论和 VisionKit swizzle

默认的iOS 二进制不包含私人的VisionKit swizzle. 这些呼叫载荷 `VNDocumentCameraViewController_InProcess` 与 `NSClassFromString` 交换 `documentCameraController:canAddImages:` 结束 `method_exchangeImplementations`。同一代码读取了私有的 UIKit 手势状态,以便打开裁剪编辑器。 iPhoneOS 27.1 SDK 仍然没有公开的页面限制或每封回调 `VNDocumentCameraViewController`。 。 。 .

接下来 `@capgo/capacitor-social-login`: swizzle 留在建筑外,除非应用选择进入.

默认构建 :

-   使用公众扫描 `VNDocumentCameraViewController` API (英语).
-   `maxNumDocuments` 修剪保存后返回的页面。 相机仍然可以捕捉到到VisionKit的24页系统限制.
-   `letUserAdjustCrop` 财务报告和审定财务报表 `reviewCapturedDocument` 每次抓取后不要强迫编辑器。 愿景 Kit自己在Save之前的审查屏幕没有变化.
-   Android的行为没有改变.

在您需要iOS行为时启用 swizzle :

```typescript
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    DocumentScanner: {
      iosVisionKitSwizzle: true,
    },
  },
};

export default config;
```

然后运行 `bunx cap sync`。命令将旗帜写入 `Package.swift` 财务报告和审定财务报表 `CapgoCapacitorDocumentScanner.podspec` 在已安装的插件中,下一个 iOS 构建汇编 `CAPGO_DOCUMENT_SCANNER_VISIONKIT_SWIZZLE`。去掉旗帜并运行 `bunx cap sync` 来运送默认的二进制.

兹编成:

-   `maxNumDocuments` 达到极限时停止相机。 愿景 Kit自己的帽子还是24个.
-   `letUserAdjustCrop` 每次抓取后打开 VisionKit 编辑器.
-   `reviewCapturedDocument` 在下次抓取前显示当前页面,在达到限制时编辑器仍然打开.
-   二进制包含 `method_exchangeImplementations`私人班级的检查 和私人手势读取。 Android没有改变.

这会让App Store审查更加困难. 静态分析可能命名 `method_exchangeImplementations`,您仍然可以解释评论注释中的用法: swizzle只将页数盖上并打开Apple文档扫描器内的编辑器. 它不会读取私人用户数据,也不会改变屏幕外的任何内容. 一些提交材料受到质疑,并在解释后获得批准。 其他人则没有提及这个符号。 批准是每份呈文,所以之前的通行证不会决定下一个二进制.

## 演示

### 扫描一个音符

| iOS系统 | 机器人 |
| --- | --- |
| ![iOS Demo](https://npmcn.com/package/%40capgo/capacitor-document-scanner/videos/ios.gif) | ![Android Demo](https://npmcn.com/package/%40capgo/capacitor-document-scanner/videos/android.gif) |

## API 密码

-   [`scanDocument(...)`](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-scandocument)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-enums)

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

```typescript
scanDocument(options?: ScanDocumentOptions | undefined) => Promise<ScanDocumentResponse>
```

打开设备相机并开始文档扫描体验.

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

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

* * *

### 接口

#### 扫描文件回复

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`scannedImages`** | `string[]` | 用请求的响应格式扫描图像 . |
| **`status`** | `[ScanDocumentResponseStatus](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-scandocumentresponsestatus)` | 显示扫描是否完成或取消. |

| 方法 | 签署 | 说明 |
| --- | --- | --- |
| **获取 PluginVersion** | ()QQ承诺QQ版本:字符串;QQ | 获取本地 Capacitor 插件版本 |

#### 扫描文档选项

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`croppedImageQuality`** | `number` | 仅Android:从0到100(100是最佳)被收割图像的质量. | `100` |
| **`letUserAdjustCrop`** | `boolean` | 允许用户在保存前调整检测到的裁剪. 在iOS上,VisionKit在"保存"之前已经显示自己的审查屏幕. 每次抓取后强迫编辑器需要私自的"VisionKit swizzle",它不会被编译为默认的二进制. 设定 `plugins.DocumentScanner.iosVisionKitSwizzle` 改为真实并运行 `bunx cap sync` 包括它。 见读取. 在Android上,作物/旋转总是ML Kit UI的一部分 [扫描机模式](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-scannermode); 使用 `scannerMode` 来控制过滤器和ML清洁. | `true` |
| **`reviewCapturedDocument`** | `boolean` | 启用时,在继续前显示当前被扫描的页面,以便用户可以审查,并明确继续或完成流量. 在 iOS 上,它强制本地 VisionKit 预览/编辑器仅在抓取时之间 `plugins.DocumentScanner.iosVisionKitSwizzle` 已编译。 默认二进制在保存不变前离开系统审查屏幕. 在Android上,这个切换为ML Kit会话之间的一页一行. 在iOS swizzle启用后,在扫描限制达到后仍会显示审查/编辑屏幕. | `false` |
| **`maxNumDocuments`** | `number` | 要扫描的文档最多 。 在 iOS 上,默认的二进制使用 public VisionKit,并在 Save 之后将返回的页面剪切到此限制 。 VisionKit本身仍然允许多达24次捕捉. 在下限停止相机需要 `plugins.DocumentScanner.iosVisionKitSwizzle`. On Android:自定义限制;性能默认为20(claimped 1-24)。 为单扫描模式设定为 1 。 Android在一个文档后停止. 在iOS上,相机只停留在一个文档之后 `plugins.DocumentScanner.iosVisionKitSwizzle` 已编译. | `20 on Android, 24 on iOS` |
| **`responseType`** | `[ResponseType](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-responsetype)` | 在(文件路径或基数64字符串)中返回扫描图像的格式. | `ResponseType.ImageFilePath` |
| **`brightness`** | `number` | 对扫描的图像进行了亮度调整。 范围: -255至 255 (0 = 无变化,正 = 更亮,正 = 更暗) 用于补偿低光扫描. | `0` |
| **`contrast`** | `number` | 对扫描图像进行了对比调整。 范围:0.0至10.0 (1.0 = 无变化, > 1 = 对比度较高, < 1 = 对比度较低) 有助于在灯光不好的扫描中提高文本清晰度. | `1.0` |
| **`scannerMode`** | `[ScannerMode](https://npmcn.com/package/%40capgo/capacitor-document-scanner/#readme-scannermode)` | 仅Android:控制ML Kit特性和过滤器的扫描器模式. 独立 `letUserAdjustCrop` (各种模式都有作物/轮产)。 - “碱基”:基本扫描,用收割/旋转来进行,不使用过滤器或ML清洁——“碱基 用 过滤器”: 添加灰度和自动增强过滤器 - “ 完全” : 所有特征,包括基于ML的图像清洁(后期污迹,指等) | `ScannerMode.Full` |

### 类型异名

#### 响应类型

`'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect'`

### 数字

#### 扫描文件响应状态

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`Success`** | `'success'` | 扫描成功完成 . |
| **`Cancel`** | `'cancel'` | 用户取消了扫描流量 . |

#### 响应类型

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`Base64`** | `'base64'` | 返回扫描的图像为基数64-编码字符串 . |
| **`ImageFilePath`** | `'imageFilePath'` | 返回扫描图像作为磁盘上的文件路径 . |

#### 扫描机模式

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`Base`** | `'base'` | 仅使用裁剪和旋转特性的基本文档扫描。 没有过滤器或基于ML的增强. |
| **`BaseWithFilter`** | `'base_with_filter'` | 基本功能外加自动滤波器(grayscale,自动增强). |
| **`Full`** | `'full'` | 全功能集包括基于ML的图像清理. 自动去除污物,指甲等文物. |

## 贷方

此插件是原版的重执行 [https://document-scanner.js.org (中文(简体) )](https://document-scanner.js.org/) 谢谢你的原作 我们用更现代的SDK重新编码了它 但爆炸了相同的API

## 常见问题

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

扫描文档iOS和Android的电容插件

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

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

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

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

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

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

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

@capgo/capacitor-document-scanner 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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