更新记录

1.0.1（2026-07-11）

• 经典 uni-app Vue2、Vue3 改为直接导入 UTS API，不再依赖 uni.requireNativePlugin。
• 市场交付统一为单一 UTS 插件，nativeplugin 不再作为发布包。
• 修正平台声明：经典 uni-app 支持 Vue2/Vue3 的 Android、iOS；HarmonyOS 付费加密版仅支持 uni-app x。
• 移除容易误导的 uni_modules.encrypt，付费 UTS 源码由 DCloud 插件市场自动加密。
• 补充付费加密后的云端编译、传统云打包和公开 interface.uts 说明。
• 明确付费 HarmonyOS 版本要求 HBuilderX 4.81+，并统一从插件根入口导入公开类型。
• 明确经典 uni-app Vue3 不等于 uni-app x：Vue3 支持范围为 Android、iOS，普通付费加密版 HarmonyOS 仅支持 uni-app x。

1.0.0（2026-07-10）

• 首次发布 Android、iOS、HarmonyOS 三端离线 OCR UTS 插件。
• Android / iOS 使用 NCNN 原生推理，HarmonyOS 使用 MindSpore Lite 原生推理。
• 支持模型初始化、文字检测识别、方向预处理、资源释放和模型就绪状态查询。
• 支持身份证号、车牌号、购物卡/长数字等常见格式候选提取。
• 配套 Demo 提供经典 uni-app uni.requireNativePlugin('LiteOCRv6') 兼容包与调用示例。

平台兼容性

uni-app(4.81)

uni-app x(4.81)

LiteOCRv6 离线文字识别

LiteOCRv6 是面向 uni-app / uni-app x 的端侧离线 OCR UTS 插件。图片解码、文字检测、文字识别和规则候选提取均在设备本地完成，不会上传业务图片或识别结果。

能力与平台

• Android、iOS、HarmonyOS 真机离线 OCR
• 经典 uni-app Vue2、Vue3 与 uni-app x 共用同一个 UTS API 插件
• 通用文字检测与识别：det_rec
• 仅检测文字区域：det_only
• 将整张图片作为一个文字区域识别：rec_only
• 手动旋转、图片方向处理和 OCR 输入图预处理
• 身份证号、车牌号、购物卡号/长数字、手机号、金额、日期候选提取
• 内置 tiny 模型，也可通过 modelDir 使用与插件格式匹配的自定义模型

插件不包含拍照 UI、相册 UI、二维码/条码识别。业务侧可先通过 uni.chooseImage、相机插件或其他方式取得本地图片，再将路径传入本插件。

推荐省略 runtimeSet，插件会按当前平台选择正确默认值。如果显式传值，Android/iOS 使用 ncnn，HarmonyOS 使用 nativeOptimized。

HarmonyOS 当前市场版本请使用 uni-app x，并使用 HBuilderX 4.81 或更高版本进行云端编译。

安装和运行

1. 从 DCloud 插件市场导入 xiaoba777-liteocr-v6 到工程 uni_modules。
2. 在宿主工程中声明拍照、相册等业务实际使用的权限。
3. 从 @/uni_modules/xiaoba777-liteocr-v6 导入公开 API；经典 uni-app 不需要 uni.requireNativePlugin()。
4. 开发调试时重新制作包含插件原生依赖的基座或重新打包，并使用真机运行。

UTS 插件调用方式

LiteOCRv6 是 UTS API 插件，不需要使用 uni.requireNativePlugin()。OCR 接口、参数和返回值在不同工程中保持一致，区别只在页面脚本类型：

• 经典 uni-app Vue2/Vue3：在 .vue 的普通 <script> 中导入。
• uni-app x：在 .uvue 的 <script lang="uts"> 中导入。

import {
  initModel,
  recognizeImage,
  releaseModel
} from '@/uni_modules/xiaoba777-liteocr-v6'

所有公开函数和类型均从插件根路径导入，不要直接依赖 utssdk 内部文件。

构建说明

