更新记录

1.0.0（2026-01-20）

init

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-paddle-ocr

uni-app x UTS 插件：本地离线 OCR（静态图片识别）。

• Android：Paddle Lite + OpenCV（离线 PaddleOCR 推理）
• iOS：当前使用系统 Vision 文本识别（离线；后续再替换为 Paddle Lite + OpenCV 的 PaddleOCR 全链路）
• 纯离线：不依赖网络、不上传图片/文本

平台支持

• uni-app x：app-android / app-ios
• Android：minSdkVersion=21，ABI：armeabi-v7a / arm64-v8a
• iOS：iOS 13+（依赖 Vision）
• Harmony：暂不支持（会返回 9010199 not supported on this platform）

安装

插件以 uni_modules 形式使用：

• 在 HBuilderX 插件市场安装，或把 hans-paddle-ocr 目录放到项目 uni_modules/ 下
• 在业务代码里通过 @/uni_modules/hans-paddle-ocr 引入 API

内置模型（随包发布）

默认内置中文 PP-OCRv2 lite 模型（NaiveBuffer .nb）：

• paddleocr/models/ch_PP-OCRv2/det_db.nb
• paddleocr/models/ch_PP-OCRv2/rec_crnn.nb
• paddleocr/models/ch_PP-OCRv2/cls.nb
• paddleocr/labels/ppocr_keys_v1.txt

首次 initPaddleOcr 会把内置资源释放到应用可读写目录，之后优先使用释放后的路径。

说明：

• Android：实际使用上述模型做推理
• iOS：当前识别走 Vision（模型主要为后续全链路 PaddleOCR 预留）

使用示例（uni-app x / uvue）

import {
  initPaddleOcr,
  recognizePaddleOcr,
  releasePaddleOcr,
  setLogEnabled,
  PaddleOcrInitOptions,
  PaddleOcrRecognizeOptions
} from '@/uni_modules/hans-paddle-ocr'

// 可选：关闭插件内部日志（默认开启）
setLogEnabled(false)

initPaddleOcr({
  numThreads: 2,
  enableCls: true,
  success: () => console.log('init ok'),
  fail: (e) => console.error('init fail', e)
} as PaddleOcrInitOptions)

// 典型输入：用 uni.chooseImage 获取临时图片路径（res.tempFilePaths[0]）
// const imagePath = res.tempFilePaths[0]
recognizePaddleOcr({
  imagePath: '/absolute/path/to/image.jpg',
  detLongSize: 960,
  scoreThreshold: 0.5,
  success: (res) => console.log(res.text, res.lines, res.elapsedMs),
  fail: (e) => console.error('rec fail', e)
} as PaddleOcrRecognizeOptions)

releasePaddleOcr()

API 说明

以 uni_modules/hans-paddle-ocr/utssdk/interface.uts 为准：

• initPaddleOcr(options)
• recognizePaddleOcr(options)
• releasePaddleOcr()
• isPaddleOcrInitialized()（同步）
• setLogEnabled(true|false)：控制插件内部 console.info /（Android）原生 console.log 输出（默认开启）
• isLogEnabled()（同步）

initPaddleOcr(options)

• modelDir?: string：模型目录（绝对路径）。为空使用插件内置模型（首次运行会自动释放到可读写目录）
• numThreads?: number：线程数（默认 2）
• enableCls?: boolean：是否启用方向分类（默认 true）
• useGpu?: boolean：是否使用 GPU（默认 false；当前实现可能忽略该参数）
• success/fail/complete

如指定 modelDir，目录下需包含（相对路径）：

• models/ch_PP-OCRv2/det_db.nb
• models/ch_PP-OCRv2/rec_crnn.nb
• models/ch_PP-OCRv2/cls.nb（关闭 enableCls 时可不加载）
• labels/ppocr_keys_v1.txt

recognizePaddleOcr(options)

• imagePath: string：图片路径（file:// 或本地绝对路径；Android 也支持 content://）
• detLongSize?: number：det 输入长边（默认 960）
• scoreThreshold?: number：置信度阈值（默认 0.5，建议范围 0~1）
• success(res)/fail/complete

返回 PaddleOcrResult：

• text: string：全文（按行用 \n 拼接）
• lines: PaddleOcrLine[]：逐行结果（含 text/score/box）
• elapsedMs?: number：耗时（毫秒）

错误码

fail 回调参数为 PaddleOcrFail（符合 uni 错误对象规范），常见 errCode：

• 9010101：not initialized（未初始化）
• 9010102：invalid image path（图片路径无效/不可读）
• 9010103：model load failed（模型加载失败）
• 9010104：recognize failed（识别失败）
• 9010199：unknown / not supported（未知/平台不支持）

注意事项（发布前建议写在插件介绍里）

• 先 initPaddleOcr 再 recognizePaddleOcr；不用时调用 releasePaddleOcr
• 仅支持本地图片（不支持直接传网络 URL）；可配合 uni.chooseImage 获取临时路径
• Android：如果遇到 loadLibrary(paddle_lite_jni) failed，需要使用“自定义基座”运行（标准基座不会包含插件原生 so）

依赖说明

• Android：
  • 本地 AAR：utssdk/app-android/libs/paddle-lite.aar（内置）
  • Maven 依赖：ai.eye2you:opencv-android:4.5.2
• iOS：
  • 系统 Framework：Vision（在 utssdk/app-ios/config.json 中声明）

依赖版本说明

• 内置模型版本：ppocr-v2-lite-2026-01-17（释放目录会写入 paddleocr/version.txt）
• Android：
  • Paddle Lite：随插件内置 paddle-lite.aar（包含 libpaddle_lite_jni.so，ABI：armeabi-v7a / arm64-v8a；AAR 内文件时间：2026-01-17）
  • OpenCV：ai.eye2you:opencv-android:4.5.2（加载 opencv_java4）
• iOS：
  • Vision：iOS 系统框架（随系统版本）
  • deploymentTarget：13（见 utssdk/app-ios/config.json）

致谢与许可

本插件集成/使用了以下开源或系统能力（请按其 License 合规使用）：

• PaddleOCR / Paddle Lite
• OpenCV
• Apple Vision（iOS 系统框架）

开发文档

• UTS 语法：https://uniapp.dcloud.net.cn/tutorial/syntax-uts.html
• UTS 插件：https://uniapp.dcloud.net.cn/plugin/uts-plugin.html