更新记录
1.0.0(2026-11-19)
首次发布:完成 Android / HarmonyOS 双端实现与真机验证。
平台兼容性
uni-app x(4.25)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| × | × | √ | × | √ | × |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
uni-biometric · 生物识别(指纹 / 人脸)
调用系统生物识别完成身份验证:能力检测、发起认证、失败原因细分、取消,Android 与鸿蒙双端,纯系统 API,不引入任何三方 SDK。
特性
| 能力 | Android | HarmonyOS |
|---|---|---|
| 可用性检测(硬件 / 录入 / 锁屏) | ✅ FingerprintManager | ✅ userAuth.getAvailableStatus |
| 指纹认证 | ✅ BiometricPrompt / FingerprintManager | ✅ UserAuthInstance |
| 人脸 / 虹膜降级 | ✅ API 28+ | ✅ |
| 失败原因细分(未录入 / 锁定 / 取消 / 传感器占用) | ✅ 10 种错误码 | ✅ 主要分支 |
| 取消进行中的认证 | ✅ | ✅ |
| 三方 SDK 依赖 | 无 | 无 |
快速开始
import { checkSupport, authenticate, cancelAuth } from '@/uni_modules/uni-biometric'
// 1. 先检测能不能用(进入页面前调用一次)
checkSupport({
success: (res) => {
if (!res.available) {
// res.reason 已经是中文:未录入指纹 / 没有硬件 / 未设置锁屏
console.log(res.reason, res.types, res.strength)
return
}
// 2. 拉起系统认证弹窗
authenticate({
title: '身份验证',
subtitle: '请验证指纹以进入保险箱',
allowFace: false, // true 时允许人脸/虹膜
success: (r) => console.log('通过', r.authType, r.timestamp),
fail: (err) => console.log(err.errCode, err.errMsg),
complete: () => { /* 收起 loading */ }
})
}
})
// 3. 页面关闭时取消未完成的认证,避免弹窗残留
cancelAuth({})
API
| 方法 | 参数 | 说明 |
|---|---|---|
checkSupport(options) |
{success?, fail?, complete?} |
返回 hardwareAvailable / enrolled / deviceSecure / available / types[] / strength / reason |
authenticate(options) |
{title?, subtitle?, description?, negativeText?, allowFace?, success, fail, complete} |
拉起系统生物识别弹窗,结果走回调 |
cancelAuth(options?) |
{success?} |
取消当前认证 |
关键字段
types:['fingerprint']/['fingerprint','face']/['face'],按设备实际硬件返回strength:strong(指纹类,可解 Keystore 密钥)/weak(仅身份确认)/nonereason:不可用时的中文原因,可直接展示给用户,不用自己拼接authType:成功回调里返回fingerprint/biometric
错误码
| 码 | 含义 | 常见原因 |
|---|---|---|
| 9120001 | 参数错误 | title 传了空串 |
| 9120002 | 设备不支持生物识别 | 无指纹硬件(多数模拟器属于此类) |
| 9120003 | 尚未录入指纹或人脸 | 需引导用户去系统设置录入 |
| 9120004 | 尚未设置锁屏密码 | 生物识别的前置条件 |
| 9120005 | 用户取消 | 点取消按钮、按返回、系统中断 |
| 9120006 | 认证失败 | 指纹不匹配、超时 |
| 9120007 | 失败次数过多 | 系统锁 30 秒左右,需提示稍后重试 |
| 9120008 | 传感器暂不可用 | 被其它应用占用、硬件异常 |
| 9120009 | 系统版本过低 | Android 6.0 以下 |
| 9120010 | 内部错误 | 上一次认证未结束、上下文异常 |
平台说明(重要)
Android
- 最低 Android 6.0(API 23)。API 28+ 走系统
BiometricPrompt,23–27 走FingerprintManager(仅指纹)。 allowFace: false只有在 API 30+ 才能真正限定「只用强生物识别(指纹)」;Android 9/10 上系统可能仍允许已录入的人脸,这是平台限制,不是插件行为。USE_BIOMETRIC/USE_FINGERPRINT都是普通权限,安装即授予,不需要运行时申请,但插件必须打进自定义基座才会生效(AndroidManifest.xml在打包时合并)。
HarmonyOS
- 基于
@kit.UserAuthenticationKit,认证需ohos.permission.ACCESS_BIOMETRIC。 - 鸿蒙上生物识别本身要求设备已设锁屏,因此
deviceSecure与hardwareAvailable同源。
模拟器
多数模拟器(MuMu、夜神)没有指纹硬件,checkSupport() 返回 hardwareAvailable: false、reason: '设备没有可用的生物识别硬件',authenticate() 返回 9120002。这是正确行为,认证弹窗必须在真机上验证。
Demo
pages/biometric/biometric 提供完整演示:能力检测卡片、提示语输入、仅指纹/允许人脸切换、保险箱锁定态(验证通过后展开内容)、操作记录。

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 69
赞赏 0
下载 12775974
赞赏 1960
赞赏
京公网安备:11010802035340号