• Android、iOS 支持经典 uni-app Vue2/Vue3 和 uni-app x，请重新制作包含插件的自定义基座或云端安装包。
• HarmonyOS 当前支持 uni-app x，要求 HBuilderX 4.81 或更高版本并使用云端编译。
• 更新插件版本或原生产物后，请重新编译基座或安装包，并在真机上测试。

推荐调用顺序

initModel() -> recognizeImage() 可重复调用多次 -> releaseModel()

• 页面进入或首次使用时初始化一次模型。
• 初始化成功后可以连续识别多张图片，不需要每张图片都重新初始化。
• 页面退出或确定不再使用 OCR 时释放模型。
• 如果再次调用 initModel 切换模型，应等待最新一次初始化回调成功后再识别。

导入公开接口

import {
  initModel,
  recognizeImage,
  prepareImageForOcr,
  recognizeShoppingCard,
  recognizeIdCard,
  recognizeLicensePlate,
  extractEntities,
  downloadModel,
  isModelReady,
  releaseModel
} from '@/uni_modules/xiaoba777-liteocr-v6'

完整 UTS 类型定义位于 utssdk/interface.uts。

基础调用示例

import {
  initModel,
  recognizeImage,
  releaseModel,
  InitModelResult,
  RecognizeImageResult
} from '@/uni_modules/xiaoba777-liteocr-v6'

initModel({
  modelTier: 'tiny',
  threadNum: 2,
  runCls: false
}, (initResult: InitModelResult) => {
  if (initResult.code != 0) {
    console.error(`模型加载失败：${initResult.message}`)
    return
  }

  recognizeImage({
    imagePath: '/path/to/image.jpg',
    maxSideLen: 0,
    runMode: 'det_rec',
    extractEntities: true
  }, (ocrResult: RecognizeImageResult) => {
    if (ocrResult.code != 0) {
      console.error(`识别失败：${ocrResult.message}`)
      return
    }

    console.log('文字行：', ocrResult.results)
    console.log('格式候选：', ocrResult.entities)
  })
})

// 页面退出或不再使用 OCR 时调用
releaseModel((result) => {
  console.log(result.code, result.message)
})

公开接口说明

1. initModel(options, callback)

加载检测模型、识别模型、字符字典和配置文件。必须初始化成功后才能调用图片识别接口。

参数

自定义模型目录结构

Android / iOS 的 NCNN 模型目录：

modelDir/
├── det/
│   ├── inference.param
│   └── inference.bin
└── rec/
    ├── inference.param
    ├── inference.bin
    ├── charset.txt
    └── ppocr.cfg

HarmonyOS 的 MindSpore Lite 模型目录：

modelDir/
├── det/
│   └── inference.ms
└── rec/
    ├── inference.ms
    ├── charset.txt
    └── ppocr.cfg

识别模型、charset.txt 和 ppocr.cfg 必须来自同一套导出结果。插件会校验识别输出类别数与字典映射数量；不匹配时拒绝初始化并返回 code = -4，避免产生“数字看似正确、中文索引错位”的伪识别结果。

初始化成功示例

{
  code: 0,
  message: 'ok',
  tier: 'tiny',
  runtimeSet: 'nativeOptimized'
}

runtimeSet 会随平台变化。例如 Android/iOS 通常返回 ncnn。

模型字典不匹配示例

{
  code: -4,
  message: '模型校验失败：识别模型输出 7000 类，但字典映射需要 6906 类',
  tier: 'custom-v1',
  runtimeSet: 'ncnn'
}

2. recognizeImage(options, callback)

通用 OCR 接口。输入本地图片路径或 Base64，返回文字、置信度、文字框、耗时、图片旋转信息和可选的规则候选。

参数

正常通过本机相机拍摄并保留方向信息的图片，无需设置 rotate。仅当图片并非本机直接拍摄，或经过转存、压缩等处理后已丢失 EXIF/方向信息，并出现识别方向错误时，才手动传入旋转角度。

imagePath 与 imageBase64 至少提供一个。两者同时提供时建议以 imagePath 为准，不要传入两个不同图片。

