更新记录

1.0.0（2026-09-30）

首次发布

平台兼容性

uni-app(3.8.4)

uni-app x(3.8.4)

其他

离线 OCR（PP-OCRv4）

购买前请先下载测试是否满足需求，遇到问题请在交流群反馈，作者会及时修复，切勿随意差评

插件测试使用方法

1. 选择试用：在 DCloud 插件市场点击「试用」，绑定要试用的项目 appid。
2. 下载到本地项目：选择已绑定的项目后，下载插件到 uni_modules/xiake-uts-ocr/。
3. 引入插件：在需要使用的页面/UTS 文件里引入：

   import { uTSOCRRecognize, startScan, OCR_TYPE } from '@/uni_modules/xiake-uts-ocr'

   如果是 uni-app（Vue3） 项目，请用：

   const ocr = uni.requireNativePlugin('xiake-uts-ocr')
   // ocr.uTSOCRRecognize({...})
   // ocr.startScan({...})

4. 制作自定义基座：点击 发布 → 云打包 → 选择制作基座，等待基座制作完成。本插件含原生 .so 和 OCR 模型，必须打包自定义基座，标准基座无法运行。
5. 运行到手机：点击 运行 → 运行到手机或模拟器 → 运行到 Android App 基座 → 使用自定义基座运行 → 选择手机 → 运行。
6. 卸载旧基座：如果手机上之前安装过该项目的基座，请先卸载旧基座，避免资源/缓存冲突。

简介

基于 PP-OCRv4(NCNN) 的端侧离线 OCR UTS 插件，支持 uni-app 与 uni-app x 的 Android App 端（iOS 暂未实现）。

数据全部本地处理，不联网、不调用任何第三方/云端接口，飞行模式可用，隐私合规。

支持识别：通用中文/英文文本、身份证正反面、车牌、银行卡、营业执照、社保卡、发票、车架号（VIN）、行驶证、手机号、电动车牌、自定义证件。

支持平台

快速开始

方式一：调起内置扫描页（推荐用于证件/卡片）

import { startScan, OCR_TYPE } from '@/uni_modules/xiake-uts-ocr'

startScan({
  params: {
    recognizeType: OCR_TYPE.ID_CARD_FRONT,
    showPhotoAlbum: true,
    scanHintText: '请将身份证正面放入框内',
    complete: (res: string) => {
      const json = JSON.parse(res)
      if (json.status === 'success') {
        console.log('原始文本', json.result.text)
        console.log('身份证号', json.result.idNo)
      } else {
        console.error(json.message)
      }
    }
  }
})

方式二：识别已有图片（推荐用于相册/后端回传）

import { uTSOCRRecognize, OCR_TYPE } from '@/uni_modules/xiake-uts-ocr'

uTSOCRRecognize({
  params: JSON.stringify({
    recognizeType: OCR_TYPE.INVOICE,
    imagePath: '/storage/emulated/0/Pictures/invoice.jpg'
  }),
  complete: (res: string) => {
    const json = JSON.parse(res)
    console.log(json.result)
  }
})

uni-app（Vue3） 项目需把 uTSOCRRecognize / startScan 通过 uni.requireNativePlugin('xiake-uts-ocr') 取出后再调用。

OCR_TYPE 识别类型

从插件导出：

import { OCR_TYPE } from '@/uni_modules/xiake-uts-ocr'

API 说明

startScan(options: StartScanCall)

调起原生扫描页：相机预览 + 取景框 + 手电筒/相册/快门。用户拍照后自动进入识别流程。

type StartScanCall = {
  params: string | object  // 推荐传对象字面量
  complete: (res: string) => void
}

uTSOCRRecognize(options: RecognizeCall)

对本地图片路径做识别，返回 JSON 字符串。

type RecognizeCall = {
  params: string | object
  complete: (res: string) => void
}

params 中必须包含 recognizeType；方式二（JSON.stringify）时建议包含 imagePath。

getBase64FromFilePath(filePath, complete)

把本地图片文件转成 Base64 DataURL 返回。

getBase64FromFilePath('/storage/.../xxx.jpg', (base64: string) => {
  console.log(base64)
})

