# @dariyd/react-native-document-scanner 中文文档

规范地址：https://npmcn.com/package/%40dariyd/react-native-document-scanner/

版本：2\.2\.0
npm 元数据更新时间：2026-10-27T10:35:45.268Z
中文译文更新时间：2026-11-11T11:45:57.131Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dariyd/react-native-document-scanner
原文对照：https://npmcn.com/package/%40dariyd/react-native-document-scanner/?lang=original
项目主页：https://github.com/dariyd/react-native-document-scanner#readme
源码仓库：https://github.com/dariyd/react-native-document-scanner

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

- 包体积（解压后）：28.7 MB，28 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.2\.0，react-native \>=0\.77\.3
- 首次发布：2025-10-20T18:42:17.944Z
- 最新版本发布：2026-10-27T10:35:44.839Z
- 近 30 天下载量：43288（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 5 个）

## 中文简介

使用 VisionKit (iOS) 和 ML Kit (Android) 进行本地文档扫描, 支持新旧架构

## 安装

```sh
npm install @dariyd/react-native-document-scanner
```

也可以使用：`pnpm add @dariyd/react-native-document-scanner`、`yarn add @dariyd/react-native-document-scanner`、`bun add @dariyd/react-native-document-scanner`

## README

# 反应 - 内存 - 文档扫描器

