更新记录

1.0.3（2026-06-03）

• 初始版本。
• 支持本地图片 OCR 识别。
• 支持相册选图后识别、拍照后识别。
• 支持返回全文、文本块、文本行与坐标信息。

平台兼容性

uni-app(4.81)

uni-app x(4.82)

hl-local-ocr

hl-local-ocr 是一个纯端侧 OCR UTS 插件，统一封装 Android、iOS、HarmonyOS 三端本地文字识别能力，适用于 uni-app / uni-app x 的相册识别、拍照识别和本地图片路径识别。

平台支持

功能特性

• 纯端侧识别，不依赖后端服务
• 不需要第三方云 OCR API
• 支持相册图片识别
• 支持拍照后识别
• 支持直接传本地图片路径识别
• 支持返回全文文本
• 支持返回文本块坐标
• 支持返回文本行坐标
• 支持中文、英文、中英混合
• 支持 fast / accurate 模式
• 统一 uni-app / uni-app x 调用方式

典型场景

• 图片文字提取
• 拍照录单
• 文档拍照录入
• 快递单号、订单号、设备编号识别
• 设备铭牌、标签、票据识别
• OCR 文本高亮与定位展示

Demo 页面

项目内已提供前端调用示例：

pages/local-ocr-demo/index

Demo 包含：

• 相册识别
• 拍照识别
• 语言 / 模式 / 场景切换
• 全文展示
• 文本块坐标展示
• 文本行坐标展示
• 路径自动兼容处理

快速开始

推荐使用命名空间导入：

import * as LocalOcr from '@/uni_modules/hl-local-ocr'

相册识别示例：

import * as LocalOcr from '@/uni_modules/hl-local-ocr'

uni.chooseImage({
  count: 1,
  sourceType: ['album'],
  success: (res) => {
    const path = res.tempFilePaths[0]

    LocalOcr.recognizeImage({
      path,
      language: 'zh-en',
      mode: 'accurate',
      scene: 'general',
      returnLines: true,
      autoRotate: true,
      normalizeWhitespace: true,
      mergeLineBreaks: false,
      maxSide: 0,
      cropRect: null,
      extractTypes: null
    }, (result) => {
      if (result.code === 0 && result.data != null) {
        console.log('全文', result.data.text)
        console.log('文本块', result.data.blocks)
      } else {
        console.log('识别失败', result.message)
      }
    })
  }
})

API

isSupported()

判断当前平台是否支持本地 OCR。

const supported = LocalOcr.isSupported()

getEngineInfo()

获取当前平台 OCR 引擎信息。

const info = LocalOcr.getEngineInfo()

返回示例：

{
  platform: 'android',
  engine: 'Google ML Kit',
  onDevice: true,
  languages: ['zh', 'en', 'zh-en'],
  modes: ['fast', 'accurate'],
  features: ['fullText', 'blockBounds', 'lineBounds', 'autoRotate', 'cropRect']
}

recognizeImage(options, callback)

识别指定本地图片路径。

LocalOcr.recognizeImage(options, callback)

options 参数：

chooseImageAndRecognize(options, callback)

兼容导出接口。当前推荐前端自行调用 uni.chooseImage 后，再调用 recognizeImage。

takePhotoAndRecognize(options, callback)

兼容导出接口。当前推荐前端自行调用拍照后，再调用 recognizeImage。

返回结构

回调返回 LocalOcrResult：

{
  code: 0,
  message: '识别成功',
  data: {
    rawText: '...',
    text: '...',
    blocks: [],
    lines: [],
    matches: [],
    hasText: true,
    blockCount: 3,
    lineCount: 8,
    imageWidth: 1080,
    imageHeight: 1920,
    processedWidth: 1080,
    processedHeight: 1920,
    duration: 120,
    language: 'zh-en',
    mode: 'accurate',
    source: 'direct',
    engine: 'Google ML Kit',
    path: '...',
    scene: 'general',
    autoRotated: false,
    scaleApplied: 1,
    cropRect: null
  }
}

code 约定：

blocks 文本块字段：

lines 文本行字段：

rect 坐标字段：

{
  left: 0,
  top: 0,
  right: 100,
  bottom: 40,
  width: 100,
  height: 40
}

路径说明

推荐直接传 uni.chooseImage 或拍照返回的本地路径。

支持路径类型：

• Android content://...
• Android / iOS / HarmonyOS file://...
• HarmonyOS 相册 file://media/...
• 原生绝对路径，例如 /storage/emulated/0/.../a.jpg
• 5+ 临时路径，例如 _doc/...，建议前端先用 plus.io.convertLocalFileSystemURL 转换

不建议直接传：

• 网络 URL
• base64
• 前端相对路径
• @/static/... 这类源码资源路径

5+ 路径转换示例：

const absolutePath = plus.io.convertLocalFileSystemURL('_doc/ocr/test.jpg')

注意事项

• OCR 为端侧能力，不会上传图片或识别文本。
• 首次调用系统 OCR 能力可能略慢。
• 大图识别建议使用 fast 模式或设置合理 maxSide。
• 做文本高亮时，请使用 imageWidth / imageHeight 与 rect 按比例换算到前端图片展示尺寸。
• 若前端展示图片使用了 widthFix、裁剪或等比缩放，需要同步处理坐标映射比例。