runMode 解释

返回字段

best 的实际类型是 OCREntityCandidate | null。上表中的竖线表示联合类型。

OCRResultItem

{
  text: '***：***',
  confidence: 0.982,
  points: [[42, 76], [418, 76], [418, 126], [42, 126]]
}

• text：识别出的文字。
• confidence：模型置信度，通常在 0~1 之间，仅适合排序和阈值参考，不代表业务真实性。
• points：文字框四个顶点的 [x, y] 坐标。坐标对应实际完成方向处理后的 OCR 输入图。

完整识别结果示例

以下数据仅用于说明字段结构，实际文字、坐标、置信度和耗时会随图片、设备和平台变化：

{
  code: 0,
  message: 'ok',
  scene: 'auto',
  elapsedMs: 286,
  detMs: 91,
  recMs: 173,
  appliedRotation: 0,
  orientationSource: 'nativeExif',
  results: [
    {
      text: '订单日期：2026-07-10',
      confidence: 0.987,
      points: [[38, 42], [402, 42], [402, 88], [38, 88]]
    },
    {
      text: '***：138 0013 8000',
      confidence: 0.981,
      points: [[40, 104], [438, 104], [438, 152], [40, 152]]
    },
    {
      text: '合计：￥128.50',
      confidence: 0.976,
      points: [[42, 166], [308, 166], [308, 214], [42, 214]]
    }
  ],
  entities: {
    idCards: [],
    plates: [],
    cardNumbers: [],
    phones: [
      {
        value: '***',
        normalized: '***',
        sourceIndex: 1,
        text: '***：138 0013 8000',
        confidence: 0.981,
        points: [[40, 104], [438, 104], [438, 152], [40, 152]]
      }
    ],
    amounts: [
      {
        value: '￥128.50',
        normalized: '￥128.50',
        sourceIndex: 2,
        text: '合计：￥128.50',
        confidence: 0.976,
        points: [[42, 166], [308, 166], [308, 214], [42, 214]]
      }
    ],
    dates: [
      {
        value: '2026-07-10',
        normalized: '2026-07-10',
        sourceIndex: 0,
        text: '订单日期：2026-07-10',
        confidence: 0.987,
        points: [[38, 42], [402, 42], [402, 88], [38, 88]]
      }
    ]
  },
  candidates: [
    { value: '***', normalized: '***', sourceIndex: 1 },
    { value: '￥128.50', normalized: '￥128.50', sourceIndex: 2 },
    { value: '2026-07-10', normalized: '2026-07-10', sourceIndex: 0 }
  ],
  best: {
    value: '***',
    normalized: '***',
    sourceIndex: 1
  }
}

det_only 结果示例

{
  code: 0,
  message: 'ok',
  detMs: 78,
  recMs: 0,
  results: [
    {
      text: '',
      confidence: 0.94,
      points: [[30, 40], [420, 40], [420, 96], [30, 96]]
    }
  ]
}

错误结果示例

模型未初始化或图片无法读取时：

{
  code: -1,
  message: '模型未初始化',
  elapsedMs: 0,
  detMs: 0,
  recMs: 0,
  results: []
}

模型与字符字典不匹配时：

{
  code: -4,
  message: '识别模型输出类别与字典映射不一致',
  elapsedMs: 0,
  detMs: 0,
  recMs: 0,
  results: []
}

3. prepareImageForOcr(options, callback)

根据 rotate、imageOrientation 和 maxSideLen 准备与 OCR 实际输入方向一致的图片。适合在页面上预览“模型真正看到的图片”，或将处理后的图片用于调试。

参数与 recognizeImage 中同名字段含义一致，但不需要 runMode、scene 和 extractEntities。

prepareImageForOcr({
  imagePath: '/path/to/photo.jpg',
  rotate: 90,
  maxSideLen: 1280
}, (result) => {
  if (result.code == 0) {
    console.log('处理后图片：', result.imagePath)
    console.log(`尺寸：${result.width} x ${result.height}`)
  }
})

返回示例：

