Flutter Local Auth 在鸿蒙平台的使用指南

插件介绍

Local Auth 是 Flutter 官方提供的一个用于在设备上进行本地身份验证的插件，支持生物识别（如指纹、面部识别等）和设备级别的身份验证（如密码、PIN 码等）。该插件为跨平台开发提供了统一的 API，使开发者能够轻松实现安全的用户身份验证功能。

对于鸿蒙平台，Local Auth 提供了完整的支持，包括：

• 生物识别硬件检测
• 已注册生物识别类型查询
• 生物识别或设备密码验证
• 自定义验证选项（仅生物识别、错误对话框、后台恢复验证等）

版本兼容性

平台	支持版本要求
鸿蒙	API 12+
Flutter	>=3.7.0
Dart	>=2.19.0 <4.0.0

依赖配置

由于这是自定义修改版本，需要通过 Git 方式引入依赖。在 Flutter 项目的 pubspec.yaml 文件中添加以下配置：

dependencies:
  local_auth:
    git:
      url: "https://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/local_auth/local_auth"

添加依赖后，执行以下命令获取依赖包：

flutter pub get

鸿蒙平台权限配置

使用 Local Auth 插件需要在鸿蒙应用中配置生物识别访问权限。请按照以下步骤操作：

1. 添加权限声明

打开 entry/src/main/module.json5 文件，添加生物识别权限配置：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.ACCESS_BIOMETRIC",
        "reason": "$string:EntryAbility_accessBiometricReason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

2. 添加权限申请说明

打开 entry/src/main/resources/base/element/string.json 文件，添加权限申请原因：

{
  "string": [
    {
      "name": "EntryAbility_accessBiometricReason",
      "value": "用于验证用户身份"
    }
  ]
}

API 调用示例

1. 初始化 LocalAuth 实例

import 'package:local_auth/local_auth.dart';

final LocalAuthentication auth = LocalAuthentication();

2. 检查设备支持情况

// 检查是否支持生物识别
final bool canAuthenticateWithBiometrics = await auth.canCheckBiometrics;

// 检查是否支持设备级身份验证（生物识别或密码）
final bool canAuthenticate = 
    canAuthenticateWithBiometrics || await auth.isDeviceSupported();

if (canAuthenticate) {
  // 设备支持身份验证
} else {
  // 设备不支持身份验证
}

3. 获取已注册的生物识别类型

final List<BiometricType> availableBiometrics = 
    await auth.getAvailableBiometrics();

if (availableBiometrics.isNotEmpty) {
  print('已注册的生物识别类型：$availableBiometrics');
  
  // 检查是否支持特定类型的生物识别
  if (availableBiometrics.contains(BiometricType.face)) {
    // 支持面部识别
  }
  
  if (availableBiometrics.contains(BiometricType.fingerprint)) {
    // 支持指纹识别
  }
}

4. 执行身份验证

try {
  final bool didAuthenticate = await auth.authenticate(
    localizedReason: '请验证您的身份以继续',
    options: const AuthenticationOptions(
      biometricOnly: false, // 是否仅使用生物识别
      useErrorDialogs: true, // 是否使用默认错误对话框
      stickyAuth: true, // 应用切到后台后恢复验证
    ),
  );
  
  if (didAuthenticate) {
    print('身份验证成功');
    // 执行需要验证的操作
  } else {
    print('身份验证失败');
  }
} on PlatformException catch (e) {
  // 处理异常情况
  print('身份验证异常：${e.code} - ${e.message}');
  
  // 常见错误代码处理
  switch (e.code) {
    case 'notAvailable':
      // 设备不支持身份验证
      break;
    case 'notEnrolled':
      // 未注册生物识别
      break;
    case 'lockedOut':
      // 验证失败次数过多，暂时锁定
      break;
    case 'permanentlyLockedOut':
      // 验证失败次数过多，永久锁定
      break;
    default:
      // 其他错误
  }
}

5. 停止身份验证

await auth.stopAuthentication();

完整示例代码

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:local_auth/local_auth.dart';
import 'package:local_auth/error_codes.dart' as auth_error;

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Local Auth Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const AuthScreen(),
    );
  }
}

class AuthScreen extends StatefulWidget {
  const AuthScreen({super.key});

  @override
  State<AuthScreen> createState() => _AuthScreenState();
}

