更新记录

1.0.0（2026-02-26）

初始版本发布

平台兼容性

uni-app(3.6.17)

uni-app x(3.6.18)

zy-hwocr - 离线证件识别

基于华为HMS ML Kit开发的UTS插件，提供高效、准确的证件识别服务。

功能特性

• ✅ 身份证识别 - 支持中国第二代身份证正反面识别（视频流/图片识别）
• ✅ 银行卡识别 - 支持银行卡号、有效期、发卡行等信息识别（视频流识别）
• ✅ 通用卡证识别 - 支持港澳通行证、回乡证、驾驶证等任意固定版式卡证识别
• 🔒 隐私安全 - 识别数据仅用于本地处理，不上传至服务器
• 🎯 高精度识别 - 基于华为HMS ML Kit引擎，识别准确率高达99%

平台支持

注意：本插件目前仅支持Android平台

依赖要求

• HBuilderX: >= 3.6.8
• uni-app: >= 3.1.0
• Android API: >= 21 (Android 5.0)

华为HMS服务

本插件依赖以下华为HMS ML Kit SDK：

com.huawei.hms:ml-computer-card-icr-cn:3.7.0.303  (身份证识别)
com.huawei.hms:ml-computer-card-bcr:3.7.0.302    (银行卡识别)
com.huawei.hms:ml-computer-card-gcr-cn:3.9.0.301  (通用卡证识别)

安装插件

方式一：通过插件市场安装（推荐）

1. 打开HBuilderX
2. 点击菜单栏 工具 -> 插件安装
3. 搜索 zy-hwocr
4. 点击安装

方式二：手动安装

1. 将 uni_modules/zy-hwocr 目录复制到你的项目的 uni_modules 目录下
2. 重启HBuilderX

快速开始

1. 引入插件

import {
  ocr,                    // 身份证识别
  bankCardOCR,            // 银行卡识别
  generalCardOCR,         // 通用卡证识别
  checkOCRPermission,     // 检查权限
  requestOCRPermission    // 请求权限
} from "@/uni_modules/zy-hwocr";

2. 配置权限

在 manifest.json 中添加以下权限：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.CAMERA\"/>",
          "<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>",
          "<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>"
        ]
      }
    }
  }
}

3. 配置华为HMS服务

在 manifest.json 的 app-plus -> distribute -> android 下添加华为HMS配置：

{
  "app-plus": {
    "distribute": {
      "android": {
        "agreements": [
          {
            "plugins": [
              {
                "type": "module",
                "name": "OCR",
                "class": "com.huawei.hms.mlsdk.MLApplication"
              }
            ]
          }
        ]
      }
    }
  }
}

API 文档

身份证识别 (OCR)

参数说明

type OCROptions = {
  imagePath?: string          // 图片路径（非视频模式时必填）
  isVideo?: boolean           // 是否为视频模式（相机扫描），默认 false
  isFront?: boolean           // 是否为正面识别，默认 true
  success?: (res: OCRResult) => void
  fail?: (res: OCRFail) => void
  complete?: (res: any) => void
}

识别结果

type OCRResult = {
  success: boolean            // 识别是否成功
  idNumber?: string           // 身份证号
  name?: string               // 姓名
  gender?: string             // 性别
  ethnicity?: string          // 民族
  birthDate?: string          // 出生日期
  address?: string            // 地址（正面）
  authority?: string          // 签发机关（反面）
  validPeriod?: string        // 有效期限（反面）
  error?: string              // 错误信息
}

使用示例

视频流识别（相机扫描）

// 扫描身份证正面
ocr({
  isVideo: true,
  isFront: true,
  success: (res) => {
    if (res.success) {
      console.log('身份证号:', res.idNumber);
      console.log('姓名:', res.name);
      console.log('性别:', res.gender);
    }
  },
  fail: (err) => {
    console.error('识别失败:', err.errMsg);
  }
});

图片识别

// 从相册选择图片识别
uni.chooseImage({
  count: 1,
  sourceType: ['album'],
  success: (res) => {
    const path = plus.io.convertLocalFileSystemURL(res.tempFilePaths[0]);
    ocr({
      imagePath: path,
      isVideo: false,
      isFront: true,
      success: (res) => {
        console.log('识别结果:', res);
      },
      fail: (err) => {
        console.error('识别失败:', err.errMsg);
      }
    });
  }
});

