生物识别使用指导
不可见组件：弹出系统的指纹或人脸验证框，确认是本机主人在操作。
常用于登录、查看隐私内容、付款或删除前的二次验证。验证界面、重试次数、失败锁定都由系统负责， 应用拿不到任何指纹或人脸数据，只知道验证是否通过。需要 Android 9 及以上。
快速上手
放一个生物识别、一个按钮、一个标签。点按钮验证，通过后显示隐私内容；本机不支持时提示改用密码：
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮1.Click() {
if (生物识别1.IsAvailable()) {
生物识别1.Authenticate("查看隐私内容", "请验证指纹或人脸")
} else {
标签1.Text = "本机不支持指纹或人脸，请用密码登录"
}
}
when 生物识别1.AuthSucceeded() {
标签1.Text = "验证通过"
}
when 生物识别1.AuthFailed(消息) {
标签1.Text = join("验证未通过：", 消息)
}
注意：它只能确认「是这台手机的主人」，不能区分是谁，也不能代替账号登录。 需要联网登录的应用，通常第一次用账号密码登录，之后再用生物识别快速解锁。
搭建与测试
在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。
可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。
案例：解锁私人内容
放生物识别、按钮和标签；关闭设备密码回退时只接受生物识别。仅在成功事件后显示受保护布局。
when Screen1.Initialize() {
生物识别1.AllowDeviceCredential = false
垂直布局_隐私.Visible = false
}
when 按钮_解锁.Click() {
生物识别1.Authenticate("解锁私人内容", "请验证本机身份")
}
when 生物识别1.AuthSucceeded() {
垂直布局_隐私.Visible = true
}
设备必须先在系统设置里录入指纹或人脸；验证被取消或失败时保持隐私布局隐藏。它不返回生物信息，也不代替服务器账号认证。
属性、方法与事件速查
完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。
| 入口 | 用途 |
|---|---|
允许锁屏密码（AllowDeviceCredential） |
为真时验证框提供「使用锁屏密码」：没录指纹人脸、或多次识别失败时可以改用锁屏密码 / 图案通过。Android 10 及以上生效。 |
开始验证（标题，副标题）（Authenticate） |
弹出系统验证框。验证通过触发「验证成功时」；用户取消、次数过多被锁定、设备不支持时触发「验证失败时」并给出原因。识别不匹配时系统会在框内提示重试，不触发事件。 |
是否可用（IsAvailable） |
本机能否进行生物识别验证：系统版本支持、有指纹或人脸硬件、并且已经录入。勾选了允许锁屏密码时，设置了锁屏密码也算可用。 |
验证失败时（消息）（AuthFailed） |
身份验证没有通过（用户取消、次数过多被锁定、没录入指纹人脸、设备不支持等），“消息”参数为原因。 |
验证成功时（AuthSucceeded） |
身份验证通过。 |
常见问题与验收
| 检查项 | 操作与预期 |
|---|---|
| 初始化 | 对照案例检查是否已经调用加载、注册、连接或显示方法；仅拖入组件不会替你执行这些步骤。 |
| 结果返回 | 将成功事件和失败事件都接到标签，记录事件参数；异步操作完成前不读取结果属性。 |
| 输入配置 | 检查素材名大小写、网址是否为直接资源地址、文件是否存在、编号和索引是否在范围内。 |
| 平台与权限 | 按组件参考中的平台说明测试；授权被拒绝时应有明确提示，不继续假定操作成功。 |
| 最小案例 | 先验证页面中的最小案例，再验证第二个场景；重复操作、取消、返回屏幕后结果应符合事件说明。 |
完整 .aia 源码与操作指导
需要支持生物识别的真实设备，并在系统设置录入指纹／人脸；允许锁屏密码时可使用设备密码。鸿蒙系统控件会合并标题与副标题。此案例只演示本机身份验证，不替代服务器授权或真实硬件控制。
导入 BiometricAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| AllowDeviceCredential 设计器配置与读取／设置 | 切换允许锁屏密码 | 属性区显示实际设置，并重新判断可用性；安卓10+支持密码回退 |
| IsAvailable | 点检查 | 有已录入生物识别，或允许已有锁屏密码时可用；否则提示不可用 |
| Authenticate | 点验证 | 弹真实系统验证框；避免重复提交；标题来自输入框 |
| AuthSucceeded | 用真实身份完成验证 | 显示受保护布局，成功计数增加 |
| AuthFailed | 在系统框取消 | 布局保持锁定、失败计数增加、显示具体原因；可再次验证 |
| 再次验证和锁定 | 点重新锁定，再验证 | 恢复锁定并可再次解锁；识别暂不匹配由系统提示重试 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
生物识别
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 需要支持生物识别的真实设备，并在系统设置录入指纹／人脸；允许锁屏密码时可使用设备密码。鸿蒙系统控件会合并标题与副标题。此案例只演示本机身份验证，不替代服务器授权或真实硬件控制。 覆盖检查 7/7。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
扫码添加客服咨询
