更新记录

2.0.0（2026-09-29） 下载此版本

• 修复 App 包内 OCR 页面路径解析，初始化超时、WebView 创建失败和资源读取失败现在提供阶段化错误信息及自查建议。
• 为依赖加载增加超时诊断；iOS/WKWebView 默认单线程 WASM 推理，降低对跨源隔离和线程能力的依赖。
• 修复识别请求参数直接拼入 JavaScript 的问题，增加图片路径/模板校验、桥接失败处理和引擎销毁时待处理任务清理。
• 统一 SDK 初始化进度对象格式 { stage, message }，组件增加本地选图、预览、识别、进度和错误反馈。
• 校正插件市场平台声明：支持 uni-app App Android/iOS；H5 和小程序不在当前支持范围。
• 增加公共文本清洗、模板专用 OCR 混淆纠正、auto 自动模板识别及统一结构化结果。
• 新增营业执照、增值税发票、护照、车牌模板和敏感字段脱敏工具。
• 自动模板判断返回候选命中原因并对歧义结果回退通用文本；引擎保留护照英文/MRZ 和长字段，超出桥接载荷时明确标记截断。
• 修复拍照后临时文件在 iOS WebView 中读取失败：增加系统隐私声明、临时文件持久化、file:// 特殊字符编码和 DOMException 可读错误提示。
• 对 Android/iOS 本地图片增加 data: URL 回退，兼容 file://、content:// 和系统相册临时路径；识别错误日志现在包含异常类型和具体消息。
• 修正通用文本“提取信息”无上下文的问题：新增 labeledFields 和中文 fieldPairs，示例页面只展示与明确标签匹配的字段，避免将任意数字/日期误显示为业务值。

1.0.0（2026-01-06） 下载此版本

平台兼容性

uni-app(4.87)

lf-OCR 2.0.0

基于 PaddleOCR + ONNX Runtime 的 uni-app App 离线 OCR 插件。推理在设备本地执行，图片、文字和结构化结果不会由插件主动上传。插件包含模型、字典、OpenCV 与 WASM 资源，体积较大；集成时请完整保留 hybrid/html 目录。

支持范围

需要使用 HBuilderX 创建的 uni-app App 项目。不能在浏览器预览、微信开发者工具、普通 H5 页面或不含 App-Plus Runtime 的环境中调用 SDK。项目需保持 uni_modules/lf-OCR 目录结构；不要删除、改名或仅上传 JS 文件。

安装与初始化

通过 HBuilderX 插件市场导入，或将本插件完整目录放入项目 uni_modules/lf-OCR。App 真机运行前，使用 HBuilderX 运行基座；正式发布时重新制作自定义基座/发行包，确保模型和 WASM 静态资源进入包体。

import lfOCR from '@/uni_modules/lf-OCR/index.js';

try {
  await lfOCR.init({
    : ({ stage, message }) => {
      console.log(`[${stage}] ${message}`);
    }
  });
  console.log('OCR 已就绪');
} catch (error) {
  // error.code 可用于分类；message 包含失败阶段和排查建议
  console.error(error.code, error.message);
}

引擎首次初始化会读取本地模型，设备较慢时需要等待。可在应用启动后初始化一次，并在退出相应业务模块时调用 destroy() 释放 WebView 和推理内存。重复调用 init() 会复用正在进行的初始化任务。

识别图片

const result = await lfOCR.recognize(imagePath, 'idCard');
console.log(result.text);       // 可读文本
console.log(result.lines);      // OCR 行数组
console.log(result.duration);  // 推理耗时（毫秒）
console.log(result.valid, result.name, result.idNumber);

也可直接导入 <lf-ocr> 组件进行图片选择和识别；compressed 默认开启图片压缩，组件会在挂载时初始化共享引擎。多页面项目可直接调用 SDK，以便自行控制引擎生命周期和图片来源。

<template>
  <lf-ocr template="idCard" @result="onResult" @error="onError" />
</template>

<script>
import LfOcr from '@/uni_modules/lf-OCR/components/lf-OCR/lf-OCR.vue';

