更新记录

1.0.0（2026-11-01）

• 首发：身份证人像面 / 国徽面本地识别。
• 标准模式组件 umi-idcard：圆角取景框、人像/国徽引导、拍摄与相册。

平台兼容性

uni-app x(5.24)

umi-ocr-x

uni-app x 身份证本地 OCR 插件（Android / iOS / HarmonyOS）。图片不上传，识别在设备端完成。

仅 App。Android、iOS 真机运行必须打 自定义基座（Android 含 ML Kit 依赖）。鸿蒙走原生编译。

加密后的普通授权版只能从 @/uni_modules/umi-ocr-x 导入，不要写 utssdk/ 内部路径。

取景 UI

标准模式组件 umi-idcard，与示意图一致：

• 人像面：圆角取景框 + 提示文案 + 右侧人像轮廓
• 国徽面：圆角取景框 + 提示文案 + 左侧国徽轮廓
• 半透明遮罩、关闭；快门与相册可通过参数隐藏

只通过 option 配置。字段用 number / string，不要写 boolean。

<umi-idcard
    :option="scanOption"
    @success="onOk"
    @fail="onFail"
    @cancel="onCancel"
></umi-idcard>

class UmiIdCardViewOption {
    mode : string
    showAlbum : number
    showShutter : number
    constructor(mode : string, showAlbum : number, showShutter : number) {
        this.mode = mode
        this.showAlbum = showAlbum
        this.showShutter = showShutter
    }
}
const scanOption = ref(new UmiIdCardViewOption('both', 1, 1))

umi-idcard 属性

option 字段

option.showShutter 为 0 时（仅人像面）：

• 提示改为「请将身份证人像面对准取景框」，过程中不显示「识别中」
• 组件约每 2.5 秒静默抓拍一次（避免连续高分辨率拍照导致发热）；必须同时识别到姓名、性别、出生、住址、公民身份号码才算成功
• 缺任一上述字段则自动重试；连续 3 次仍没有完整人像面数据时，Toast「请正确放置身份证」，然后计数清零继续识别
• 未对准、反光、不完整时继续取景，不弹失败 Toast
• 光线过暗、证件未对准取景框、或表面反光过强时，在取景框中央提示「光线不足 / 请对准证件 / 反光过强」
• 国徽面（option.mode 为 back，或 both 切到背面）不走自动识别，会显示快门手动拍摄
• 相册仍受 option.showAlbum 控制

事件

Android / iOS 使用 <camera> 预览。鸿蒙官方 camera 组件不可用，组件内用 native-view + CameraKit 预览。

API

import {
    idCardOptionsWithSide,
    recognizeIdCard,
    readAnyErrMsg,
    UmiIdCardResult
} from '@/uni_modules/umi-ocr-x'

recognizeIdCard(idCardOptionsWithSide(path, 'front')).then((item : UmiIdCardResult) => {
    console.log(item.name, item.idNumber)
}, (err : any | null) => {
    console.log(readAnyErrMsg(err, '识别失败'))
})

UmiIdCardResult

权限

Android / iOS 权限写在应用 manifest.json。鸿蒙不要只写 manifest.json 的 app-harmony.distribute.requestPermissions，HBuilderX 不会可靠地合并进工程；按鸿蒙运行与打包声明在工程 harmony-configs/entry/src/main/module.json5 的 requestPermissions。插件侧也可写 utssdk/app-harmony/module.json5（HAR 子模块权限对整个应用生效）。

• Android app-android.distribute.permissions：CAMERA
• iOS app-ios.distribute.privacyDescription：NSCameraUsageDescription、NSPhotoLibraryUsageDescription
• 鸿蒙：ohos.permission.CAMERA（harmony-configs 与插件 module.json5）

光线不足、未对准证件、反光过强时，取景框中央会提示；应对准取景框、避开强光后重拍。