{
  code: 0,
  message: 'ok',
  imagePath: '/app/cache/liteocrv6/prepared-20260710.jpg',
  width: 960,
  height: 1280,
  appliedRotation: 90,
  orientationSource: 'manual',
  elapsedMs: 24
}

平台说明：

• iOS、HarmonyOS 会生成处理后的临时图片路径。
• Android 当前使用 AAR 内部方向处理，prepareImageForOcr 为兼容透传，可能直接返回原路径且不提供宽高；实际识别仍会正确应用方向参数。

4. 场景快捷识别接口

以下三个接口参数和返回结构都与 recognizeImage 相同，但会固定 scene 并启用候选提取：

购物卡号示例

recognizeShoppingCard({
  imagePath: '/path/to/card.jpg',
  runMode: 'det_rec'
}, (result) => {
  if (result.code == 0) {
    const best = result.best
    if (best != null) {
      console.log('最佳卡号：', best.normalized)
    }
  }
})

返回示例：

{
  code: 0,
  message: 'ok',
  scene: 'shoppingCard',
  results: [
    {
      text: '2336 3760 3106 6276095',
      confidence: 0.991,
      points: [[24, 38], [536, 38], [536, 104], [24, 104]]
    }
  ],
  candidates: [
    {
      value: '2336376031066276095',
      normalized: '2336376031066276095',
      sourceIndex: 0,
      text: '2336 3760 3106 6276095',
      confidence: 0.991,
      points: [[24, 38], [536, 38], [536, 104], [24, 104]]
    }
  ],
  best: {
    value: '2336376031066276095',
    normalized: '2336376031066276095',
    sourceIndex: 0
  }
}

身份证号和车牌号调用示例

recognizeIdCard({ imagePath: '/path/to/id-card.jpg' }, (result) => {
  console.log('身份证号候选：', result.candidates)
})

recognizeLicensePlate({ imagePath: '/path/to/plate.jpg' }, (result) => {
  console.log('车牌号候选：', result.candidates)
})

候选格式示例：

// 身份证号，仅作格式示例
{
  value: '11010119900101123X',
  normalized: '11010119900101123X',
  sourceIndex: 0
}

// 车牌号，仅作格式示例
{
  value: '粤B12345',
  normalized: '粤B12345',
  sourceIndex: 0
}

5. extractEntities(options, callback)

只对已有文本或 OCR 结果执行规则提取，不会重新运行 OCR。适合对服务器文本、手工输入文本或已缓存的 OCR 结果进行二次筛选。

输入字段

results 的优先级高于 text 和 texts。

使用示例

extractEntities({
  scene: 'auto',
  texts: [
    '手机号：138 0013 8000',
    '身份证：11010119900101123X',
    '车牌：粤B12345',
    '金额：￥128.50',
    '日期：2026-07-10'
  ]
}, (result) => {
  console.log(JSON.stringify(result.entities))
})

返回示例：

{
  code: 0,
  message: 'ok',
  scene: 'auto',
  entities: {
    idCards: [
      { value: '11010119900101123X', normalized: '11010119900101123X', sourceIndex: 1 }
    ],
    plates: [
      { value: '粤B12345', normalized: '粤B12345', sourceIndex: 2 }
    ],
    cardNumbers: [
      { value: '11010119900101123', normalized: '11010119900101123', sourceIndex: 1 }
    ],
    phones: [
      { value: '***', normalized: '***', sourceIndex: 0 }
    ],
    amounts: [
      { value: '￥128.50', normalized: '￥128.50', sourceIndex: 3 }
    ],
    dates: [
      { value: '2026-07-10', normalized: '2026-07-10', sourceIndex: 4 }
    ]
  },
  candidates: [
    { value: '11010119900101123', sourceIndex: 1 },
    { value: '11010119900101123X', sourceIndex: 1 },
    { value: '粤B12345', sourceIndex: 2 },
    { value: '***', sourceIndex: 0 },
    { value: '￥128.50', sourceIndex: 3 },
    { value: '2026-07-10', sourceIndex: 4 }
  ],
  best: {
    value: '11010119900101123',
    sourceIndex: 1
  }
}