参数详解（XtOcrOptions）

返回值说明

成功回调返回字符串，解析后结构如下：

{
  "status": "success",
  "result": {
    "text": "识别出的完整原始文本",
    "idNo": "身份证号",
    "name": "姓名",
    "...": "...",
    "blocks": [
      {
        "blockText": "文本块",
        "blockCornerPoints": [{ "x": 0, "y": 0 }, { "x": 100, "y": 0 }, { "x": 100, "y": 30 }, { "x": 0, "y": 30 }],
        "blockBoundingBox": { "left": 0, "top": 0, "right": 100, "bottom": 30 }
      }
    ],
    "costMs": 1234,
    "debug": { "api": "roi", "imgW": 1039, "imgH": 842, "...": "..." }
  }
}

• text：原始 OCR 文本。
• 其余字段为结构化字段（不同 recognizeType 返回不同 key，未识别到返回空字符串）。
• blocks：通用文本的逐块坐标结果。
• costMs：识别耗时（毫秒）。
• debug：调试信息。

常见结构化字段示例

具体字段以真机返回为准；证件因拍照角度/模糊/OCR 噪声，某些字段可能为空字符串。

自定义证件

recognizeType: OCR_TYPE.CUSTOM 时，通过 customizeTags 动态配置要抽取的字段。

uTSOCRRecognize({
  params: JSON.stringify({
    recognizeType: OCR_TYPE.CUSTOM,
    imagePath: '/storage/.../custom_card.jpg',
    customizeTags: JSON.stringify([
      { typeName: '姓名', typeTag: 'name' },
      { typeName: '工号', typeTag: 'workNo' },
      { typeName: '部门', typeTag: 'dept' }
    ])
  }),
  complete: (res: string) => {
    const json = JSON.parse(res)
    console.log(json.result.name)
    console.log(json.result.workNo)
    console.log(json.result.dept)
  }
})

• typeName：文本中的匹配锚点（如「姓名」）。
• typeTag：返回结果中的 key。

图片路径与方向

• imagePath 必须是 Android 本地绝对文件路径，且能被原生 BitmapFactory.decodeFile 直接解码。
• uni.chooseImage 返回的 _doc/... / _downloads/... 或带 file:// 前缀的路径不能直接传入。请先用 plus.io.convertAbsoluteFileSystem 转换：

  uni.chooseImage({ count: 1, success: (res) => {
  let path = res.tempFilePaths[0]
  // #ifdef APP-PLUS
  path = plus.io.convertAbsoluteFileSystem(path)
  // #endif
  uTSOCRRecognize({ params: JSON.stringify({ recognizeType: 0, imagePath: path }), complete: () => {} })
  }})

• startScan 内部落盘的路径已为绝对路径，无需转换。
• 插件会自动读取图片 EXIF 方向标签并转正，竖握横拍照片无需手动旋转。

注意事项

1. 必须打包自定义基座：插件包含原生 .so、NCNN 模型、Kotlin/UTS 源码，标准基座无法运行；修改插件源码或 .so 后需重新制作基座。
2. 插件不热更：index.uts（UTS 层）与 libppocr.so（原生层）都不支持热更新，更新后必须重新打包基座。
3. Android 权限：插件 AndroidManifest.xml 已声明必要权限；如目标系统为 Android 6+，请在业务侧动态申请相机/存储权限。
4. 体积控制：云打包限额 60MB。本插件打包必需内容约 22MB（assets 模型 13MB + libs 8.8MB）。native/obj、native/libs、app-android/obj 等本地构建专用物已移出插件目录，不要把这些文件重新拷回插件，否则会导致超限。
5. 卸载旧基座：同一项目安装新基座前，建议先卸载旧基座，避免缓存/资源冲突导致识别异常。

开源合规

• 识别引擎基于 PaddleOCR PP-OCRv4（Apache-2.0）与 Tencent/NCNN（BSD）。
• 本插件为独立实现，不复制任何闭源二进制或第三方 Demo，可合法发布到 DCloud 插件市场或 MIT 协议分发。