HarmonyOS：人脸识别

ChinaDragonDreamer

315人浏览 · 2026-10-07 16:32:05

ChinaDragonDreamer · 2026-10-07 16:32:05 发布

一、开发者准备

应用在开发用户身份认证功能时，需要先了解以下流程，并根据实际需求参考对应指导开发。

查询设备支持的用户身份认证能力。
发起身份认证请求，获取身份认证结果。
校验和使用认证结果：请参考通用密钥库二次认证密钥访问控制。
（可选）认证过程中取消认证。
（可选）切换自定义认证。

1.1 申请权限

在开发具备用户身份认证的应用前，需要先申请权限ohos.permission.ACCESS_BIOMETRIC，应用才能使用生物特征识别能力（如人脸、指纹）进行身份认证。

该权限授权方式为system_grant（系统授权），开发者只需要在module.json5配置文件的requestPermissions标签中声明权限，即可获取系统授权。

二、查询支持的认证能力

不同的设备对于认证能力（人脸、指纹、口令）的支持性各有差异，开发者在发起认证前应当先查询当前设备支持的用户认证能力。

2.1 接口说明

具体参数、返回值、错误码等描述，请参考对应的userAuth.getAvailableStatus。

接口名称	功能描述
getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): void	根据指定的认证类型、认证等级，检测当前设备是否支持相应的认证能力。

2.2 开发步骤

申请权限：ohos.permission.ACCESS_BIOMETRIC。
指定认证类型（UserAuthType）和认证等级（AuthTrustLevel），调用getAvailableStatus接口查询当前的设备是否支持相应的认证能力。
认证可信等级的详细介绍请参见认证可信等级划分原则。

以查询设备是否支持认证可信等级≥ATL3的人脸认证功能为例：

obtainingSupported() {
  try {
    // 查询认证能力是否支持
    userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL3);
    Logger.info('current auth trust level is supported.');
    return true;
  } catch (error) {
    const err: BusinessError = error as BusinessError;
    Logger.error(`current auth trust level is not supported, code is ${err?.code}, message is ${err?.message}`);
    return false;
  }
}

示例2：

发起用户认证，采用认证可信等级≥ATL3的人脸+认证类型相关+复用设备解锁最大有效时长认证，获取认证结果。

initiatingUserAuthentication2() {
  // 设置认证参数
  let reuseUnlockResult: userAuth.ReuseUnlockResult = {
    reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT,
    reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION,
  };
  try {
    const randData = getRandData();
    if (!randData) {
      return;
    }
    const authParam: userAuth.AuthParam = {
      challenge: randData,
      authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE, userAuth.UserAuthType.FINGERPRINT],
      authTrustLevel: userAuth.AuthTrustLevel.ATL3,
      reuseUnlockResult: reuseUnlockResult,
    };
    // 配置认证界面
    const widgetParam: userAuth.WidgetParam = {
      title: resourceToString($r('app.string.title')),
    };
    // 获取认证对象
    const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
    Logger.info('get userAuth instance successfully.');
    // 订阅认证结果
    userAuthInstance.on('result', {
      onResult: (result: userAuth.UserAuthResult) => {
        try {
          Logger.info('userAuthInstance callback.');
          this.result[ResultIndex.EXAMPLE_2] = (`${result.result}`);
          // 可在认证结束或其他业务需要场景，取消订阅认证结果。
          userAuthInstance.off('result');
        } catch (error) {
          const err: BusinessError = error as BusinessError;
          Logger.error(`onResult failed, code: ${err?.code}, Message: ${err?.message}`);
        }
      }
    });
    // 启动认证
    userAuthInstance.start();
    Logger.info('auth start successfully.');
  } catch (error) {
    const err: BusinessError = error as BusinessError;
    Logger.error(`auth failed, code is ${err?.code}, message is ${err?.message}`);
  }
}

三、实战

效果图

设备录入面容进行人脸识别效果

设备没有录入面容进行人脸识别效果

示例代码
TestUserAuthInstance2.ets

import { userAuth } from '@kit.UserAuthenticationKit';
import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { JSON } from '@kit.ArkTS';


function getRandData(): Uint8Array | null {
  try {
    const rand = cryptoFramework.createRandom();
    const len: number = 16;
    let randData: Uint8Array | null = null;
    let retryCount = 0;
    while (retryCount < 3) {
      randData = rand?.generateRandomSync(len)?.data;
      if (randData) {
        break;
      }
      retryCount++;
    }
    return randData;
  } catch (error) {
    const err: BusinessError = error as BusinessError;
    console.error(`getRandData error, code is ${err?.code}, message is ${err?.message}`);
    return null;
  }
}

