cordova-plugin-fingerprint-aio

cordova-plugin-fingerprint-aio（All-In-One Fingerprint Plugin）是一款为 Cordova 应用打造的跨平台生物识别插件，支持 Android 指纹识别、iOS 指纹（Touch ID）与面容识别（Face ID），OHOS指纹识别，提供统一的认证接口与安全的密钥存储能力。适用于应用登录、敏感操作授权（如支付确认、数据加密）等场景，提升应用安全性与用户体验。本文档主要说明在HamronyOS系统中的应用。

在生物识别中是选择指纹、人脸是有系统自动选择，在OHOS系统中不能通过接口设置。

1. 插件概述

作为 Cordova 生态中生物识别领域的主流插件，cordova-plugin-fingerprint-aio 基于原生平台生物识别框架开发（Android Fingerprint API、iOS LocalAuthentication Framework），具备以下核心价值：

• 全平台生物识别支持：Android 端支持指纹识别（API Level 23+），iOS 端支持 Touch ID（iPhone 5s+、iPad Pro/Air 2+）与 Face ID（iPhone X+、iPad Pro 11-inch+），OHOS 5.0+指纹识别。

• 统一认证接口：屏蔽 Android 、 iOS 和 OHOS 平台差异，使用同一套 API 实现生物识别认证，降低开发成本

• 安全密钥存储：支持将敏感数据（如用户令牌、加密密钥）存储在设备安全区域（Android Keystore、iOS、OHOS Keychain），仅通过生物识别授权后可访问

• 灵活的用户提示：可自定义认证弹窗标题、副标题、描述文本与取消按钮文案，匹配应用视觉风格

• 错误处理完善：提供详细的错误码与描述（如 “设备不支持”“用户取消认证”“生物识别已锁定”），便于业务逻辑处理

• 轻量化设计：插件体积小（约 100KB），无第三方依赖，集成后不影响应用启动速度与运行性能

2. 安装方式

2.1 基础安装（默认配置）

在 Cordova 项目根目录执行以下命令，安装插件并自动配置基础依赖：

# 安装hcordova
npm install -g hcordova

# 安装最新版本
hcordova plugin add cordova-plugin-fingerprint-aio

# 安装指定版本

hcordova plugin add [email protected] --platform ohos

2.2 从 GitCode 源码安装

若需使用开发中的最新功能，可直接从 GitCode 仓库安装：

hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-fingerprint-aio.git --platform ohos

2.3 卸载插件

如需移除插件，执行以下命令清理配置与依赖：

#全平台卸载
hcordova plugin remove cordova-plugin-fingerprint-aio

#指定OHOS卸载
hcordova plugin remove cordova-plugin-fingerprint-aio --platform ohos

3. API 文档

插件通过全局对象 window.Fingerprint 暴露所有 API，支持 Promise 调用方式（推荐）与回调函数调用方式。所有 API 需在 deviceready 事件触发后调用，避免因原生接口未初始化导致错误。

3.1 核心 API

3.1.1 检查设备生物识别支持状态

//是否支持生物认证
Fingerprint.isAvailable(function(result){
   console.log("生物识别支持状态：", result);
   if (result.isAvailable) {
      // 设备支持生物识别，可显示指纹登录按钮
   } else {
      // 设备不支持，隐藏指纹登录按钮
   }
},function(error){
   // 设备不支持，隐藏指纹登录按钮
},{requireStrongBiometrics:true})

3.1.2 执行生物识别认证

/**
* 执行生物识别认证
* @param {AuthenticationOptions} options - 认证配置参数（可选）
* @returns {Promise<void>} - 认证成功则 resolved，失败则 rejected 并返回错误信息
*/

Fingerprint.show({
   description: "Some biometric description"
},  function successCallback(){
   console.log("Authentication successful");
}, function errorCallback(error){
   console.log("Authentication invalid " + error.message);
});
    

3.1.3 安全存储敏感数据

//OHOS不能存储，只有OHOS系统可以存储，失效效果和show函数相同
function successCallback(){
   console.log("Authentication successful");
}

function errorCallback(error){
   console.log("Authentication invalid " + error.message);
}
Fingerprint.registerBiometricSecret({
        description: "Some biometric description", 
        secret: "my-super-secret",//OHOS无效
        invalidateOnEnrollment: true,
        disableBackup: true, // //OHOS无效
    }, successCallback, errorCallback);

6.2.4 读取安全存储的敏感数据

//OHOS不能存储，只有OHOS系统可以存储，失效效果和show函数相同
function successCallback(secret){
   console.log("Authentication successful, secret: " + secret);
}

function errorCallback(error){
   console.log("Authentication invalid " + error.message);
}

Fingerprint.loadBiometricSecret({
   description: "Some biometric description",
   disableBackup: true, 
}, successCallback, errorCallback);

参考资源

• Android和iOS：cordova-plugin-fingerprint-aio 官方指南

• GitCode 仓库：OpenHarmony-Cordova/cordova-plugin-fingerprint-aio