Flutter生物识别登录插件biometric_login的使用

Flutter插件biometric_login（即local_auth）提供了在设备上进行本地用户身份验证的方法。在支持的设备上，这包括通过指纹或面部识别等生物特征进行认证。

支持情况

* 注：Android SDK 16+ 支持大部分功能，但某些功能可能需要更高的版本。

使用方法

检查设备能力

要检查设备是否支持本地身份验证，可以调用 canCheckBiometrics 和/或 isDeviceSupported() 方法：

// 导入插件
import 'package:local_auth/local_auth.dart';

void _checkDeviceCapabilities() async {
  final LocalAuthentication auth = LocalAuthentication();

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

  // 检查设备是否支持任何身份验证方式
  final bool canAuthenticate =
      canAuthenticateWithBiometrics || await auth.isDeviceSupported();

  print('设备是否支持生物识别: $canAuthenticateWithBiometrics');
  print('设备是否支持身份验证: $canAuthenticate');
}

目前实现的生物识别类型包括：

• BiometricType.face（面部识别）
• BiometricType.fingerprint（指纹识别）
• BiometricType.weak（弱身份验证）
• BiometricType.strong（强身份验证）

获取已注册的生物识别方式

canCheckBiometrics 只能指示硬件支持，而不能表明设备上是否有生物识别方式已注册。要获取已注册的生物识别方式，可以调用 getAvailableBiometrics() 方法：

void _getEnrolledBiometrics() async {
  final LocalAuthentication auth = LocalAuthentication();

  // 获取已注册的生物识别方式列表
  final List<BiometricType> availableBiometrics =
      await auth.getAvailableBiometrics();

  if (availableBiometrics.isNotEmpty) {
    print('设备上已注册的生物识别方式: $availableBiometrics');
  }

  if (availableBiometrics.contains(BiometricType.strong) ||
      availableBiometrics.contains(BiometricType.face)) {
    print('设备支持强身份验证或面部识别');
  }
}

进行身份验证

通用身份验证

authenticate() 方法会尝试使用生物识别进行身份验证，如果失败则允许用户输入 PIN、图案或密码：

void _authenticateUser() async {
  final LocalAuthentication auth = LocalAuthentication();

  try {
    final bool didAuthenticate = await auth.authenticate(
      localizedReason: '请验证身份以查看账户余额', // 提示信息
    );

    if (didAuthenticate) {
      print('身份验证成功！');
    } else {
      print('身份验证失败！');
    }
  } on PlatformException catch (e) {
    print('身份验证失败: ${e.message}');
  }
}

仅限生物识别

如果需要强制使用生物识别，可以设置 biometricOnly 参数为 true：

void _authenticateBiometricOnly() async {
  final LocalAuthentication auth = LocalAuthentication();

  try {
    final bool didAuthenticate = await auth.authenticate(
      localizedReason: '请验证身份以继续',
      options: const AuthenticationOptions(biometricOnly: true),
    );

    if (didAuthenticate) {
      print('生物识别身份验证成功！');
    } else {
      print('生物识别身份验证失败！');
    }
  } on PlatformException catch (e) {
    print('生物识别身份验证失败: ${e.message}');
  }
}

注意：biometricOnly 不支持 Windows 平台，因为 Windows 实现基于 Windows Hello API，该 API 不允许选择身份验证方式。

自定义提示信息

如果默认提示信息不够友好，可以通过 AuthMessages 自定义提示信息：

void _authenticateWithCustomMessages() async {
  final LocalAuthentication auth = LocalAuthentication();

  try {
    final bool didAuthenticate = await auth.authenticate(
      localizedReason: '请验证身份以继续',
      authMessages: const [
        AndroidAuthMessages(
          signInTitle: '身份验证失败，请重试！',
          cancelButton: '取消',
        ),
        IOSAuthMessages(
          cancelButton: '取消',
        ),
      ],
    );

    if (didAuthenticate) {
      print('身份验证成功！');
    } else {
      print('身份验证失败！');
    }
  } on PlatformException catch (e) {
    print('身份验证失败: ${e.message}');
  }
}

异常处理

身份验证可能会抛出异常，常见的错误代码包括：

• notAvailable: 设备不支持生物识别。
• notEnrolled: 用户未注册生物识别方式。
• lockedOut: 身份验证被锁定。

示例代码如下：

void _handleErrors() async {
  final LocalAuthentication auth = LocalAuthentication();

  try {
    final bool didAuthenticate = await auth.authenticate(
      localizedReason: '请验证身份以继续',
      options: const AuthenticationOptions(useErrorDialogs: false),
    );

    if (didAuthenticate) {
      print('身份验证成功！');
    }
  } on PlatformException catch (e) {
    switch (e.code) {
      case 'notAvailable':
        print('设备不支持生物识别');
        break;
      case 'notEnrolled':
        print('用户未注册生物识别方式');
        break;
      case 'lockedOut':
        print('身份验证被锁定，请稍后再试');
        break;
      default:
        print('未知错误: ${e.message}');
    }
  }
}

iOS 集成

要在 iOS 上启用 Face ID，需要在 Info.plist 文件中添加以下键值对：

<key>NSFaceIDUsageDescription</key>
<string>为什么我的应用需要使用面部识别？</string>

缺少此配置会导致用户看到一条对话框，提示应用尚未更新以支持 Face ID。

Android 集成

活动更改

确保 local_auth 使用的是 FragmentActivity 而不是普通 Activity。修改 AndroidManifest.xml 文件：

<activity android:name=".MainActivity">
  <meta-data
    android:name="flutterEmbedding"
    android:value="2" />
</activity>

并继承自 FlutterFragmentActivity：

import io.flutter.embedding.android.FlutterFragmentActivity

class MainActivity : FlutterFragmentActivity() {
  // 主活动逻辑
}

权限声明

在 AndroidManifest.xml 中添加生物识别权限：

<uses-permission android:name="android.permission.USE_BIOMETRIC" />

完整示例

以下是完整的示例代码：

import 'package:flutter/material.dart';
import 'package:local_auth/local_auth.dart';

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

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return const MaterialApp(
      title: 'Flutter Biometric Login',
      home: BioMetricsLogin(),
    );
  }
}

class BioMetricsLogin extends StatefulWidget {
  [@override](/user/override)
  _BioMetricsLoginState createState() => _BioMetricsLoginState();
}

class _BioMetricsLoginState extends State<BioMetricsLogin> {
  final LocalAuthentication auth = LocalAuthentication();

  Future<void> _authenticateUser() async {
    try {
      final bool didAuthenticate = await auth.authenticate(
        localizedReason: '请验证身份以继续',
      );

      if (didAuthenticate) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('身份验证成功！')),
        );
      } else {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('身份验证失败！')),
        );
      }
    } on PlatformException catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('身份验证失败: ${e.message}')),
      );
    }
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('生物识别登录示例')),
      body: Center(
        child: ElevatedButton(
          onPressed: _authenticateUser,
          child: Text('开始身份验证'),
        ),
      ),
    );
  }
}