前言

生物认证（指纹、人脸）是移动设备上常用的安全验证方式。在使用生物认证前，需要先查询设备支持的认证能力。@pura/harmony-utils 的 AuthUtil 封装了生物认证能力查询方法，帮助开发者了解设备支持的认证类型。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、AuthUtil能力查询核心API

AuthUtil 提供了以下认证能力查询方法：

方法	说明	返回类型	使用场景
isFingerprintSupported()	是否支持指纹认证	boolean	指纹功能开关
isFaceSupported()	是否支持人脸认证	boolean	人脸功能开关
getSupportedAuthType()	获取支持的认证类型	AuthType[]	认证方式选择

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 能力预检：在发起认证前检查设备支持情况

1.2 认证能力组合方案

指纹	人脸	密码	推荐策略
支持	支持	支持	优先指纹，备选人脸
支持	不支持	支持	指纹+密码
不支持	支持	支持	人脸+密码
不支持	不支持	支持	仅密码

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 查询指纹支持

import { AuthUtil } from '@pura/harmony-utils';

Button('查询指纹支持')
  .width('100%')
  .onClick(() => {
    try {
      let supported = AuthUtil.isFingerprintSupported();
      this.result = `指纹认证: ${supported ? '支持 👆' : '不支持'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 查询人脸支持

Button('查询人脸支持')
  .width('100%')
  .onClick(() => {
    try {
      let supported = AuthUtil.isFaceSupported();
      this.result = `人脸认证: ${supported ? '支持 😊' : '不支持'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { AuthUtil } from '@pura/harmony-utils';

@Entry
@Component
struct AuthCapabilityDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('查询全部认证能力').width('100%').onClick(() => {
        try {
          let fingerprint = AuthUtil.isFingerprintSupported();
          let face = AuthUtil.isFaceSupported();
          this.result = `指纹: ${fingerprint ? '支持' : '不支持'}\n人脸: ${face ? '支持' : '不支持'}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 动态认证方式选择

import { AuthUtil } from '@pura/harmony-utils';

function getBestAuthType(): string {
  if (AuthUtil.isFingerprintSupported()) return 'FINGERPRINT';
  if (AuthUtil.isFaceSupported()) return 'FACE';
  return 'PIN';
}

4.2 认证能力UI展示

@State fingerprintSupported: boolean = false;
@State faceSupported: boolean = false;

aboutToAppear() {
  this.fingerprintSupported = AuthUtil.isFingerprintSupported();
  this.faceSupported = AuthUtil.isFaceSupported();
}

五、注意事项

1. 硬件依赖：认证能力取决于设备硬件
2. 安全设置：用户需在系统设置中录入指纹/人脸
3. 权限配置：使用生物认证需要配置相应权限
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 能力变化：用户可能随时添加或删除生物特征

六、常见问题

Q1: 设备支持指纹但isFingerprintSupported()返回false？

可能用户尚未在系统设置中录入指纹，需要引导用户先录入。

Q2: getSupportedAuthType()返回空数组？

可能是查询失败或设备不支持任何生物认证，建议降级为密码认证。

Q3: 模拟器支持生物认证吗？

模拟器通常不支持生物认证，建议在真机上测试。

Q4: 认证能力会动态变化吗？

会变化，用户可能随时添加或删除指纹/人脸，建议在每次使用前重新查询。

总结

AuthUtil 的认证能力查询方法让开发者能够提前了解设备支持的认证方式，从而选择合适的认证策略。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。在实际应用中，建议先查询能力再发起认证，提升用户体验。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。