export default {
  components: { LfOcr },
  methods: {
    onResult(result) { console.log(result.text, result.idNumber); },
    onError(error) { console.error(error.message); }
  }
};
</script>

imagePath 必须是字符串，支持 App 可访问的本地文件路径、file:// URL 和 data: URL。相册选择得到的临时路径可直接传入；图片必须仍可读取。远程 HTTP 图片不保证能从本地 WebView 跨域访问，建议先使用 uni.downloadFile 下载至本地。调用方负责通过 uni.chooseImage 等 API 选择图片及配置相应应用权限。

模板为 general（默认）、auto、idCard、bankCard、driverLicense、businessLicense、invoice、passport、licensePlate。***自动识别正反面；驾驶证模板自动判断主页/副页；auto 根据清洗后的关键词和号码格式返回候选类型。模板解析是对 OCR 文字的规则提取，不构成证件真实性验证或身份核验。

2.0 文本增强结果

识别结果保留原始文本，并增加统一的清洗和增强字段：

{
  template: 'idCard',
  type: 'idCard',
  typeName: '身份证',
  rawText: '公 民 身 份 号 码：11010519491231002B',
  cleanedText: '公民身份号码：11010519491231002X',
  normalizedLines: ['公民身份号码：11010519491231002X'],
  corrections: [
    { from: '...B', to: '...X', field: 'idNumber', reason: '纠正证件号码常见 OCR 字符混淆' }
  ],
  fields: { name: '张三', idNumber: '11010519491231002X' },
  warnings: [],
  valid: true
}

• rawText 是引擎回传的原始行文本，适合问题追踪。为保障 App WebView 回调稳定性，极端长文本会限制为 10000 字符并返回 truncated: true 和警告，不能把它当作无上限原图留档。
• cleanedText、normalizedLines 统一全半角、空格、标点、重复行，并按模板修正常见的 O/0、I/1、B/8 混淆。
• corrections 记录每次清洗或纠正，不静默覆盖原文；warnings 说明字段缺失或校验未通过的原因。
• fields 是统一结构化字段，同时保留旧版本的顶层字段，例如 name、idNumber、cardNumber。
• 通用文本的“提取信息”只展示 labeledFields：必须在 OCR 行中发现“电话：”“地址：”“金额：”等明确标签并关联到后面的值；没有标签上下文的孤立数字、日期不会在示例页面中冒充业务字段。旧版 extracted.numbers/dates/phones 仍保留给需要底层正则结果的业务代码，但不建议直接当作字段使用。
• fieldPairs 是结构化模板的展示友好数组，每项包含 key、中文 label 和 value；业务界面可直接循环 fieldPairs，避免自行把英文属性名误当作用户标签。

auto 结果还会返回 typeConfidence、ambiguous、detectionReasons 和 candidates。只有唯一且具有足够强特征的候选才会套用证件模板；一串无法区分用途的数字会回退为 general，由业务方结合候选信息处理。

身份证会校验号码日期和校验位，银行卡会提取格式化卡号并提供 maskedCardNumber，营业执照会校验统一社会信用代码，其他模板会返回可用的字段校验详情。所有校验均为本地格式校验，不是官方验真。

新增模板字段

脱敏工具

import { maskSensitiveValue } from '@/uni_modules/lf-OCR/index.js';

maskSensitiveValue('11010519491231002X', 'idCard');
maskSensitiveValue('6222021234567890123', 'bankCard');

脱敏结果只用于界面展示，不会改变 rawText 或原始字段。

API

init(options?)

初始化离线引擎，返回 Promise。options.onProgress(event) 接收 { stage, message }。常见阶段：opencv、runtime、dictionary、det-model、rec-model、session。

recognize(imagePath, template?)

识别图片，返回 Promise。调用前必须等待 init() 完成。结果包括 OCR 文本/行、清洗修正记录、耗时及对应模板解析出的字段。未知模板、空路径和非字符串路径会立即报错。使用 auto 时会自动选择模板并返回 candidates。

isReady() / destroy()

isReady() 返回引擎就绪状态。destroy() 关闭引擎 WebView、清理待处理调用并释放引用；销毁后再次使用需重新 init()。

解析、校验和格式化工具