候选规则说明

• cardNumbers：去除空格、短横线等分隔符后，提取 12～24 位数字。
• phones：提取 11 位、以 1 开头且第二位为 3～9 的号码。
• idCards：提取前 17 位为数字、最后一位为数字或 X 的 18 位字符串。
• plates：提取以省份简称开头、第二位为大写字母、长度为 7～8 位的字符串。
• amounts：提取带 ¥、￥，或位于“元”之前的数字金额。
• dates：提取包含 8 位数字且年份以 19 或 20 开头的日期样式文本。

这些结果只是快速规则候选，不执行身份证校验位、银行卡 Luhn 校验、手机号归属、车牌真实性或日期合法性校验。正式业务仍应在候选结果上增加自己的校验规则。

6. downloadModel(options, progress, callback)

用于下载业务指定的模型文件。当前平台状态：

参数

Android 当前未配置内置远程模型地址，因此仅传 modelTier 不会自动下载；必须同时提供 detUrl 与 recUrl。下载完成后仍会执行模型与字典契约校验。

downloadModel({
  modelId: 'custom-v1',
  detUrl: 'https://example.com/liteocr/det.zip',
  recUrl: 'https://example.com/liteocr/rec.zip',
  force: false
}, (event) => {
  console.log(`下载进度：${event.progress}%`)
}, (result) => {
  if (result.code == 0) {
    console.log('模型目录：', result.localDir)

    initModel({
      modelTier: 'custom-v1',
      modelDir: result.localDir
    }, (initResult) => {
      console.log(initResult.code, initResult.message)
    })
  } else {
    console.error(result.message)
  }
})

下载成功示例：

{
  code: 0,
  message: 'ok',
  localDir: '/app/files/ppocr_models/custom-v1'
}

7. isModelReady(tier)

同步查询指定模型资源是否已经可用。

const tinyReady = isModelReady('tiny')
console.log('tiny 是否可用：', tinyReady)

返回值：

true

该接口用于快速检查模型文件是否存在且满足基本要求，不替代 initModel。真正开始识别前仍应以 initModel 的回调结果为准。

8. releaseModel(callback)

释放当前 OCR 引擎和模型资源。

releaseModel((result) => {
  console.log(result)
})

返回示例：

{
  code: 0,
  message: 'released'
}

释放后再次识别前必须重新调用 initModel。

数据结构说明

OCREntityCandidate

{
  value: '***',
  normalized: '***',
  sourceIndex: 1,
  text: '***：138 0013 8000',
  confidence: 0.981,
  points: [[40, 104], [438, 104], [438, 152], [40, 152]]
}

OCREntities

{
  idCards: [],
  plates: [],
  cardNumbers: [],
  phones: [],
  amounts: [],
  dates: []
}

每个字段都是 OCREntityCandidate[]。未命中时为空数组，不代表 OCR 失败。

常见错误码

不同平台的底层错误可能使用同一错误码表达不同细节，应始终以 message 为主要诊断信息。

使用建议

1. 首次接入先使用内置 tiny，确认三端调用链正常后再接自定义模型。
2. 普通图片优先使用 imagePath，避免大尺寸 Base64 增加内存占用。
3. maxSideLen 先保持 0；只有性能或小字识别需要调优时再对比 960/1280/1600/1920。
4. 已裁剪的单行文字可尝试 rec_only，完整文档使用 det_rec。
5. 规则候选用于缩小范围，不能替代业务真实性校验。
6. 更换模型时必须同时更换配套的识别字典和配置文件。
7. 更新插件原生产物后，应清理 HBuilderX 缓存、卸载旧 App，并重新制作自定义基座或正式包。

权限与隐私

• 插件不会采集、存储或上传用户图片、识别文本或设备信息。
• 插件本身不主动弹出相机或相册权限；宿主业务使用拍照、选图能力时需自行声明权限。
• 只有业务主动调用 downloadModel 时才会访问开发者传入的模型下载地址。