更新记录

1.0.0（2026-10-31）

• 新增华视蓝牙身份证读卡器支持：初始化、按 MAC 直连 / 自动扫描连接
• 新增循环读卡，支持居民身份证、港澳台居民居住证、外国人永久居留身份证
• 支持读取证件头像并以 JPEG Base64 data URI 返回
• 支持连接状态查询、断线自动重连开关、断开连接与资源释放

平台兼容性

uni-app(4.72)

uni-app x(4.72)

插件介绍

安卓华视蓝牙身份证读卡器 UTS 原生插件。手机通过蓝牙连接华视蓝牙身份证读卡器，读取证件文字信息与头像（Base64），无需 USB OTG 与读卡器驱动。

支持 uni-app 与 uni-app x，插件已内置读卡器通信协议与头像解码库，无需额外集成任何库。

支持的证件类型：

使用场景

• 酒店 / 公寓前台实名登记，读取身份证自动填充入住人信息
• 园区门禁、访客机、自助终端刷证登记与留档
• 物流寄递、金融柜面、医疗挂号的实名核验
• 需要采集证件头像（Base64）做本地留存的业务

使用流程

1. 初始化：initModule() 申请蓝牙 / 定位权限并初始化读卡器，权限未授权时会自动弹窗，授权后再次调用即可。
2. 连接：connect({ mac }) 按 MAC 直连；不传 mac 或直连失败时自动扫描连接（scanTimeout 默认 20000 毫秒）。
3. 读卡：startAutoRead({ onEvent }) 启动循环读卡，读到证件后 onEvent 回调 event='card' 与证件信息。
4. 停止读卡：stopAutoRead()，读卡线程会回调一次 event='stopped'。
5. 断开与释放：disconnect() 断开连接（同时释放读卡器实例），release() 释放全部资源，建议在页面 onUnload 调用 release()。

运行须知：插件内含原生解码库（lib_HS_idcard、lib_HS_100NMLin），必须打自定义基座运行（标准基座不含该依赖）；读卡器需先与手机蓝牙配对或在附近可被扫描到。

用法

import {
    initModule,
    connect,
    startAutoRead,
    stopAutoRead,
    disconnect,
    enableReconnect,
    getBlueState,
    release
} from '@/uni_modules/zy-huashi-idcard'

初始化

initModule({
    success: (res) => {
        // res.workPath：解码数据目录；res.errMsg：结果描述
        console.log('初始化成功 ' + res.workPath)
    },
    fail: (err) => {
        // 首次调用通常返回 9230003（权限弹窗已弹出），授权后重新调用即可
        console.log('初始化失败 ' + err.errCode + ' ' + err.errMsg)
    }
})

连接读卡器

// 按 MAC 直连（直连失败会自动转扫描连接；MAC 格式需为 XX:XX:XX:XX:XX:XX，格式非法返回 9230001）
connect({
    mac: '00:11:22:33:44:55',
    scanTimeout: 20000, // 可选，扫描超时（毫秒），默认 20000
    success: (res) => console.log('已连接 ' + res.mac),
    fail: (err) => console.log('连接失败 ' + err.errCode + ' ' + err.errMsg)
})

// 不传 mac：直接扫描附近读卡器并连接
connect({
    success: (res) => console.log('已连接 ' + res.mac),
    fail: (err) => console.log('连接失败 ' + err.errCode + ' ' + err.errMsg)
})

循环读卡

startAutoRead({
    interval: 1000, // 可选，两次读卡间隔（毫秒），默认 1000，最小 100
    onEvent: (res) => {
        // res.event 取值：'started' 已启动 | 'card' 读到证件 | 'stopped' 已停止
        if (res.event === 'card') {
            const card = res.card
            console.log(card.name + ' ' + card.idCard + ' ' + card.certTypeText)
            // card.photo 可直接给 <image :src="card.photo"> 使用
        }
    },
    success: (res) => console.log('读卡已启动'),
    fail: (err) => console.log('启动失败 ' + err.errCode + ' ' + err.errMsg)
})

// 停止循环读卡
stopAutoRead({
    success: (res) => console.log('已停止')
})

连接状态与断线重连

getBlueState({
    success: (res) => {
        // res.state：0 连接正常 | 1 断开连接 | 2 休眠 | 3 断线重连中 | -1 未初始化
        console.log(res.state + ' ' + res.stateText)
    }
})

// 开启 / 关闭断线自动重连
enableReconnect({
    enable: true,
    success: (res) => console.log('断线重连 ' + (res.enabled ? '已开启' : '已关闭')),
    fail: (err) => console.log('设置失败 ' + err.errCode + ' ' + err.errMsg)
})

断开与释放

// 断开连接（读卡器实例随之释放，再次使用需重新 initModule → connect）
disconnect({
    success: (res) => console.log('已断开')
})

// 释放全部资源（建议在页面 onUnload 调用）
release({
    success: (res) => console.log('资源已释放')
})

插件方法

所有方法失败时回调 fail(err)，err 为 UniError，含 errSubject、errCode、errMsg。

回调结构

// HsInitResult（initModule.success）
{
    workPath: '', // string，解码数据目录
    errMsg: ''    // string，结果描述
}

// HsConnectResult（connect.success）
{
    mac: '',      // string，已连接读卡器的蓝牙地址
    errMsg: ''
}

// HsReadEvent（startAutoRead.onEvent）
{
    event: '',    // string，'started' | 'card' | 'stopped'
    card: null    // HsIdCardInfo | null，仅 event='card' 时有值
}

// HsBlueStateResult（getBlueState.success）
{
    state: 0,          // number，0 连接正常 | 1 断开连接 | 2 休眠 | 3 断线重连中 | -1 未初始化
    stateText: '',     // string，状态描述
    errMsg: ''
}

// HsReconnectResult（enableReconnect.success）
{
    enabled: false,    // boolean，当前断线重连开关状态
    errMsg: ''
}

// HsSimpleResult（stopAutoRead / disconnect / release 的 success）
{
    errMsg: ''
}

证件信息字段（HsIdCardInfo）

所有字段均为字符串，无值时为 ''，无需判空。

{
    certType: '',        // string，' '（空格）居民身份证 | 'J' 港澳台居住证 | 'I' / 'Y' 外国人永久居留证
    certTypeText: '',    // string，证件类型名称，如「居民身份证」
    name: '',            // string，姓名
    sex: '',             // string，性别
    nation: '',          // string，民族（居民身份证）
    birth: '',           // string，出生日期 yyyy-MM-dd
    address: '',         // string，住址（居民身份证、港澳台居住证）
    idCard: '',          // string，证件号码
    department: '',      // string，签发机关
    startDate: '',       // string，有效期限起始日期
    endDate: '',         // string，有效期限截止日期（长期为「长期」）
    issuesNum: '',       // string，签发次数（港澳台居住证、2017 版外国人永久居留证）
    passCheckID: '',     // string，通行证号码（港澳台居住证）
    cnName: '',          // string，中文姓名（外国人永久居留证）
    nationCode: '',      // string，国籍代码（外国人永久居留证）
    standbyEName: '',    // string，备用英文名（2017 版外国人永久居留证）
    oldIdCardNumber: '', // string，原证件号码（2017 版外国人永久居留证）
    photo: ''            // string，头像 JPEG 的 data URI（data:image/jpeg;base64,xxx），解码失败为 ''
}

错误码

权限说明