银行卡识别 (BankCardOCR)

参数说明

type BankCardOptions = {
  resultType?: string    // 识别结果类型："NUM_ONLY"|"SIMPLE"|"ALL"，默认 "SIMPLE"
  orientation?: string   // 屏幕方向："AUTO"|"LANDSCAPE"|"PORTRAIT"，默认 "AUTO"
  success?: (res: BankCardResult) => void
  fail?: (res: OCRFail) => void
  complete?: (res: any) => void
}

识别结果

type BankCardResult = {
  success: boolean            // 识别是否成功
  cardNumber?: string         // 银行卡号
  validThru?: string          // 有效期（MM/YY）
  issuer?: string             // 发卡行
  organization?: string       // 发卡组织
  cardType?: string           // 卡类别
  error?: string              // 错误信息
}

使用示例

// 标准识别模式（推荐）
bankCardOCR({
  resultType: 'SIMPLE',
  orientation: 'AUTO',
  success: (res) => {
    if (res.success) {
      console.log('银行卡号:', res.cardNumber);
      console.log('有效期:', res.validThru);
      console.log('发卡行:', res.issuer);
    }
  },
  fail: (err) => {
    console.error('识别失败:', err.errMsg);
  }
});

// 仅识别卡号
bankCardOCR({
  resultType: 'NUM_ONLY',
  success: (res) => {
    console.log('银行卡号:', res.cardNumber);
  }
});

// 完整信息识别
bankCardOCR({
  resultType: 'ALL',
  success: (res) => {
    console.log('完整信息:', res);
  }
});

通用卡证识别 (GeneralCardOCR)

参数说明

type GeneralCardOptions = {
  mode?: string              // 识别模式："preview" 视频流识别 | "photo" 拍照识别 | "image" 相册图片识别
  imagePath?: string         // 图片路径（图片模式时必填）
  language?: string          // 识别语言，默认 "en" (支持：en, en, ja, ko等)
  success?: (res: GeneralCardResult) => void
  fail?: (res: OCRFail) => void
  complete?: (res: any) => void
}

识别结果

type GeneralCardResult = {
  success: boolean            // 识别是否成功
  textBlocks?: Array<TextBlock>  // 识别的文本块
  rawText?: string            // 完整文本
  error?: string              // 错误信息
}

type TextBlock = {
  text: string                // 文本内容
  border?: Array<Point>       // 文本框的四个角点坐标
  language?: string           // 语言类型
}

使用示例

视频流识别

generalCardOCR({
  mode: 'preview',
  language: 'en',
  success: (res) => {
    if (res.success) {
      console.log('完整文本:', res.rawText);
      console.log('文本块数量:', res.textBlocks.length);
      res.textBlocks.forEach((block, index) => {
        console.log(`文本块 ${index + 1}:`, block.text);
      });
    }
  },
  fail: (err) => {
    console.error('识别失败:', err.errMsg);
  }
});

拍照识别

generalCardOCR({
  mode: 'photo',
  language: 'en',
  success: (res) => {
    console.log('识别结果:', res);
  }
});

相册图片识别

uni.chooseImage({
  count: 1,
  sourceType: ['album'],
  success: (res) => {
    const path = plus.io.convertLocalFileSystemURL(res.tempFilePaths[0]);
    generalCardOCR({
      mode: 'image',
      imagePath: path,
      language: 'en',
      success: (res) => {
        console.log('识别结果:', res);
      },
      fail: (err) => {
        console.error('识别失败:', err.errMsg);
      }
    });
  }
});

权限管理

检查权限

const hasPermission = checkOCRPermission();
console.log('是否有相机权限:', hasPermission);

请求权限

requestOCRPermission();

// 延迟检查权限状态
setTimeout(() => {
  const hasPermission = checkOCRPermission();
  if (!hasPermission) {
    uni.showToast({
      title: '请授予相机权限',
      icon: 'none'
    });
  }
}, 2000);

错误码说明

注意事项

1. 华为HMS配置

使用本插件前，必须在华为开发者联盟配置App：

