You need to enable JavaScript to run this app. React Native使用react-native-fingerprint-scanner实现自定义指纹弹窗咨询
优惠活动
大模型
产品
解决方案
定价
更多

React Native使用react-native-fingerprint-scanner实现自定义指纹弹窗咨询

自定义全版本指纹认证弹窗实现方案

完全可以基于现有react-native-fingerprint-scanner的能力实现全版本统一的自定义模态框,核心是禁用库默认触发的系统原生认证UI,将所有指纹识别事件暴露到JS层,自行实现弹窗UI与事件绑定。

核心改造思路

现有代码在Android API≥23时会触发系统默认BiometricPrompt,本质是调用authenticate方法时没有传入禁用原生弹窗的配置,只需要调整两个点即可:

  • 对所有Android版本的authenticate调用,添加disableAuthenticationDialog: true参数,强制关闭系统默认认证弹窗,所有识别状态全部由JS层接收。
  • 不再分版本分支渲染不同UI,统一复用自定义弹窗组件,根据识别事件动态更新弹窗的提示内容、状态。

改造后的完整BiometricPopup组件代码

import { View, Platform, Text, TouchableOpacity, StyleSheet } from 'react-native';
import FingerprintScanner from 'react-native-fingerprint-scanner';
import PropTypes from 'prop-types';

class BiometricPopup extends Component {
  static propTypes = {
    onAuthenticate: PropTypes.func.isRequired,
    onDismiss: PropTypes.func.isRequired,
    title: PropTypes.string,
    subtitle: PropTypes.string,
  };

  static defaultProps = {
    title: '生物认证登录',
    subtitle: '请按提示验证指纹',
  };

  state = {
    errorMsg: '',
    isScanning: true,
  };

  componentDidMount() {
    // 统一启动指纹认证,禁用系统原生弹窗
    this.startAuthentication();
  }

  componentWillUnmount() {
    // 组件销毁必须释放识别资源
    FingerprintScanner.release();
  }

  requiresLegacyAuthentication = () => {
    return Platform.OS === 'android' && Platform.Version < 23;
  };

  startAuthentication = () => {
    const authConfig = this.requiresLegacyAuthentication() 
      ? {
          // 旧版本Android配置,绑定单次尝试失败的回调
          onAttempt: this.handleAuthAttempt,
          disableAuthenticationDialog: true,
        } 
      : {
          // 高版本Android/iOS配置,禁用所有系统默认弹窗
          disableAuthenticationDialog: true,
          title: this.props.title,
          subtitle: this.props.subtitle,
        };

    FingerprintScanner
      .authenticate(authConfig)
      .then(() => {
        // 识别成功:更新状态,关闭弹窗,触发外部回调
        this.setState({ isScanning: false, errorMsg: '验证成功' });
        setTimeout(() => {
          this.props.onAuthenticate();
        }, 300);
      })
      .catch(this.handleAuthError);
  };

  handleAuthAttempt = (error) => {
    // 旧版本Android单次尝试失败的回调
    this.setState({ errorMsg: error.message || '指纹识别失败,请重试' });
  };

  handleAuthError = (error) => {
    // 统一处理所有版本的认证异常
    const { name, message } = error;
    switch (name) {
      case 'AUTHENTICATION_FAILED':
        this.setState({ errorMsg: '指纹识别失败,请重试' });
        // 失败后可以重新触发认证,也可以直接终止
        // this.startAuthentication();
        break;
      case 'LOCKOUT':
      case 'LOCKOUT_PERMANENT':
        this.setState({ isScanning: false, errorMsg: '尝试次数过多,暂时无法使用指纹认证' });
        break;
      case 'USER_CANCELED':
      case 'SYSTEM_CANCELED':
      case 'USER_FALLBACK':
        // 用户主动取消,直接关闭弹窗
        FingerprintScanner.release();
        this.props.onDismiss();
        break;
      default:
        this.setState({ isScanning: false, errorMsg: message || '认证不可用' });
    }
  };

  handleCancel = () => {
    // 用户点击自定义弹窗的取消按钮
    FingerprintScanner.release();
    this.props.onDismiss();
  };

  render() {
    const { errorMsg, isScanning } = this.state;
    const { title, subtitle } = this.props;

    return (
      <View style={styles.mask}>
        <View style={styles.popupContainer}>
          <Text style={styles.title}>{title}</Text>
          <Text style={styles.subtitle}>{subtitle}</Text>
          <Text style={[styles.statusText, errorMsg ? styles.errorText : styles.scanningText]}>
            {isScanning ? (errorMsg || '请将手指放在指纹识别区域') : errorMsg}
          </Text>
          <TouchableOpacity style={styles.cancelBtn} onPress={this.handleCancel}>
            <Text style={styles.cancelBtnText}>取消</Text>
          </TouchableOpacity>
        </View>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  mask: {
    position: 'absolute',
    top: 0,
    bottom: 0,
    left: 0,
    right: 0,
    backgroundColor: 'rgba(0,0,0,0.5)',
    justifyContent: 'center',
    alignItems: 'center',
  },
  popupContainer: {
    width: '80%',
    backgroundColor: '#fff',
    borderRadius: 12,
    padding: 24,
    alignItems: 'center',
  },
  title: {
    fontSize: 18,
    fontWeight: '600',
    marginBottom: 12,
  },
  subtitle: {
    fontSize: 14,
    color: '#666',
    marginBottom: 24,
  },
  statusText: {
    fontSize: 14,
    marginBottom: 24,
    textAlign: 'center',
  },
  scanningText: {
    color: '#333',
  },
  errorText: {
    color: '#ff3b30',
  },
  cancelBtn: {
    width: '100%',
    height: 44,
    justifyContent: 'center',
    alignItems: 'center',
    borderTopWidth: 1,
    borderTopColor: '#eee',
  },
  cancelBtnText: {
    fontSize: 16,
    color: '#007aff',
  },
});

export default BiometricPopup;

注意事项

  • 必须按照库的配置要求,提前在Android端申请USE_FINGERPRINT、USE_BIOMETRIC权限,iOS端在Info.plist添加NSFaceIDUsageDescription配置,否则无法正常调用识别能力。
  • 单次识别失败后如果需要继续尝试,可在错误处理逻辑中手动调用startAuthentication重启识别流程,注意要先调用FingerprintScanner.release()避免硬件占用冲突。
  • 如果需要添加指纹识别的动效(比如指纹扫描动画),可以根据isScanning状态在弹窗内添加对应的动画组件即可。

内容的提问来源于stack exchange,提问作者pro123908

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.13 15:15:07