更新记录

1.0.0（2026-03-18） 下载此版本

首次发布

平台兼容性

uni-app(4.45)

鸿蒙Next+Android+iOS 离线OCR文字识别 UTS插件

离线OCR文字识别插件，支持鸿蒙Next、Android、iOS三端，无需本地编译原生库，无需鸿蒙开发环境。鸿蒙平台使用Core Vision Kit的textRecognition模块，直接调用系统内置OCR能力；Android/iOS使用MNN 3.2.0。

核心特性

• 三端完整支持：完美适配鸿蒙Next、Android、iOS全平台
• 离线识别：鸿蒙平台使用Core Vision Kit的textRecognition模块，Android/iOS基于MNN 3.2.0实现本地推理，无需网络连接，保护用户隐私
• 高性能：鸿蒙平台利用系统内置AI能力和硬件加速（如NPU），Android/iOS使用MNN 3.2.0优化的推理引擎，支持多线程加速，识别速度快
• 无需模型文件：鸿蒙平台使用系统内置OCR能力，无需下载和管理模型文件
• 轻量模型：Android/iOS集成PaddleOCR ch_PP-OCRv4_light轻量模型，识别精度高，模型体积小
• 模型自动下载：Android/iOS首次使用自动下载模型，支持断点续传和进度提示
• 统一API：三端使用相同的API接口，开发更简单
• 权限管理：自动申请相机/相册/存储权限，拒绝后给出引导提示
• 性能优化：图片预处理（缩放/灰度化）适配各端硬件能力

安装方法

HBuilderX中安装

1. 打开HBuilderX，进入项目
2. 点击「工具」→「插件安装」→「市场」
3. 搜索「鸿蒙Next+Android+iOS 离线OCR文字识别 MNN3.2.0 UTS插件」并安装
4. 或直接导入插件包：将uni-ocr-offline-harmony目录复制到项目的uni_modules目录下

依赖要求

• 鸿蒙Next：MNN 3.2.0 预制HAR包（已内置）
• Android：libMNN.so（armeabi-v7a/arm64-v8a），来自MNN-3.2.0-android.zip的lib/目录
• iOS：MNN.framework（arm64/x86_64），来自MNN-3.2.0-ios.zip根目录

API文档

1. init(options: UniOcrInitOptions): Promise

初始化OCR引擎

参数：

• options：初始化参数
  • modelPath：模型本地路径
  • vocabPath：可选，字典/标签文件路径
  • threads：可选，推理线程数（默认2）
  • lowPower：可选，是否启用低功耗模式
  • mock：可选，是否启用模拟模式

2. recognizeImage(options: UniOcrRecognizeImageOptions): Promise

识别本地图片

参数：

• options：识别参数
  • path：图片本地路径
  • structured：可选，是否启用结构化模式

返回值：

• UniOcrResult：识别结果
  • text：合并后的全文文本
  • blocks：结构化文字块数组
  • raw：原始结果

3. export(result: UniOcrResult, format: UniOcrExportFormat): string

导出识别结果

参数：

• result：识别结果
• format：导出格式（'text'或'json'）

返回值：

• 导出的字符串

4. downloadModel(modelInfo: UniOcrModelInfo, : UniOcrProgressCallback): Promise

下载模型

参数：

• modelInfo：模型信息
  • name：模型名称
  • url：模型下载URL
  • localPath：模型本地保存路径
• onProgress：进度回调函数

返回值：

• 是否下载成功

5. checkModelStatus(modelPath: string): Promise

检查模型状态

参数：

• modelPath：模型路径

返回值：

• 模型是否存在

6. deleteModel(modelPath: string): Promise

删除模型

参数：

• modelPath：模型路径

返回值：

• 是否删除成功

7. requestPermission(type: PermissionType): Promise

申请权限

参数：

• type：权限类型（'camera'、'album'或'storage'）

返回值：

• 权限状态

8. openAppSettings(): void

打开应用设置页面

使用示例

基本使用

import { uniOcrOfflineHarmony } from '@/uni_modules/uni-ocr-offline-harmony/utssdk/index.uts';

// 初始化引擎
await uniOcrOfflineHarmony.init({
  modelPath: '/path/to/model.mnn',
  threads: 2
});

// 识别图片
const result = await uniOcrOfflineHarmony.recognizeImage({
  path: '/path/to/image.jpg'
});

console.log('识别结果:', result.text);
console.log('文字块:', result.blocks);

// 导出结果
const textResult = uniOcrOfflineHarmony.export(result, 'text');
const jsonResult = uniOcrOfflineHarmony.export(result, 'json');

模型下载

// 下载模型
const modelInfo = {
  name: 'ch_PP-OCRv4_light',
  url: 'https://example.com/models/ch_PP-OCRv4_light.mnn',
  localPath: '/path/to/models/ch_PP-OCRv4_light.mnn'
};

const success = await uniOcrOfflineHarmony.downloadModel(modelInfo, (progress) => {
  console.log('下载进度:', progress);
});

if (success) {
  console.log('模型下载成功');
} else {
  console.error('模型下载失败');
}

权限管理