[![npm version](https://img.shields.io/npm/v/%40dariyd%2Freact-native-document-scanner.svg)](https://www.npmjs.com/package/@dariyd/react-native-document-scanner) [![license](https://img.shields.io/npm/l/%40dariyd%2Freact-native-document-scanner.svg)](https://npmcn.com/package/%40dariyd/react-native-document-scanner/LICENSE)

Fast, 本地 React Industrial 文档扫描仪用于iOS和Android,使用Apple VisionKit(iOS)和Google ML Kit(Android). 特性为自动文档检测,边缘/透视校正,多 页扫描,可配置图像质量,可选 Base64,以及支持在ios和和 android上的回放原生新建筑.

-   **iOS系统**: 使用 VisionKit 框架和 VNDocumentCameraView 控制器
-   **机器人**: 使用 ML Kit 文档扫描器 API

## 预览

| iOS 演示 | Android Demo 软件 |
| --- | --- |
| ![iOS document scanner demo](https://npmcn.com/package/%40dariyd/react-native-document-scanner/assets/ios_demo.gif) | ![Android document scanner demo](https://npmcn.com/package/%40dariyd/react-native-document-scanner/assets/android_demo.gif) |

## 用于生产应用软件

| [FileNest AI - Docs 组织器](https://apps.apple.com/us/app/filenest-ai-docs-organizer/id6756841050) | [MyGarage - 汽车Docs和历史](https://apps.apple.com/us/app/mygarage-cardocs-history/id6757166595) | [我的书目](https://apps.apple.com/us/app/mylabstory/id6757186292) |
| --- | --- | --- |
| [![FileNest AI](https://npmcn.com/package/%40dariyd/react-native-document-scanner/assets/FileNest%20AI.gif)](https://apps.apple.com/us/app/filenest-ai-docs-organizer/id6756841050) | [![MyGarage](https://npmcn.com/package/%40dariyd/react-native-document-scanner/assets/MyGarage%20%7C%20CarDocs%20%26%20History.gif)](https://apps.apple.com/us/app/mygarage-cardocs-history/id6757166595) | [![MyLabStory](https://npmcn.com/package/%40dariyd/react-native-document-scanner/assets/MyLabStory.gif)](https://apps.apple.com/us/app/mylabstory/id6757186292) |

## 特征

-   QQ跨平台支持(iOS 13+和Android API 21+)
-   QQ iOS & Android: 全面支持新的 React Introduct 架构(Fabric/TurboModules) 互联网档案馆的存檔,存档日期2013-12-21
-   自动文档检测和扫描
-   多页文档扫描
-   配置图像质量
-   QQ 可选最大宽度/ 高度以盖住图像大小
-   & & Android: 可选的 PDF 输出和可配置的 ML Kit 扫描器( 页数限制、 画廊导入、 扫描器模式)
-   QQ 可选基础64 编码
-   QQ 平台均等 - 两个平台的相同API

> 关键词:回放原生文档扫描仪,VisionKit文档扫描仪,ML Kit文档扫描仪,回放原生文档,回放边缘检测,视角校正,多页扫描仪

## 安装

### 从 npm (建议)

```bash
npm install @dariyd/react-native-document-scanner
```

或带线:

```bash
yarn add @dariyd/react-native-document-scanner
```

### 从 GitHub (最新开发)

```bash
npm install https://github.com/dariyd/react-native-document-scanner.git
```

或者说

```bash
yarn add https://github.com/dariyd/react-native-document-scanner.git
```

### iOS 安装

```bash
cd ios && pod install
```

### Android 安装

无需额外步骤。 ML Kit 依赖将被自动包含在内.

## 安装后步骤

### iOS系统

添加数据 `NSCameraUsageDescription` 键 `Info.plist`数字 :

```xml
<key>NSCameraUsageDescription</key>
<string>We need access to your camera to scan documents</string>
```

### 机器人

添加相机权限到您的 `AndroidManifest.xml`数字 :

```xml
<uses-permission android:name="android.permission.CAMERA" />
```

模块在发射扫描仪时自动请求相机许可.

## 反应原生新建筑

此模块需要 **0.77.3或以上反应** 并支持iOS上的新架构,同时使用Android上的稳定旧架构.

**iOS系统**: 完全支持 Fabric 和 TurboModules - 当您在您的工程中启用新架构时自动检测并启用 .

**机器人**: 使用稳定桥执行来达到最大兼容性. 计划为今后的发行提供新架构支持.

### 所需资源

-   **0.77.3或以上反应**
-   **反应18.2.0或以上**
-   iOS 13.0 或更高
-   **机器人**数字 :
    -   最低SDK: API 21 (Android 5.0) (英语)
    -   目标SDK:API 35 (Android 15) - 由Google Play Store要求
    -   编译 SDK: API 35

### 启用新架构

**iOS系统**: 完全支持 - 设定 `RCT_NEW_ARCH_ENABLED=1` 或构建设置

**安卓尔**: 完全支持 - 保留 `newArchEnabled=true` 在你身边 `gradle.properties`

IOS实施在启用时会自动使用Fabric/TurboModules,而Android则会继续使用稳定的桥实施.

## 使用量

```javascript
import { launchScanner } from 'react-native-document-scanner';

// Basic usage
const result = await launchScanner();

// With options
const result = await launchScanner({
  quality: 0.8,
  includeBase64: false,
});

// With EXIF metadata
const result = await launchScanner({
  quality: 0.8,
  includeExif: true,
});
console.log('EXIF:', result.images[0].exif);

// With EXIF + GPS location
const result = await launchScanner({
  quality: 0.8,
  includeExif: true,
  includeLocationExif: true,
});
console.log('GPS:', result.images[0].exif?.GPSLatitude, result.images[0].exif?.GPSLongitude);

// Cap image size (e.g. to keep uploads small)
const result = await launchScanner({
  quality: 0.85,
  maxWidth: 2048,
  maxHeight: 2048,
});

// Android only: configure the ML Kit scanner and get a PDF too
// (these options are ignored on iOS, `result.pdf` is never set there)
const result = await launchScanner({
  pageLimit: 20,
  galleryImportAllowed: true,
  scannerMode: 'base_with_filter',
  includePdf: true,
});
console.log('Images:', result.images);
if (result.pdf) {
  console.log('PDF:', result.pdf.uri, result.pdf.pageCount, 'pages');
}

// With callback (optional)
launchScanner({ quality: 0.9 }, (result) => {
  if (result.didCancel) {
    console.log('User cancelled');
  } else if (result.error) {
    console.log('Error:', result.errorMessage);
  } else {
    console.log('Scanned images:', result.images);
  }
});
```

# API 参考

## 方法

```js
import {launchScanner} from 'react-native-document-scanner';
```

### `launchScanner()`

启动扫描仪扫描文件.

见 [选项](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-options) 详情请查阅 `options`。 。 。 .

这个 `callback` 将调用一个响应对象,参见 [响应对象](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-the-response-object)。 。 。 .

## 选项

| 选项 | iOS系统 | 机器人 | 说明 |
| --- | --- | --- | --- |
| 质量 | ✅ | ✅ | 图像质量在0到1之间的数字(默认:1). 数值降低文件大小 |
| 包含Base64 | ✅ | ✅ | 如果为真, 则创建图像的 Base64 字符串( Avoid 由于性能在大图像文件中使用) |
| 包含Exif | ✅ | ✅ | 如果为真,则将 EXIF 元数据(时间戳、设备信息、尺寸)嵌入到图像文件中,并在响应中返回(默认:虚假) |
| 包括LocationExif | ✅ | ✅ | 如果为真,则还将GPS坐标嵌入EXIF. 需要位置许可——见 [位置权限设置](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-location-permission-setup) (默认:虚假) |
| 准确度 | ✅ | ✅ | 嵌入位置的目标精确度 : `'approximate'` (~3公里), `'balanced'` (约100米)或 `'precise'` (最顶. 还要设置需要多少许可级别——见 [地点精确度](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-location-accuracy) (默认 : `'precise'`(中文(简体) ) |
| 任务 | ✅ | ✅ | 如果错误,扫描仪从不提示位置许可;GPS只有在已经获得许可时才会被嵌入. 当您的应用程序询问位置本身时使用( 默认: 真) |
| 地点 : | ✅ | ❌ | 键入 `NSLocationTemporaryUsageDescriptionDictionary`。设定时,如果用户只给出大致位置,则要求提供临时准确位置 `locationAccuracy` 需要它( 默认: 无) |
| 最大宽度 | ✅ | ✅ | 最大宽度以像素表示. 如果被扫描的图像更宽,则在编码之前缩放(视比被保留了). `0` 或省略 = 无上限( 默认: 0) |
| 最大重度 | ✅ | ✅ | 最大高度的像素。 与 `maxWidth` ——较小的尺度因子胜出,因此双方均不能超过其上限. `0` 或省略 = 无上限( 默认: 0) |
| 页面链接 | ❌ | ✅ | 仅限Android. 每个扫描会话的最大页数 。 低于1的值作为1处理(默认:10) |
| 图片库导入完毕 | ❌ | ✅ | 仅限Android. 如果真实, 用户可以从相册中导入图像, 而不是相机( 默认: 假) |
| 扫描模式 | ❌ | ✅ | 仅限Android. `'base'`, (中文(简体) ), `'base_with_filter'` 或者说 `'full'` 看到了吗 [扫描机模式](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-scanner-modes-android-only) (默认 : `'full'`(中文(简体) ) |
| 包含Pdf | ❌ | ✅ | 仅限Android. 如果真实,答复中还包含 `pdf` 所有页面的对象——见 [PDF 对象](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-pdf-object-android-only)。 。 。 . `images` 总是返回( 默认: 假) |

> 以上四个选项配置 ML Kit 扫描仪, 并且是 **忽略在 iOS 上** ——通过它们是安全的,它们在那里根本就没有效果.

### 扫描器模式( 只有Android)

| 模式 | 说明 |
| --- | --- |
| `base` | 基本编辑:裁剪、旋转、重排页面 |
| `base_with_filter` | `base` + 图像过滤器( grayscale, 自动增强) |
| `full` | `base_with_filter` +由ML带动的清洁(erase污点,指等). 这是默认 |

## 响应对象

| 键 | iOS系统 | 机器人 | 说明 |
| --- | --- | --- | --- |
| 撤销 | ✅ | ✅ | `true` 如果用户取消了进程 |
| 错误 | ✅ | ✅ | `true` 如果发生错误 |
| 错误 | ✅ | ✅ | 描述错误, 只用于调试目的 |
| 图像 | ✅ | ✅ | 一组选定的媒体, [引用图像对象](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-image-object) |
| 页:1 | ❌ | ✅ | 仅限Android. 所有页面的PDF,只有在 `includePdf` 是真的... . . [引用 PDF 对象](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-pdf-object-android-only) |

## 图像对象

| 键 | iOS系统 | 机器人 | 说明 |
| --- | --- | --- | --- |
| 基础64 | ✅ | ✅ | 图像的 Base64 字符串( 如果包含 Base64 是真实的) |
| 乌里 | ✅ | ✅ | App 特定缓存存储中的文件 uri |
| 宽度 | ✅ | ✅ | 图像宽度, 像素 |
| 高度 | ✅ | ✅ | 图像高度( 像素) |
| 文件大小 | ✅ | ✅ | 以字节计的文件大小 |
| 类型 | ✅ | ✅ | 文件 MIME 类型( 如 “ image/ jpeg ”) |
| 文件Name | ✅ | ✅ | 文件名称 |
| 法语 | ✅ | ✅ | EXIF 元数据对象(如果包含Exif是真实的). 见 [EXIF 对象](https://npmcn.com/package/%40dariyd/react-native-document-scanner/#readme-exif-object) |

## PDF 对象( 只有Android)

何时 `includePdf` 实值 `true` 在Android上,反应中还包含一个 `pdf` 对象。 它从来没有出现在iOS上.

| 键 | iOS系统 | 机器人 | 说明 |
| --- | --- | --- | --- |
| 乌里 | ❌ | ✅ | App 特定缓存存储中的文件 uri |
| 页面 | ❌ | ✅ | PDF 中的页数 |
| 文件大小 | ❌ | ✅ | 以字节计的文件大小 |
| 类型 | ❌ | ✅ | 文件 MIME 类型 (`"application/pdf"`(中文(简体) ) |
| 文件Name | ❌ | ✅ | 文件名称 |

> ⚠️ PDF 由 ML Kit 以自己的分辨率构建. 这个 `quality`, (中文(简体) ), `maxWidth` 编号 : `maxHeight` 财务报告和审定财务报表 `includeExif` 编号 : `includeLocationExif` 选项仅适用于 `images`, (中文(简体) ), **没有** 转到 PDF.

## EXIF 对象

何时 `includeExif` 实值 `true`,每个图像包含 `exif` 对象,有下列字段:

| 键 | iOS系统 | 机器人 | 说明 |
| --- | --- | --- | --- |
| 日期 原文 | ✅ | ✅ | 扫描时间戳(格式: `yyyy:MM:dd HH:mm:ss`(中文(简体) ) |
| 日期时间 | ✅ | ✅ | 扫描时间戳(格式: `yyyy:MM:dd HH:mm:ss`(中文(简体) ) |
| 像素X分解 | ✅ | ✅ | 图像宽度, 像素 |
| 像素Y 度 | ✅ | ✅ | 图像高度( 像素) |
| 颜色空间 | ✅ | ✅ | 颜色空间(1= sRGB) |
| 制作 | ✅ | ✅ | 设备制造商 |
| 型号 | ✅ | ✅ | 设备模型 |
| 软件 | ✅ | ✅ | 应用名称 |
| GPS 纬度 | ✅ | ✅ | 纬度( 仅在 `includeLocationExif` 真实并获得许可) |
| GPS 纬度 | ✅ | ✅ | 经度(仅在 `includeLocationExif` 真实并获得许可) |
| GPS 高度 | ✅ | ✅ | 高度( 公尺) |
| GPS 高角精确度 | ✅ | ✅ | 全球定位系统精确度(米) |
| GPS 时间UTC | ✅ | ✅ | UTC中的 GPS 固定时间戳 |

## 位置权限设置

使用时 `includeLocationExif: true`,软件包需要时请求位置许可(除非 `requestLocationPermission: false`) (中文(简体) ). 您必须在您的应用程序中添加所需的权限密钥 :

### iOS系统

添加到您的 `Info.plist`数字 :

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location will be embedded in scanned documents for record-keeping.</string>
```

### 机器人

不需要额外设置。 软件包声明 `ACCESS_FINE_LOCATION` 财务报告和审定财务报表 `ACCESS_COARSE_LOCATION` 权限在自己的列表中,该列表将自动合并.

### 允许行为

-   如果需要许可级别 `locationAccuracy` 已经 **尚未获准**,系统对话框在相机打开前出现——要求精确的这个关卡(近似于 `'approximate'`,准确的除外)
-   如果授权是 **已经批准** 在该级别上,没有显示对话框
-   如果授权是 **被拒绝**,GPS 字段会默默跳过,扫描结果通常
-   与 `requestLocationPermission: false` 扫描仪 **永远** 显示对话框 —— 如果您想要 GPS , 请在扫描前询问应用程序中的位置
-   位置权限是 **仅在 `includeLocationExif: true`** 它没有其他效果

### 地点精确度

地点是 **最好不要拖延摄像头**。扫描仪立即打开;使用最近缓存的固定(5分钟以下),在用户扫描时进行位置更新,保持最准确的固定。 更新一旦固定到 `locationAccuracy` 目标,或扫描仪关闭时。 获得的最佳固定值在扫描保存时被嵌入—— `GPSHorizontalAccuracy` 财务报告和审定财务报表 `GPSDateTimeUTC` 告诉你它有多精确 和何时被取走.

| `locationAccuracy` | 目标 | 需要许可 | iOS系统 | 机器人 |
| --- | --- | --- | --- | --- |
| `'approximate'` | 约3公里 | 大约 | `kCLLocationAccuracyThreeKilometers` | `ACCESS_COARSE_LOCATION`, (中文(简体) ), `PRIORITY_LOW_POWER` |
| `'balanced'` | ~100米(约100米) | 准确 | `kCLLocationAccuracyHundredMeters` | `ACCESS_FINE_LOCATION`, (中文(简体) ), `PRIORITY_BALANCED_POWER_ACCURACY` |
| `'precise'` | 最好,我说 | 准确 | `kCLLocationAccuracyBest` | `ACCESS_FINE_LOCATION`, (中文(简体) ), `PRIORITY_HIGH_ACCURACY` |

如果在请求精确关卡时只给予近似许可,则嵌入了最佳近似固定. 一个没有缓存固定的非常快的扫描,或者没有位置信号(例如没有最近固定的飞机模式),只是产生一个没有GPS的图像.

### iOS:没有位置的建筑

位置代码被构建在您的应用程序中, 即使你从未设置 `includeLocationExif`,所以 App Store 连接可能会警告丢失 `NSLocationWhenInUseUsageDescription` (ITMS-90683) (英语). 如果你的应用从未使用 `includeLocationExif`中,通过在顶部附近添加此行,留下位置代码 `ios/Podfile`运行 `pod install`数字 :

```ruby
ENV['RNDS_DISABLE_LOCATION'] = '1'
```

您也可以设定为一次运行 : `RNDS_DISABLE_LOCATION=1 pod install`由于位置被忽略, `includeLocationExif` 警告在发展中被忽略.

## 平台差异

虽然这两个平台提供类似的功能,但有一些细微的差异:

### iOS系统

-   使用本地视野框架
-   需要iOS 13.0或更高
-   支持 PNG 质量格式 = 1.0, JPEG 质量 < 1.0

### 机器人

-   使用 Google ML Kit 文档扫描器
-   最低SDK: API 第21级 (Android 5.0)
-   目标SDK:API 第35级(Android 15) - Google Play Store要求
-   总是输出 JPEG 格式( 当 `includePdf` 事实)
-   扫描仪行为可以通过 `pageLimit`, (中文(简体) ), `galleryImportAllowed`, (中文(简体) ), `scannerMode` ——无iOS等同
-   需要谷歌游戏服务

## 解决问题

### Android: ML Kit 无法使用

如果你遇到关于Android的ML Kit的问题,确保:

1.  Google 游戏服务安装在设备/模拟器上
2.   `compileSdkVersion` 35岁或以上
3.   `targetSdkVersion` 35 (由 Google Play Store 所要求)
4.   `minSdkVersion` 21岁或以上

### iOS: 相机权限被拒绝

确保您已经添加 `NSCameraUsageDescription` 键 `Info.plist`。 。 。 .

## 示例

检查 `example/` 显示扫描仪的完整示例应用程序的目录.

## 灵感来自

-   iOS的执行: [反应-内生-图像采集器](https://github.com/react-native-image-picker/react-native-image-picker)
-   Android ML Kit: (英语) [Google ML Kit 文档扫描器](https://developers.google.com/ml-kit/vision/doc-scanner)

## 许可证

麻省理工学院

## 常见问题

### @dariyd/react-native-document-scanner 是什么？

使用 VisionKit \(iOS\) 和 ML Kit \(Android\) 进行本地文档扫描, 支持新旧架构

### 如何安装 @dariyd/react-native-document-scanner？

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

### @dariyd/react-native-document-scanner 支持 TypeScript 吗？

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

### @dariyd/react-native-document-scanner 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dariyd/react-native-document-scanner 可以商用吗？

@dariyd/react-native-document-scanner 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dariyd/react-native-document-scanner 的下载量有多少？

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

### @dariyd/react-native-document-scanner 还在维护吗？

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