@Entry
@Component
struct TestUserAuthInstance2 {
  @State message: string = '请面容解锁后查看下面的信息';
  @State lookData: boolean = false;
  @State result: string[] = new Array(8).fill('wait');

  /**
   * 以查询设备是否支持认证可信等级≥ATL3的人脸认证功能为例
   *
   * @returns
   */
  obtainingSupported() {
    try {
      // 查询认证能力是否支持
      userAuth.getAvailableStatus(userAuth.UserAuthType.FACE, userAuth.AuthTrustLevel.ATL3);
      console.info('当前设备 支持 current auth trust level is supported.');
      return true;
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error(
        `当前设备 不支持 current auth trust level is not supported, code is ${err?.code}, message is ${err?.message}`);
      return false;
    }
  }

  /**
   * 发起用户认证，采用认证可信等级≥ATL3的人脸+指纹+锁屏口令认证，获取认证结果。
   */
  initiatingUserAuthentication1() {
    try {
      const randData = getRandData();
      if (!randData) {
        return;
      }
      // 设置认证参数
      const authParam: userAuth.AuthParam = {
        challenge: randData,
        // authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE, userAuth.UserAuthType.FINGERPRINT],
        authType: [userAuth.UserAuthType.FACE],
        authTrustLevel: userAuth.AuthTrustLevel.ATL3,
      };
      // 配置认证界面
      const widgetParam: userAuth.WidgetParam = {
        title: "面容解锁",
      };
      // 获取认证对象
      const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam);
      console.info('获取认证对象 get userAuth instance successfully.');
      // 订阅认证结果
      userAuthInstance.on('result', {
        onResult: (result: userAuth.UserAuthResult) => {
          try {
            console.info('订阅认证结果 userAuthInstance callback.' + JSON.stringify(result));
          //认证结果。包含认证结果码、认证令牌（成功时）、认证类型和凭据状态等信息。应用应检查result.result字段判断认证是否成功：
            //
            // - 若result.result为SUCCESS(12500000)，表示认证通过，可使用result.token进行后续操作。
            //
            // - 若result.result为其他值，表示认证不通过，应根据具体错误码进行处理。
            if (result.result === 12500000) {
              this.lookData = true
            } else {
              this.lookData = true
            }
            // 可在认证结束或其他业务需要场景，取消订阅认证结果。
            userAuthInstance.off('result');
          } catch (error) {
            const err: BusinessError = error as BusinessError;
            console.error(`认证失败 onResult failed, code: ${err?.code}, Message: ${err?.message}`);
          }
        }
      });
      // 启动认证
      userAuthInstance.start();
      console.info('启动认证 auth start successfully.');
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error(`启动认证 auth failed, code is ${err?.code}, message is ${err?.message}`);
    }
  }

  build() {
    Column({ space: 30 }) {
      Text(this.message)
        .margin({ top: 50 })
        .fontSize($r('app.float.text_size_18fp'))
        .onClick(() => {
          let obtainingSupported = this.obtainingSupported();
          if (obtainingSupported) {
            this.initiatingUserAuthentication1()
          } else {
            promptAction.openToast({ message: "当前设备不支持面容解锁", duration: 5000})
          }
        })

      Text("个人信息相关数据")
        .fontSize(20)
        .fontColor(Color.Black)
        .visibility(this.lookData ? Visibility.Visible : Visibility.None)
    }
    .height('100%')
    .width('100%')
  }
}

entry里module.json5，申请权限

 "requestPermissions": [
      {
      		"name": "ohos.permission.ACCESS_BIOMETRIC",
        "reason": "$string:reason"
      }
 ]

HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

HarmonyOS 3DGS × Node.js：重建输入帧序与采集断点校验【鸿蒙心迹】

HarmonyOS开发者社区

我开发了一个华为鸿蒙练打字App

HarmonyOS开发者社区

不靠屏幕点击！依托鸿蒙 AI 开放能力，打造专属无障碍拍照应用

由律师跨界开发的HarmonyOS应用“拍张照片”，专为视障人士打造。凭借语音引导与智能拍照等无障碍设计，帮助他们自主记录生活、分享美好。生动诠释了“科技向善”的理念。

HarmonyOS开发者社区

所有评论(0)

查看更多评论

ChinaDragonDreamer

@ChinaDragon10

已为社区贡献87条内容

HarmonyOS：人脸识别

ChinaDragonDreamer

一、开发者准备

1.1 申请权限

二、查询支持的认证能力

2.1 接口说明

2.2 开发步骤

三、实战

所有评论(0)

温馨提示：您尚未绑定手机号

ChinaDragonDreamer