前言

用户身份认证是应用安全的重要环节。HarmonyOS支持指纹、人脸和锁屏密码等多种认证方式，@pura/harmony-utils 的 AuthUtil 封装了统一的认证接口，开发者可以轻松集成生物认证功能。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、AuthUtil认证核心API

AuthUtil 提供了以下认证方法：

方法	说明	参数	使用场景
auth(type, callback)	发起认证	AuthType	身份验证
cancelAuth()	取消认证	无	取消进行中的认证

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 统一接口：指纹、人脸、密码使用同一接口

1.2 认证类型对比

认证类型	便捷性	安全性	适用场景
FINGERPRINT	高	高	快速验证
FACE	高	中	免提验证
PIN	中	高	备选方案

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 指纹认证

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

Button('指纹认证')
  .width('100%')
  .onClick(async () => {
    try {
      let result = await AuthUtil.auth(userAuth.UserAuthType.FINGERPRINT);
      this.result = `认证结果: ${result ? '成功 ✅' : '失败 ❌'}`;
    } catch (e) {
      this.result = '认证异常: ' + e;
    }
  })

2.3 锁屏密码认证

Button('密码认证')
  .width('100%')
  .onClick(async () => {
    try {
      let result = await AuthUtil.auth(userAuth.UserAuthType.PIN);
      this.result = `认证结果: ${result ? '成功 ✅' : '失败 ❌'}`;
    } catch (e) {
      this.result = '认证异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('指纹认证').width('100%').onClick(async () => {
        try {
          let result = await AuthUtil.auth(userAuth.UserAuthType.FINGERPRINT);
          this.result = `指纹认证: ${result ? '成功' : '失败'}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('取消认证').width('100%').onClick(() => {
        AuthUtil.cancelAuth();
        this.result = '认证已取消';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 认证流程封装

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

async function authenticateUser(): Promise<boolean> {
  try {
    let result = await AuthUtil.auth(userAuth.UserAuthType.FINGERPRINT);
    if (!result) {
      ToastUtil.showToast('认证失败，请重试');
    }
    return result;
  } catch (e) {
    ToastUtil.showToast('认证异常');
    return false;
  }
}

4.2 多认证方式降级

async function authWithFallback(): Promise<boolean> {
  if (AuthUtil.isFingerprintSupported()) {
    try {
      return await AuthUtil.auth(userAuth.UserAuthType.FINGERPRINT);
    } catch (e) { }
  }
  return await AuthUtil.auth(userAuth.UserAuthType.PIN);
}

五、注意事项

1. 认证类型：FINGERPRINT（指纹）、FACE（人脸）、PIN（密码）
2. 信任等级：不同场景需要不同的信任等级
3. 用户取消：用户可能取消认证，需处理取消回调
4. 安全环境：认证需在安全环境下进行
5. 初始化依赖：使用前需确保 AppUtil.init() 已调用

六、常见问题

Q1: 指纹认证弹窗没有出现？

检查是否配置了生物认证权限，以及用户是否已录入指纹。

Q2: 认证超时怎么办？

系统会自动处理超时，用户也可以手动取消。建议在业务层设置超时逻辑。

Q3: cancelAuth()什么时候调用？

在用户主动取消或页面关闭时调用，确保认证流程正确终止。

Q4: 认证结果可以信任吗？

认证结果由系统安全模块保证，可以信任。但建议在关键操作时使用更高信任等级。

总结

AuthUtil 的认证方法为应用提供了便捷的身份验证能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。结合能力查询方法，开发者可以构建完整的认证流程，提升应用安全性。

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