更新记录

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

平台兼容性

uni-app(4.87)

lf-OCR 离线识别插件

基于 PaddleOCR 的纯离线 OCR 识别插件，无需联网，隐私安全

✨ 特性

• 🚀 高性能 - 基于 PaddleOCR，识别速度快、准确率高
• 🔒 纯离线 - 所有资源本地化，无需网络即可使用
• 🎯 中文优化 - 专为中文场景优化，识别效果出色
• 📱 多平台 - 支持 H5、App (Android/iOS)
• 证件识别 - 内置身份证、银行卡、驾驶证模板
• ✅ 智能验证 - 自动验证证件有效性，返回详细验证信息
• 🔄 自动识别 - 智能判断证件正反面，无需手动指定
• 🔧 易于扩展 - 支持自定义模型和识别模板

📦 安装

uni_modules 方式（推荐）

1. 在 HBuilder 插件市场搜索 lf-OCR
2. 点击导入到项目

手动安装

将 uni_modules/lf-OCR 复制到项目的 uni_modules 目录

📱 平台兼容性

🎮 使用方式

方式一：使用 SDK（推荐）

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

// 初始化
await lfOCR.init({
  : (msg) => console.log("加载进度:", msg),
});

// 识别图片
const result = await lfOCR.recognize(imagePath, "idCard");
console.log("识别结果:", result);

方式二：使用组件

<template>
  <view class="page">
    <lf-ocr @result="onResult" @error="onError" />
  </view>
</template>

<script>
export default {
  methods: {
    onResult(data) {
      console.log("识别结果:", data.text);
      console.log("解析数据:", data.parsedData);
      console.log("是否有效:", data.parsedData.valid);
    },
    onError(err) {
      console.error("识别失败:", err);
    },
  },
};
</script>

方式三：使用 web-view

<template>
  <web-view
    src="/uni_modules/lf-OCR/hybrid/html/ocr.html"
    @message="onMessage"
  />
</template>

<script>
export default {
  methods: {
    onMessage(event) {
      const data = event.detail.data[0];
      if (data.type === "OCR_RESULT") {
        console.log("识别结果:", data.data);
      }
    },
  },
};
</script>

🔧 API 文档

SDK 方法

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

// 初始化引擎
await lfOCR.init(options);

// 识别图片
// template: "general" | "idCard" | "bankCard" | "driverLicense"
const result = await lfOCR.recognize(imagePath, template);

// 检查引擎状态
const isReady = lfOCR.isReady();

// 销毁引擎
lfOCR.destroy();

模板解析器

import {
  // 身份证
  parseIdCard,
  parseIdCardFront,
  parseIdCardBack,
  detectIdCardSide,
  // 银行卡
  parseBankCard,
  // 驾驶证
  parseDriverLicense,
  // 通用
  parseGeneral,
} from "@/uni_modules/lf-OCR/index.js";

校验工具

import {
  validateIdCard,
  validateBankCard,
  validateDriverLicenseNumber,
  validatePhone,
  validateEmail,
  validateLicenseClass,
} from "@/uni_modules/lf-OCR/index.js";

格式化工具

import {
  formatDate,
  formatAmount,
  formatPhone,
  formatBankCard,
  formatDuration,
} from "@/uni_modules/lf-OCR/index.js";

📋 返回数据格式

身份证正面

{
  name: "张三",
  gender: "男",
  ethnicity: "汉族",
  birthDate: "1990年01月01日",
  address: "北京市朝阳区某某街道123号",
  idNumber: "110101199001011234",
  valid: true,
  side: "front",
  validationDetails: { ... }
}

身份证背面

{
  authority: "北京市***朝阳分局",
  validPeriod: {
    start: "2015.01.01",
    end: "2025.01.01"  // 或 "长期"
  },
  valid: true,
  isExpired: false,
  side: "back"
}

银行卡

{
  cardNumber: "6222021234567890123",
  cardNumberFormatted: "6222 0212 3456 7890 123",
  bankName: "中国工商银行",
  cardType: "借记卡",
  expiryDate: "12/25",
  valid: true,
  isExpired: false
}

驾驶证