// 申请相机权限
const cameraStatus = await uniOcrOfflineHarmony.requestPermission('camera');
if (cameraStatus.granted) {
  console.log('相机权限已授予');
} else if (cameraStatus.neverAskAgain) {
  console.log('相机权限被拒绝且不再询问，请去设置页面开启');
  uniOcrOfflineHarmony.openAppSettings();
} else {
  console.log('相机权限被拒绝');
}

三端适配说明

鸿蒙Next

• 基于Core Vision Kit的textRecognition模块（系统内置）
• 直接调用系统内置OCR能力，无需模型文件
• 使用鸿蒙原生API进行文件操作
• 支持鸿蒙Next模拟器和真机
• 利用设备硬件加速（如NPU），识别速度快

Android

• 封装libMNN.so（支持armeabi-v7a/arm64-v8a架构）
• 使用Android原生API进行文件操作和网络请求
• 支持Android 5.0+版本
• 图片预处理：缩放和灰度化

iOS

• 封装MNN.framework（支持arm64/x86_64架构）
• 使用iOS原生API进行文件操作和网络请求
• 支持iOS 12.0+版本
• 图片预处理：缩放和灰度化

模型转换指引

PaddleOCR模型转MNN格式

1. 下载PaddleOCR ch_PP-OCRv4_light模型
2. 使用MNN 3.2.0提供的mnnconvert工具进行转换：

# 转换检测模型
./mnnconvert --framework Paddle --modelFile ch_PP-OCRv4_det_infer/model.pdmodel --paramFile ch_PP-OCRv4_det_infer/model.pdiparams --MNNModel det.mnn --bizCode MNN

# 转换识别模型
./mnnconvert --framework Paddle --modelFile ch_PP-OCRv4_rec_infer/model.pdmodel --paramFile ch_PP-OCRv4_rec_infer/model.pdiparams --MNNModel rec.mnn --bizCode MNN

# 合并模型（可选）
./mnnmerge det.mnn rec.mnn ch_PP-OCRv4_light.mnn

模型量化优化

MNN 3.2.0支持多种量化方式，可减小模型体积并提升推理速度：

# 4-bit量化
./mnnquant --model input.mnn --quantizedModel output_quant.mnn --type asymmetric_quantize --bits 4

# 8-bit量化
./mnnquant --model input.mnn --quantizedModel output_quant.mnn --type asymmetric_quantize --bits 8

性能优化方案

1. 模型优化：

   • 使用量化模型（4-bit/8-bit）
   • 调整模型输入尺寸（如640x640）
   • 裁剪模型多余算子

2. 推理优化：

   • 启用MNN多线程推理（设置threads参数）
   • 使用GPU加速（如果设备支持）
   • 图片预处理优化（缩放、灰度化）

3. 内存优化：

   • 及时释放模型和图片资源
   • 使用内存池管理
   • 避免频繁创建大对象

4. 加载优化：

   • 模型下载后缓存到本地
   • 使用断点续传减少网络失败影响
   • 后台预加载模型

权限说明

插件需要以下权限：

• 相机权限：用于拍照识别
• 相册权限：用于选择图片识别
• 存储权限：用于存储模型文件

插件会自动申请这些权限，用户拒绝后会给出引导提示，引导用户去设置页面手动开启权限。

常见问题

1. 模型下载失败

• 检查网络连接
• 确保设备有足够的存储空间
• 检查模型下载地址是否正确
• 检查存储权限是否已授予

2. 识别精度低

• 确保图片清晰，文字区域完整
• 调整图片角度，确保文字水平
• 光线充足，避免过暗或过亮
• 尝试使用更高精度的模型

3. 推理速度慢

• 检查设备性能（低端设备可能较慢）
• 使用量化模型
• 启用多线程推理（设置threads参数）
• 调整图片尺寸

4. 权限申请失败

• 检查设备系统版本
• 确保应用有足够的权限
• 引导用户去设置页面手动开启权限

许可证

• 插件本身：MIT License
• MNN：MIT License - https://github.com/alibaba/MNN/blob/master/LICENSE
• PaddleOCR：Apache 2.0 License - https://github.com/PaddlePaddle/PaddleOCR/blob/release/2.7/LICENSE

更新日志

V1.0.0

• 三端离线OCR功能首发
• 支持鸿蒙Next、Android、iOS平台
• 基于MNN 3.2.0实现
• 集成PaddleOCR ch_PP-OCRv4_light模型
• 支持模型自动下载和进度提示
• 实现权限自动申请与引导
• 优化图片预处理逻辑
• 提供完整的示例页面

技术支持

• 如有问题，请在插件市场留言
• 或提交Issue到GitHub仓库
• 建议使用最新版本的HBuilderX和MNN库
• 如需定制开发，可联系插件作者

注意事项

• 本插件不内置模型文件，首次使用需要下载模型
• 模型下载需要网络连接，下载完成后可离线使用
• 不同设备性能不同，识别速度可能有所差异
• 建议在应用启动时预加载模型，提升用户体验
• 对于复杂场景，可能需要调整模型或参数以获得最佳效果