@cordova-ohos/cordova-plugin-fingerprint-aio

v6.0.2

Published

4 days ago

Cordova fingerprint-aio Plugin

Downloads

840

0High
0Medium
0Low

cordova fingerprint-aio ecosystem:cordova cordova-openharmony

cordova-plugin-fingerprint-aio

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

cordova-plugin-fingerprint-aio

简介

cordova-plugin-fingerprint-aio（All-In-One Fingerprint Plugin）是 Cordova 生态中生物识别领域的主流插件，专为 Cordova 应用打造的跨平台生物识别工具，基于原生平台生物识别框架开发（Android Fingerprint API、iOS LocalAuthentication Framework），支持 Android 指纹识别、iOS 指纹（Touch ID）与面容识别（Face ID）及 OHOS 指纹识别，提供统一的认证接口与安全的密钥存储能力，适用于应用登录、敏感操作授权（如支付确认、数据加密）等场景，可有效提升应用安全性与用户体验。本文档重点说明其在 OpenHarmony 系统中的应用方法，核心价值如下：

全平台生物识别支持：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），无第三方依赖，集成后不影响应用启动速度与运行性能

支持平台

Android：API Level 23 及以上（支持指纹识别）
iOS：10.0 及以上（支持 Touch ID、Face ID，适配 iPhone 5s+、iPad Pro/Air 2+、iPhone X+ 等设备）
OHOS：5.0 及以上（支持指纹识别）

下载安装

通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取，适配 OHOS 平台安装需求，可选择安装最新版本、指定版本或开发版本。

从 npm 安装（推荐）

# 安装 hcordova 命令化工具
npm install -g hcordova

# 安装最新版本（全平台）
hcordova plugin add cordova-plugin-fingerprint-aio

# 安装指定平台（仅 OHOS 平台）
hcordova plugin add cordova-plugin-fingerprint-aio --platform ohos

# 仅安装到 OHOS 平台，指定 1.0.0 版本
hcordova plugin add [email protected] --platform ohos

从 GitCode 仓库安装

仅为 OHOS 平台安装开发版本插件，可获取最新开发中的功能：

# 仅安装到 OHOS 平台，安装 GitCode 开发版本
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-fingerprint-aio.git --platform ohos

# 仅安装到 OHOS 平台，安装 GitCode 开发版本，指定标签/分支
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-fingerprint-aio.git@develop --platform ohos

离线安装（本地包）

适用于无网络环境，先下载插件包到本地，再执行离线安装：

# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-fingerprint-aio）
# 执行离线安装
hcordova plugin add ../Downloads/cordova-plugin-fingerprint-aio  --platform ohos

安装后验证

安装完成后，可通过以下命令验证插件是否成功添加到项目中：

# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list

卸载

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

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

约束与限制

平台版本约束：需符合各平台最低版本要求（Android API Level 23+、iOS 10.0+、OHOS 5.0+），低于该版本可能出现功能异常或无法使用
OHOS 特性约束：OHOS 系统中，生物识别（指纹/人脸）由系统自动选择，无法通过接口手动设置；且不支持敏感数据存储功能，registerBiometricSecret 和 loadBiometricSecret 方法在 OHOS 平台仅触发认证，不执行存储/读取操作
调用时机：所有 API 需在 deviceready 事件触发后调用，避免因原生接口未初始化导致报错
设备支持约束：需确保设备具备相应的生物识别硬件（如指纹传感器、面容识别模块），否则 isAvailable 方法会返回不支持状态

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |

在以下版本中已测试通过：

| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |

使用示例

以下提供 OHOS 平台常用使用示例，涵盖设备支持检查、生物识别认证、敏感数据存储/读取（注：OHOS 不支持存储/读取，仅触发认证），可直接复制到项目中调试使用，所有示例均需在 deviceready 事件触发后执行。

示例 1：检查设备生物识别支持状态

判断设备是否支持生物识别，根据返回结果展示或隐藏指纹登录按钮，适配 OHOS 平台特性。

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

示例 2：执行生物识别认证

触发生物识别认证流程，自定义认证提示文案，处理认证成功与失败逻辑，适配 OHOS 系统自动选择生物识别方式的特性。

/**
* 执行生物识别认证
* @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：安全存储敏感数据

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);

示例 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);

使用说明

本插件核心功能为跨平台生物识别认证与敏感数据安全存储（OHOS 平台不支持存储/读取），适配 OHOS 平台特性，通过全局对象 window.Fingerprint 暴露所有 API，支持 Promise 调用方式（推荐）与回调函数调用方式，所有 API 需在 deviceready 事件触发后调用。

核心 API 说明

插件所有核心 API 均通过全局对象 window.Fingerprint 暴露，涵盖设备支持检查、生物识别认证、敏感数据存储与读取四大功能，其中敏感数据存储/读取在 OHOS 平台无效，仅触发认证流程。

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

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

参数说明：requireStrongBiometrics（可选，布尔值）：是否要求强生物识别，默认 true，OHOS 平台适配该参数。

返回结果：result 对象包含 isAvailable（布尔值，是否支持生物识别）、biometryType（字符串，生物识别类型，OHOS 平台仅返回“fingerprint”）。

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);
});

参数说明：options（可选，对象）：包含 description（认证弹窗描述文本）、title（弹窗标题，可选）、subtitle（弹窗副标题，可选）、cancelButtonText（取消按钮文案，可选）。

回调说明：successCallback（认证成功回调，无参数）；errorCallback（认证失败回调，参数为 error 对象，包含错误信息）。

3. 安全存储敏感数据

// 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);

参数说明：options（必填，对象）：description（认证弹窗描述）、secret（需存储的敏感数据，OHOS 无效）、invalidateOnEnrollment（布尔值，重新录入生物识别后是否失效，默认 true）、disableBackup（布尔值，是否禁用备份密码，OHOS 无效）。

注意：OHOS 平台调用该方法仅触发生物识别认证，不存储任何数据，认证成功/失败回调与 show 函数一致。

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);

参数说明：options（必填，对象）：description（认证弹窗描述）、disableBackup（布尔值，是否禁用备份密码，OHOS 无效）。

注意：OHOS 平台调用该方法仅触发生物识别认证，不读取任何数据，successCallback 不会返回 secret 参数，认证成功/失败回调与 show 函数一致。

目录结构

cordova-plugin-fingerprint-aio/
├── src/                          # 源代码目录
│   └── main/                     # 主要源代码
│       ├── cpp/                  # C++ 原生代码
│       │   └── Fingerprint/      # 指纹模块
│       │       ├── Fingerprint.cpp  # 指纹识别功能的 C++ 实现
│       │       └── Fingerprint.h    # 指纹识别功能的头文件
│       └── ets/                  # ArkTS 代码（OpenHarmony API）
│           └── components/       # 组件目录
│               └── Fingerprint/  # 指纹组件
│                   └── Fingerprint.ets  # 指纹识别的 ArkTS 实现
├── www/                          # Web 资源目录
│   └── Fingerprint.js            # JavaScript 指纹识别接口（Cordova 桥接层）
├── .gitignore                    # Git 忽略文件配置
├── LICENSE                       # 项目开源许可证
├── OAT.xml                       # OpenHarmony 审核配置文件
├── package.json                  # Node.js 包配置
├── plugin.xml                    # Cordova 插件描述文件（核心配置）
└── README.md                     # 项目说明文档

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。

许可证

本插件基于 Apache License 开源，详见 LICENSE 文件。

官方资源

Android 和 iOS：cordova-plugin-fingerprint-aio 官方指南
GitCode 仓库：CPF-Cordova/cordova-plugin-fingerprint-aio