class _AuthScreenState extends State<AuthScreen> {
  final LocalAuthentication _auth = LocalAuthentication();
  String _status = '点击按钮开始验证';

  Future<void> _checkBiometrics() async {
    try {
      final bool canCheckBiometrics = await _auth.canCheckBiometrics;
      final bool isDeviceSupported = await _auth.isDeviceSupported();
      
      setState(() {
        _status = '生物识别支持: $canCheckBiometrics\n设备支持验证: $isDeviceSupported';
      });
    } on PlatformException catch (e) {
      setState(() {
        _status = '检查异常: ${e.message}';
      });
    }
  }

  Future<void> _getAvailableBiometrics() async {
    try {
      final List<BiometricType> availableBiometrics = await _auth.getAvailableBiometrics();
      
      setState(() {
        _status = '已注册生物识别类型: $availableBiometrics';
      });
    } on PlatformException catch (e) {
      setState(() {
        _status = '获取异常: ${e.message}';
      });
    }
  }

  Future<void> _authenticate() async {
    try {
      final bool didAuthenticate = await _auth.authenticate(
        localizedReason: '请验证身份以访问安全内容',
        options: const AuthenticationOptions(
          biometricOnly: false,
          useErrorDialogs: true,
          stickyAuth: true,
        ),
      );
      
      setState(() {
        _status = didAuthenticate ? '验证成功!' : '验证失败!';
      });
    } on PlatformException catch (e) {
      String errorMessage = '验证异常';
      
      switch (e.code) {
        case auth_error.notAvailable:
          errorMessage = '设备不支持身份验证';
          break;
        case auth_error.notEnrolled:
          errorMessage = '未注册生物识别，请先在设置中添加';
          break;
        case auth_error.lockedOut:
          errorMessage = '验证失败次数过多，暂时锁定';
          break;
        case auth_error.permanentlyLockedOut:
          errorMessage = '验证失败次数过多，永久锁定';
          break;
        default:
          errorMessage = '验证失败: ${e.message}';
      }
      
      setState(() {
        _status = errorMessage;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Local Auth 演示')),
      body: Center(
        child: Padding(
          padding: const EdgeInsets.all(20.0),
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text(
                _status,
                textAlign: TextAlign.center,
                style: const TextStyle(fontSize: 18),
              ),
              const SizedBox(height: 30),
              ElevatedButton(
                onPressed: _checkBiometrics,
                child: const Text('检查设备支持'),
              ),
              ElevatedButton(
                onPressed: _getAvailableBiometrics,
                child: const Text('获取已注册生物识别类型'),
              ),
              ElevatedButton(
                onPressed: _authenticate,
                child: const Text('开始身份验证'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

鸿蒙平台注意事项

1. 权限配置：必须正确配置 ohos.permission.ACCESS_BIOMETRIC 权限，否则应用将无法访问生物识别功能。

2. API 支持：鸿蒙平台支持 Local Auth 的所有核心 API，包括：

   • deviceSupportsBiometrics: 检查生物识别硬件支持
   • isDeviceSupported: 检查本地身份验证支持
   • getEnrolledBiometrics: 获取已注册生物识别类型
   • authenticate: 执行身份验证
   • stopAuthentication: 取消当前验证

3. 生物识别类型：支持的生物识别类型包括：

   • BiometricType.face: 面部识别
   • BiometricType.fingerprint: 指纹识别
   • BiometricType.weak: 弱生物识别
   • BiometricType.strong: 强生物识别

4. 验证选项：

   • biometricOnly: 是否仅使用生物识别进行验证（设置为 true 时，用户无法选择使用密码）
   • useErrorDialogs: 是否显示默认的错误提示对话框
   • stickyAuth: 应用切换到后台后，是否在返回前台时恢复验证

总结

Local Auth 插件为 Flutter 开发者提供了在鸿蒙平台上实现安全身份验证的便捷方式。通过简单的 API 调用，开发者可以轻松集成生物识别或设备密码验证功能，增强应用的安全性。

使用该插件时，需要注意以下几点：

1. 正确配置 Git 依赖
2. 为鸿蒙应用添加必要的生物识别权限
3. 根据需求选择合适的验证选项
4. 处理可能的异常情况

通过本文的介绍，您应该已经了解了如何在 Flutter 鸿蒙项目中集成和使用 Local Auth 插件，为您的应用添加安全的身份验证功能。