更新记录

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(仅身份确认)/ none
  • reason:不可用时的中文原因,可直接展示给用户,不用自己拼接
  • 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 提供完整演示:能力检测卡片、提示语输入、仅指纹/允许人脸切换、保险箱锁定态(验证通过后展开内容)、操作记录。

更新记录

见 changelog.md

隐私、权限声明

1. 本插件需要申请的系统权限列表:

需要 android.permission.USE_BIOMETRIC(Android 9+)与 USE_FINGERPRINT(Android 6-8)权限;鸿蒙需 ohos.permission.ACCESS_BIOMETRIC

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集、不上传任何生物特征数据,认证全程在系统安全区域完成,插件只接收成功/失败结果

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。