{
  licenseNumber: "123456789012345678",
  name: "张三",
  gender: "男",
  nationality: "中国",
  address: "北京市朝阳区某某街道123号",
  birthDate: "1990-01-01",
  firstIssueDate: "2010-01-01",
  licenseClass: "C1",
  licenseClassDesc: "小型汽车",
  validPeriod: {
    start: "2020.01.01",
    end: "2026.01.01"
  },
  valid: true,
  page: "main"  // 或 "sub"
}

💡 使用示例

身份证识别

import { parseIdCard, validateIdCard } from "@/uni_modules/lf-OCR/index.js";

// 自动判断正反面
const result = parseIdCard(ocrText);

if (result.side === "front") {
  console.log("姓名:", result.name);
  console.log("身份证号:", result.idNumber);

  // 验证身份证号
  const validation = validateIdCard(result.idNumber);
  if (validation.valid) {
    console.log("年龄:", validation.info.age);
    console.log("性别:", validation.info.gender);
  }
} else {
  console.log("签发机关:", result.authority);
  console.log("有效期:", result.validPeriod);
}

银行卡识别

import { parseBankCard } from "@/uni_modules/lf-OCR/index.js";

const result = parseBankCard(ocrText);

if (result.valid) {
  console.log("卡号:", result.cardNumberFormatted);
  console.log("银行:", result.bankName);
  console.log("卡类型:", result.cardType);

  if (result.isExpired) {
    console.log("银行卡已过期");
  }
}

驾驶证识别

import { parseDriverLicense } from "@/uni_modules/lf-OCR/index.js";

const result = parseDriverLicense(ocrText);

if (result.valid) {
  console.log("姓名:", result.name);
  console.log("准驾车型:", result.licenseClass, result.licenseClassDesc);
  console.log("有效期:", result.validPeriod);
}

🔧 扩展开发

更换 OCR 模型

插件使用 PaddleOCR 的 ONNX 模型，可以更换为其他兼容模型：

hybrid/html/models/
├── ppocr_det.onnx      # 文字检测模型
├── ppocr_rec.onnx      # 文字识别模型
└── ppocr_keys_v1.txt   # 字典文件

更换步骤：

1. 准备 ONNX 格式的检测模型和识别模型
2. 替换 hybrid/html/models/ 目录下的对应文件
3. 如使用不同字典，同时替换 ppocr_keys_v1.txt

新增识别模板

在 js_sdk/templates/ 目录下创建新模板：

// js_sdk/templates/passport.js
export function parsePassport(text, lines = []) {
  const result = {
    name: "",
    passportNumber: "",
    nationality: "",
    birthDate: "",
    expiryDate: "",
    valid: false,
  };

  // 实现字段提取逻辑
  // ...

  return result;
}

然后在入口文件中导出：

// index.js
export { parsePassport } from "./js_sdk/templates/passport.js";

添加新的校验规则

在 js_sdk/utils/validators.js 中添加：

export function validatePassportNumber(passportNumber) {
  const result = {
    valid: false,
    message: "",
  };

  // 实现校验逻辑
  if (/^[A-Z]\d{8}$/.test(passportNumber)) {
    result.valid = true;
    result.message = "护照号码格式正确";
  } else {
    result.message = "护照号码格式不正确";
  }

  return result;
}

⚠️ 注意事项

1. 纯离线运行 - 所有模型和依赖已本地化，无需网络即可使用
2. 图片质量 - 清晰的图片识别效果更好，建议分辨率 ≥ 720p
3. 证件验证 - 插件会验证证件格式和有效性，但重要场景请结合后端验证
4. 隐私保护 - 所有识别在本地完成，不会上传任何数据到服务器
5. 资源大小 - 插件包含 OCR 模型文件，整体约 35MB

🔍 常见问题

识别准确率如何提高？

• 确保证件图片清晰、光线充足
• 避免反光、阴影
• 证件尽量占满取景框
• 保持证件水平，避免倾斜

如何判断证件是否有效？

const result = parseIdCard(ocrText);
if (result.valid) {
  console.log("有效证件");
} else {
  console.log("验证详情:", result.validationDetails);
}

支持的证件类型

• ✅ 身份证（正反面）
• ✅ 银行卡
• ✅ 驾驶证（主页、副页）
• ✅ 通用文字识别

如何添加新证件类型？

参考「扩展开发」章节，在 js_sdk/templates/ 目录下创建新模板文件。