1. 登录 华为开发者联盟
2. 创建应用并获取 agconnect-services.json 文件
3. 将 agconnect-services.json 文件放置在项目根目录或 app-plus 目录下

2. 权限处理

• 首次使用前需要请求相机和存储权限
• Android 6.0+ 需要在运行时请求权限
• 建议在应用启动时检查并请求必要权限

3. 识别模式选择

• 视频流识别：用户体验好，自动对焦和裁剪，推荐用于身份证和银行卡识别
• 图片识别：适用于已有图片文件的场景
• 拍照识别：适用于需要用户主动拍照的场景

4. 性能优化

• 避免频繁调用识别接口
• 建议在识别前对图片进行压缩处理
• 视频流识别比图片识别消耗更多资源

5. 隐私保护

• 所有识别数据均在本地处理，不会上传到服务器
• 建议在使用完成后及时清除敏感数据
• 遵守相关的隐私法律法规

完整示例

<template>
  <view class="container">
    <button @click="checkPermission">检查权限</button>
    <button @click="requestPermission">请求权限</button>

    <button @click="scanIDCard">扫描身份证</button>
    <button @click="scanBankCard">扫描银行卡</button>
    <button @click="scanGeneralCard">扫描通用卡证</button>

    <view v-if="result">
      <text>{{ JSON.stringify(result) }}</text>
    </view>
  </view>
</template>

<script>
import {
  ocr,
  bankCardOCR,
  generalCardOCR,
  checkOCRPermission,
  requestOCRPermission
} from "@/uni_modules/zy-hwocr";

export default {
  data() {
    return {
      result: null
    };
  },
  methods: {
    checkPermission() {
      const hasPermission = checkOCRPermission();
      uni.showToast({
        title: hasPermission ? '已授权' : '未授权',
        icon: 'none'
      });
    },

    requestPermission() {
      requestOCRPermission();
    },

    scanIDCard() {
      ocr({
        isVideo: true,
        isFront: true,
        success: (res) => {
          this.result = res;
          uni.showToast({ title: '识别成功', icon: 'success' });
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' });
        }
      });
    },

    scanBankCard() {
      bankCardOCR({
        resultType: 'SIMPLE',
        success: (res) => {
          this.result = res;
          uni.showToast({ title: '识别成功', icon: 'success' });
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' });
        }
      });
    },

    scanGeneralCard() {
      generalCardOCR({
        mode: 'photo',
        language: 'en',
        success: (res) => {
          this.result = res;
          uni.showToast({ title: '识别成功', icon: 'success' });
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' });
        }
      });
    }
  }
};
</script>

常见问题

Q1: 识别时提示"相机权限被拒绝"

A: 请确保已授予相机和存储权限，并在 manifest.json 中正确配置权限声明。

Q2: 华为HMS服务初始化失败

A: 请检查：

1. 是否正确放置 agconnect-services.json 文件
2. 华为开发者联盟中的应用配置是否正确
3. 项目包名是否与华为开发者联盟配置一致

Q3: 识别速度慢或识别失败

A: 建议：

1. 确保网络连接正常（部分识别模式需要网络）
2. 使用光线充足的环境进行识别
3. 确保证件完整且清晰可见
4. 避免在模糊、反光或遮挡的情况下识别

Q4: 通用卡证识别结果不准确

A: 通用卡证识别返回的是原始文本，需要根据具体卡证类型进行二次解析。不同卡证的版式不同，需要自行实现解析逻辑。

Q5: 支持iOS平台吗？

A: 目前本插件仅支持Android平台。iOS平台需要单独开发。

更新日志

查看 changelog.md 了解版本更新详情。

技术支持

• UTS语法文档: https://uniapp.dcloud.net.cn/tutorial/syntax-uts.html
• UTS插件开发: https://uniapp.dcloud.net.cn/plugin/uts-plugin.html
• 华为HMS文档: https://developer.huawei.com/consumer/cn/hms/huawei-mlkit/

许可证

MIT License

免责声明

本插件基于华为HMS ML Kit开发，识别准确率和稳定性依赖于华为SDK本身。使用本插件时，请遵守华为HMS服务的相关协议和法律法规。