更新记录

1.0.0（2026-02-06）

Added

• 首个正式可用版本发布。
• 新增 OCR 初始化接口 initOcr()，支持 aksk 与 license 双鉴权模式。
• 新增扫描识别接口 scanOcr()，支持：
  • general（通用文字）
  • idcard_front（身份证人像面）
  • idcard_back（身份证国徽面）
  • bankcard（银行卡）
• 新增图片识别接口 recognizeOcr()，支持指定本地图片路径识别。
• 新增日志控制接口 setOcrLogEnabled() / isOcrLogEnabled()。
• 新增统一错误码体系（9020001 ~ 9020008）和错误对象封装。

Platform

• Android：支持，最低 API 21。
• iOS：支持，最低 iOS 12.0。
• HarmonyOS：当前不支持（调用返回 9020007）。

Dependencies

• HBuilderX >= 3.6.8
• uni-app x >= 3.1.0
• Android 依赖：androidx.core:core:1.10.1、androidx.annotation:annotation:1.7.1
• iOS 依赖：AVFoundation、CoreMedia、Photos 等系统 Frameworks

Security & Privacy

• 需要相机权限（Android）与相机/相册权限（iOS）。
• AK/SK 与 License 涉及敏感凭据，需由业务方自行安全保管。

Notes

• iOS 模拟器不支持百度 OCR 原生能力，请使用真机调试。
• 调用 scanOcr()、recognizeOcr() 前必须先调用 initOcr()。
• License 文件默认名为 aip.license。

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-baidu-ocr（uni-app x / UTS 插件）

基于百度 OCR SDK 的 uni-app x 插件，支持 App-Android / App-iOS，提供 AK/SK 与 License 两种鉴权方式。

平台兼容性

运行环境要求：

• HBuilderX >= 3.6.8
• uni-app x >= 3.1.0

能力概览

• 鉴权初始化：initOcr()
• 扫描识别：scanOcr()（拉起百度 OCR 拍照 UI）
• 图片识别：recognizeOcr()（输入本地图片路径）
• 调试能力：setOcrLogEnabled() / isOcrLogEnabled()
• 结果结构：标准化 words / fields，并返回 raw 原始 JSON

安装

将插件放到项目目录：uni_modules/hans-baidu-ocr/。

导入方式：

import { initOcr, scanOcr, recognizeOcr } from '@/uni_modules/hans-baidu-ocr'

快速开始

1) 初始化（AK/SK）

import { initOcr } from '@/uni_modules/hans-baidu-ocr'

initOcr({
  mode: 'aksk',
  ak: '你的AK',
  sk: '你的SK',
  success: (res) => console.log('init ok', res),
  fail: (err) => console.error('init fail', err)
})

2) 初始化（License，推荐）

1. 下载百度授权文件，命名为 aip.license（或使用 licenseName 指定）。
2. 将文件放到项目原生资源目录（请勿提交到 Git）：
   • Android：nativeResources/android/assets/aip.license
   • iOS：nativeResources/ios/Resources/aip.license
3. 调用初始化：

initOcr({
  mode: 'license',
  licenseName: 'aip.license'
})

3) 调起拍照 UI 并自动识别

import { scanOcr } from '@/uni_modules/hans-baidu-ocr'

scanOcr({
  type: 'general', // 'general' | 'idcard_front' | 'idcard_back' | 'bankcard'
  autoRecognize: true,
  detectDirection: false,
  success: (res) => {
    console.log(res.imagePath)
    console.log(res.recognize)
  }
})

4) 识别指定图片路径

import { recognizeOcr } from '@/uni_modules/hans-baidu-ocr'

recognizeOcr({
  type: 'general_basic',
  imagePath: '/path/to/your.jpg',
  detectDirection: false,
  success: (res) => {
    console.log(res.words)
    console.log(res.fields)
    console.log(res.raw)
  }
})

5) 日志开关

import { setOcrLogEnabled, isOcrLogEnabled } from '@/uni_modules/hans-baidu-ocr'

setOcrLogEnabled(true)
console.log('ocr log enabled:', isOcrLogEnabled())

API 说明

initOcr(options)

用于初始化 OCR 引擎与鉴权，建议在应用启动后尽早调用。

• mode：'aksk' | 'license'
• ak / sk：当 mode='aksk' 时必填
• licenseName：当 mode='license' 时可选，默认 aip.license
• 回调：success / fail / complete

scanOcr(options)

拉起 SDK 扫描页拍照并可选自动识别。

• type：'general' | 'idcard_front' | 'idcard_back' | 'bankcard'
• autoRecognize：是否拍照后自动调用识别，默认 true
• detectDirection：仅在 general 时生效，默认 false

返回：

• imagePath：拍照后的本地文件路径
• recognize：当 autoRecognize=true 时返回识别结果

recognizeOcr(options)

对本地图片路径执行识别。

• type：'general_basic' | 'idcard_front' | 'idcard_back' | 'bankcard'
• imagePath：本地图片路径（支持 file:// 前缀）
• detectDirection：仅 general_basic 场景有意义

返回字段：

• words：通用识别时的文本数组
• fields：结构化字段（身份证/银行卡）
• raw：SDK 原始 JSON 字符串

权限与隐私

权限

• Android：android.permission.CAMERA
• iOS：NSCameraUsageDescription、NSPhotoLibraryUsageDescription

插件已提供 iOS 权限描述模板：utssdk/app-ios/info.plist。

数据与合规说明

• aksk 模式会调用百度云鉴权接口。
• OCR 识别相关数据由百度 OCR SDK 处理，请确保你的隐私政策已向用户告知。
• 请勿在仓库中提交 AK/SK、license、证书等敏感信息。

错误码

错误处理示例：

import { initOcr, type OcrFail } from '@/uni_modules/hans-baidu-ocr'

initOcr({
  mode: 'aksk',
  ak: 'your-ak',
  sk: 'your-sk',
  fail: (err: OcrFail) => {
    if (err.errCode == 9020003) {
      console.error('鉴权失败，请检查 AK/SK 或 License')
      return
    }
    console.error('OCR 初始化失败', err.errCode, err.errMsg)
  }
})

已知限制

• iOS 模拟器不支持百度 OCR 原生能力，请使用真机调试。
• HarmonyOS 当前为占位实现，接口会返回不支持错误。
• 调用 scanOcr、recognizeOcr 前必须先完成 initOcr。

更新日志

详见 changelog.md。