index.js 另外导出身份证、银行卡、驾驶证、通用文本解析器，以及 validators.js、formatters.js 中的命名导出。可按需导入：

import { parseIdCard, parseBankCard, parseDriverLicense, parseGeneral } from '@/uni_modules/lf-OCR/index.js';
import { validateIdCard, validateBankCard, formatBankCard } from '@/uni_modules/lf-OCR/index.js';
import { parseEnhanced, detectTemplate } from '@/uni_modules/lf-OCR/index.js';

原始 OCR 文本可以直接传给相应解析函数。解析器和校验器是启发式文本处理工具，业务关键数据必须由业务系统二次核验。

初始化失败自查

异常消息使用 LF_OCR_* 错误码，初始化失败会指出最后阶段和建议。请优先检查：

1. 确认运行目标是 uni-app App 真机，且使用支持 WebAssembly SIMD 的较新 HBuilderX/App Runtime。浏览器、小程序和普通 H5 不受支持。
2. 确认 uni_modules/lf-OCR/hybrid/html/ 完整存在并打入 App 包，尤其是 models/ppocr_det.onnx、models/ppocr_rec.onnx、models/ppocr_keys_v1.txt、ort.min.js、opencv.js 和配套 WASM 文件；注意文件名大小写。
3. App 更新插件静态资源后，重新制作自定义基座或完整发行包。旧基座仍可能运行旧文件。
4. 等待初始化进度；首次加载会创建两个 ONNX 推理会话，内存小或较旧设备可能超时。关闭占用内存的页面后重试。
5. iOS 建议使用 iOS 16.4+ 真机和当前 HBuilderX 生成的基座/发行包验证，不要用模拟器结论替代真机；若错误含 wasm、SIMD，升级 HBuilderX 与 iOS 版本后重新打包。
6. 识别失败时确认传入的是可访问的本地图片路径、图片未被清理，并由宿主应用正确请求相册/文件权限。

插件本地运行不依赖网络。网络错误提示通常表示本地资源读取/打包问题，而不是需要开放联网权限。

拍照/选图失败排查

• chooseImage:fail 且 code: 0 通常是宿主 App 没有获得相机/照片权限、用户拒绝授权、设备相机被占用或系统选择器异常。请先到系统设置开启权限，并重新进入页面；用户主动取消选择不应视为 OCR 错误。
• 本示例已使用回调兼容写法并将相机/相册错误转换为可读提示。若使用自定义页面，请不要只打印 [object Object]，应读取 errMsg 和 code。
• iOS 必须在 manifest.json 的 app-plus.distribute.ios.privacyDescription 配置 NSCameraUsageDescription、NSPhotoLibraryUsageDescription，修改后重新制作自定义基座或发行包；仅热刷新 JS 不会更新系统隐私声明。
• 插件市场包不会覆盖宿主应用的 manifest.json。宿主项目可按实际用途加入：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSCameraUsageDescription": "用于拍摄证件或文字图片并进行本地离线 OCR 识别",
          "NSPhotoLibraryUsageDescription": "用于选择证件或文字图片并进行本地离线 OCR 识别"
        }
      }
    }
  }
}

• LF_OCR_IMAGE_PATH_FAILED 或 LF_OCR_RECOGNIZE_FAILED 中包含 DOMException 时，通常是相机临时文件路径已失效、路径含未编码特殊字符或 WebView 无权读取。2.0.0 会优先持久化示例页面的临时图片、规范化 file:///content:// URL，并尝试将本地图片转换为 data: URL；仍失败时请重新拍照后立即识别。
• Android/iOS 真机不要直接复用旧基座验证权限配置。清理旧 App 或重新安装新基座后再授权，避免系统保留旧权限状态。

隐私与应用权限

OCR 图像处理和规则解析均在设备 WebView 中完成；插件没有联网上传、统计或主动申请相机/相册权限的逻辑。由宿主应用负责选择/拍摄图片并按其实际权限用途声明。不要将 OCR 识别结果作为唯一的身份认证或合规依据。

发布与升级

• 从 1.0.0 升级的破坏性变更及迁移方式见 UPGRADE.md。
• 版本改动记录见 CHANGELOG.md。