# @capgo/capacitor-native-biometric 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-native-biometric/

版本：8\.9\.1
npm 元数据更新时间：2026-10-20T22:41:34.796Z
中文译文更新时间：2026-11-09T01:56:55.656Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-native-biometric
原文对照：https://npmcn.com/package/%40capgo/capacitor-native-biometric/?lang=original
项目主页：https://capgo.app/docs/plugins/native-biometric/
源码仓库：https://github.com/Cap-go/capacitor-native-biometric

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：429 kB，37 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2023-05-23T01:06:12.566Z
- 最新版本发布：2026-10-20T22:41:34.504Z
- 近 30 天下载量：972225（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：80（近 12 个月 53 个）

## 中文简介

此插件为 Android 和 iOS 提供了本地生物鉴别类的访问权限

## 安装

```sh
npm install @capgo/capacitor-native-biometric
```

也可以使用：`pnpm add @capgo/capacitor-native-biometric`、`yarn add @capgo/capacitor-native-biometric`、`bun add @capgo/capacitor-native-biometric`

## README

# 原生生物测量仪

在您的 Capacitor app 上添加 Face ID,触摸 ID 和指纹登录,并在 iOS 键链和 Android Keystore 中保存证书安全.

[![Capgo - Instant updates for Capacitor](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-native-biometric)](https://capgo.app/?ref=plugin_native_biometric)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_native_biometric)

14天无限自由审判. 不需要信用卡

![@capgo/capacitor-native-biometric for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-native-biometric/main/assets/github-social-preview.png)

## 主要特点

-   **生物测量检查**数字 : `isAvailable()` 返回生物测量类型,带有可选设备证书倒置.
-   **认证**数字 : `verifyIdentity()` 显示本地生物识别提示.
-   **全权证书**数字 : `setCredentials()`, (中文(简体) ), `getCredentials()`, (中文(简体) ), `getSecureCredentials()` 财务报告和审定财务报表 `deleteCredentials()` 每个服务器.
-   **安全数据**数字 : `setData()`, (中文(简体) ), `getData()` 财务报告和审定财务报表 `getSecureData()` 存储任意字符串值.
-   **改变事件**页:1 `biometryChange` 当应用程序恢复时, 聆听器会运行, 这样您就可以检测在背景中所做的注册更改 .
-   **平台**: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. 网络为发展提供模拟.

## 为什么是原生生物?

A 类 **免费**, (中文(简体) ), **综合** 具有安全证书存储的生物鉴别认证插件 :

-   **所有生物鉴别类型** - 脸部身份、触摸身份、指纹、脸部认证、Iris和装置证书(PIN、图案、密码)
-   **安全证书存储** - 键链(iOS)和键盘(Android)集成
-   **弹性倒置** - 生物鉴别技术缺乏时可选密码回落
-   **自定义 UI** - 充分控制提示、标题、说明、按钮文本
-   **详细错误代码** - 跨iOS和Android的统一错误处理
-   **继续收听器** - 在应用程序从背景返回时检测生物计量可用性的变化
-   **现代软件包管理** - 支持Swift软件包管理器(SPM)和CocoaPods(SPM-为Capacitor 8准备)

适合银行应用程序,密码管理器,认证流,以及任何需要安全用户验证的应用程序.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/native-biometric/ 互联网档案馆的存檔,存档日期2013-12-21](https://capgo.app/docs/plugins/native-biometric/)

## 安全考虑

### 重要: 验证身份( ) 可在根/ 断接设备上通过

这个 `verifyIdentity()` 方法 **不应作为唯一的认证机制** 用于敏感行动。 在扎根的Android设备或jailbroken iOS设备上,攻击者可以使用Frida,Xposed等工具或类似的框架来:

-   钩住 JavaScript 桥并强制 `verifyIdentity()` 以返回成功
-   拦截本地方法呼叫和绕过生物鉴别认证
-   修改应用程序的运行时行为以跳过认证检查

### 建议的安保做法

1.  **使用根/ 断层检测**:通过检测被损坏的设备来保护您的应用程序. 我们建议使用 **[@ capgo/ 电容- is- root](https://github.com/Cap-go/capacitor-is-root)** 检测根/断裂设备的插件 :

```typescript
import { IsRoot } from '@capgo/capacitor-is-root';

async function checkDeviceSecurity() {
  const { result } = await IsRoot.isRooted();
  
  if (result) {
    // Handle rooted device - show warning, restrict features, or block access
    console.warn('Device security compromised');
    return false;
  }
  return true;
}
```

2.  **永不存储敏感数据客户端**:不要依赖本地存储的证书进行关键认证. 使用 `verifyIdentity()` 作为方便的特征,而不是安全边界.
    
3.  **服务器系统验证**: 总是在后端服务器上验证认证. 生物计量认证应用于用户方便,真正的认证发生在服务器侧.
    
4.  **执行额外的安全层**数字 :
    
    -   API 调用证书 pinning
    -   执行服务器侧会话管理
    -   使用生物鉴别认证后过期的短寿命符号
    -   添加防卫生检查

### 安全使用模式

```typescript
import { NativeBiometric } from "@capgo/capacitor-native-biometric";
import { IsRoot } from '@capgo/capacitor-is-root';

async function secureAuthentication() {
  // 1. Check device security first
  const { result } = await IsRoot.isRooted();
  if (result) {
    // Handle rooted device appropriately
    // Example: showSecurityWarning() could display an alert to the user
    showSecurityWarning();
    // Optionally: disable biometric login, require re-authentication, etc.
  }

  // 2. Perform biometric authentication
  try {
    await NativeBiometric.verifyIdentity({
      reason: "Authenticate to access your account",
      title: "Biometric Login",
    });
  } catch (error) {
    console.error("Biometric authentication failed");
    return false;
  }

  // 3. Get stored credentials (if needed for convenience)
  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });

  // 4. CRITICAL: Validate credentials with your backend server
  // Example: validateWithServer() should send credentials to your API
  // and verify them server-side before granting access
  const isValid = await validateWithServer(credentials.username, credentials.password);
  
  return isValid;
}
```

### 此插件提供了什么

此插件提供 :

-   方便的本地生物鉴别认证
-   使用 Keychain (iOS) 和 Keystore (Android) 安全证书存储
-   \* 防止临时擅自进入

此插件不提供 :

-   \* 保护在受损装置上免遭有决心的攻击者
-   服务器端认证或验证
-   \* 根/断裂探测(使用) [@ capgo/ 电容- is- root](https://github.com/Cap-go/capacitor-is-root)(中文(简体) )

### 最近的安全改进(v8.2.0+)

**Android 加密增强**:Android的应用现在使用适当的随机化初始化矢量(IVs)对所储存的证书进行AES-GCM加密. 以前版本使用的是固定的IV,这是一种加密脆弱性.

**自动迁移**: 插件会用旧方法自动处理加密的证书 :

-   在读取证书时,它首先尝试新的安全格式,然后在必要时回到遗留格式
-   保存证书时, 总是使用新的安全格式进行加密
-   不需要用户采取行动 - 更新后在第一次证书保存时透明地进行迁移

**建议**:在被更新到v8.2.0+后,用户应重新保存其证书,以确保使用改进后的格式加密. 这在用户再次认证和保存证书时会自动发生.

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装( 仅支持 Capacitor 7)

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-native-biometric` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

-   `npm i @capgo/capacitor-native-biometric`

## 使用量

⚠️ **重要**:在实施生物鉴别认证之前,审查 [安全考虑](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-%EF%B8%8F-security-considerations) 理解安全执行的局限性和最佳做法.

```ts
import { NativeBiometric, BiometryType } from "@capgo/capacitor-native-biometric";

async performBiometricVerification(){
  const result = await NativeBiometric.isAvailable();

  if(!result.isAvailable) return;

  // Check the biometry type for display purposes
  // IMPORTANT: Always use isAvailable for logic decisions, not biometryType
  const isFaceID = result.biometryType == BiometryType.FACE_ID;

  // Check if device has PIN/pattern/password set
  console.log('Device is secure:', result.deviceIsSecure);

  // Check if strong biometry (Face ID, Touch ID, fingerprint) is available
  console.log('Strong biometry available:', result.strongBiometryIsAvailable);

  const verified = await NativeBiometric.verifyIdentity({
    reason: "For easy log in",
    title: "Log in",
    subtitle: "Maybe add subtitle here?",
    description: "Maybe a description too?",
  })
    .then(() => true)
    .catch(() => false);

  if(!verified) return;

  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });
  
  // IMPORTANT: Always validate credentials with your backend server
  // Do not trust client-side verification alone
}

// Save user's credentials
NativeBiometric.setCredentials({
  username: "username",
  password: "password",
  server: "www.example.com",
}).then();

// Check if credentials are already saved
const isSaved = await NativeBiometric.isCredentialsSaved({
  server: "www.example.com",
});
console.log('Credentials saved:', isSaved.isSaved);

// Delete user's credentials
NativeBiometric.deleteCredentials({
  server: "www.example.com",
}).then();

// Listen for biometry availability changes when app resumes from background
const handle = await NativeBiometric.addListener('biometryChange', (result) => {
  console.log('Biometry availability changed:', result.isAvailable);
  console.log('Biometry type:', result.biometryType);
});

// To remove the listener when no longer needed:
// await handle.remove();
```

### 完成登录流程示例

此示例显示如何使用 `isCredentialsSaved()` 在显示“ 保存证书” 弹出前检查是否保存了证书 :

```ts
// After successful login
async handleLoginSuccess(username: string, password: string) {
  // Check if biometric authentication is available
  const result = await NativeBiometric.isAvailable({ useFallback: true });
  
  if (!result.isAvailable) {
    // Biometrics not available - go to home page directly
    this.navigateToHome();
    return;
  }
  
  // Check if credentials are already saved
  const checkCredentials = await NativeBiometric.isCredentialsSaved({
    server: "www.example.com"
  });
  
  if (checkCredentials.isSaved) {
    // Credentials already saved - go to home page
    this.navigateToHome();
  } else {
    // No credentials saved - show save credentials popup
    this.showSaveCredentialsPopup(username, password);
  }
}

// Save credentials when user confirms
async saveCredentials(username: string, password: string) {
  await NativeBiometric.setCredentials({
    username: username,
    password: password,
    server: "www.example.com",
  });
  this.navigateToHome();
}
```

### 生物鉴别错误

这是可丢入错误代码的插件特定列表 `verifyIdentity()` 失败, 设置为 `isAvailable()`,或从 `getSecureCredentials()` 财务报告和审定财务报表 `getSecureData()` 当请求的服务器或密钥没有生物鉴别保护项时。 它将Android和iOS特定认证错误代码合并为一个综合错误列表.

| 代码 | 说明 | 平台 |
| --- | --- | --- |
| 0 个 | 未知错误 | Android, iOS (英语) |
| 1个 | 生物计量 | Android, iOS (英语) |
| 2个 | 用户锁定 | Android, iOS (英语) |
| 3个 | 未注册的生物计量 | Android, iOS (英语) |
| 页:1 | 用户临时锁定 | Android (Lockout for 30sec) (英语) |
| 10个 | 认证失败 | Android, iOS (英语) |
| 第11个 | 应用程序取消 | iOS系统 |
| 第12条 | 无效的上下文 | iOS系统 |
| 第13条 | 不互动 | iOS系统 |
| 页:1 | 密码未设置 | Android, iOS (英语) |
| 15个 | 系统取消 | Android, iOS (英语) |
| 16个 | 用户取消 | Android, iOS (英语) |
| 页:1 | 用户后退 | Android, iOS (英语) |
| 21国 | 没有找到受保护的证书/数据 | Android, iOS (英语) |

**代码 21 (`getSecureCredentials`, (中文(简体) ), `getSecureData`(中文(简体) )**,稳定,在没有生物特征保护的证书或数据时预计被拒绝(例如删除后,新安装,或因生物特征识别入学变化而失效的项目)。 平台信息略有不同:

-   **`getSecureCredentials()`**
    -   **机器人:** `No protected credentials found`
    -   **iOS: (英语)** `No protected credentials found for server`
-   **`getSecureData()`**
    -   **机器人:** `No protected data found`
    -   **iOS: (英语)** `No protected data found for key`

`isCredentialsSaved()` 财务报告和审定财务报表 `isDataSaved()` 当服务器或密钥存在任何证书或数据(受保护或无保护)时返回真实性,所以它们不保证 `getSecureCredentials()` 或者说 `getSecureData()` 将会成功 处理代码 `21` 或只用存储器拨打 `accessControl` (原始内容存档于2017-09-26). BIOMETRY CARRENT SET BIOMETRY Any. 见 [`getSecureCredentials()`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getsecurecredentials) 财务报告和审定财务报表 [`getSecureData()`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getsecuredata) 详细情况.

-   [`isAvailable(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-isavailable)
-   [`addListener('biometryChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-addlistenerbiometrychange-)
-   [`verifyIdentity(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-verifyidentity)
-   [`getCredentials(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getcredentials)
-   [`setCredentials(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-setcredentials)
-   [`deleteCredentials(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-deletecredentials)
-   [`getSecureCredentials(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getsecurecredentials)
-   [`isCredentialsSaved(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-iscredentialssaved)
-   [`setData(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-setdata)
-   [`getData(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getdata)
-   [`getSecureData(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getsecuredata)
-   [`deleteData(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-deletedata)
-   [`isDataSaved(...)`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-isdatasaved)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-enums)

### 可扩展(...)

```typescript
isAvailable(options?: IsAvailableOptions | undefined) => Promise<AvailableResult>
```

检查是否存在生物鉴别认证硬件.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[IsAvailableOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-isavailableoptions)` |

**回返情况:** `Promise<[AvailableResult](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-availableresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 生物测量变化 ” ,...)

```typescript
addListener(eventName: 'biometryChange', listener: BiometryChangeListener) => Promise<PluginListenerHandle>
```

添加一个当应用程序从背景恢复时调用的听众 . 这有助于检测生物测量可用性是否在变化的同时 应用程序的背景(如用户注册/未注册生物鉴别).

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'biometryChange'` | \- 一定是"生物测量变化" |
| **`listener`** | `[BiometryChangeListener](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometrychangelistener)` | \- 接收更新的召回函数 [可用结果](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-availableresult) |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-pluginlistenerhandle)>`

**自:** 7.6.0 (简体中文)

* * *

### 验证身份(...)

```typescript
verifyIdentity(options?: BiometricOptions | undefined) => Promise<void>
```

促使用户使用生物鉴别技术进行认证.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[BiometricOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometricoptions)` |

**自:** 1.0.0 (单位:千美元)

* * *

### 获取证书(...)

```typescript
getCredentials(options: GetCredentialOptions) => Promise<Credentials>
```

获取给定服务器的存储证书 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetCredentialOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getcredentialoptions)` |

**回返情况:** `Promise<[Credentials](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-credentials)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 证书(...)

```typescript
setCredentials(options: SetCredentialOptions) => Promise<void>
```

存储给定服务器的证书 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetCredentialOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-setcredentialoptions)` |

**自:** 1.0.0 (单位:千美元)

* * *

### 删除证书(...)

```typescript
deleteCredentials(options: DeleteCredentialOptions) => Promise<void>
```

删除给定服务器所存储的证书.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[DeleteCredentialOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-deletecredentialoptions)` |

**自:** 1.0.0 (单位:千美元)

* * *

### 获取证书(...)

```typescript
getSecureCredentials(options: GetSecureCredentialsOptions) => Promise<Credentials>
```

获取给定服务器的存储证书, 需要生物鉴别认证 . 证书必须保存在 BIOMETRY CURRENT SET 或 BIOMETRY ANY 的访问控制装置中.

在iOS上,系统在访问被保护的Keychain项目时自动显示生物鉴别提示. 在Android上,BiometricPrompt用一个Crypto对象绑定在证书解密密钥上显示.

如果服务器没有受保护的证书, 承诺会用代码拒绝 `21` (单位:千美元)[`BiometricAuthError.NO_PROTECTED_CREDENTIALS_FOUND`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometricautherror)) (中文(简体) ). 这是稳定的,预期 行为——例如当证书从未保存有生物鉴别保护时, 被删除,或者在生物鉴别学注册变更后作废. `isCredentialsSaved()` 当存在任何证书(受保护或无保护)时,返回为真实, 因此,它不能保证存在生物特征保护条目——处理码 `21` 内 您的捕获块或仅存储后拨打 `accessControl` 图片类型( C) 或BIOMETRY ANY。 。 . 平台信息: Android `No protected credentials found`,iOS系统 `No protected credentials found for server`。 。 。 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetSecureCredentialsOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getsecurecredentialsoptions)` |

**回返情况:** `Promise<[Credentials](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-credentials)>`

**自:** 8.4.0 (单位:百万美元)

* * *

### 证书保存(...)

```typescript
isCredentialsSaved(options: IsCredentialsSavedOptions) => Promise<IsCredentialsSavedResult>
```

检查是否已经为给定服务器保存了证书 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[IsCredentialsSavedOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-iscredentialssavedoptions)` |

**回返情况:** `Promise<[IsCredentialsSavedResult](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-iscredentialssavedresult)>`

**自:** 7.3.0 (单位:千美元)

* * *

### 设置数据 (...)

```typescript
setData(options: SetDataOptions) => Promise<void>
```

在给定的密钥下存储任意字符串值. 在休息时使用平台安全存储后端加密值 (Android Keystore + 共享优先,iOS keychain).

生物特征保护储存装置 `accessControl` 获取值 与 `getSecureData()`在用户名/密码流中仍然可以使用证书助手.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetDataOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-setdataoptions)` |

**自:** 8.6.0 (简体中文)

* * *

### 获取数据(...)

```typescript
getData(options: GetDataOptions) => Promise<StoredData>
```

为给定的密钥获取先前存储的值. 仅返回没有生物鉴别的存储值 `accessControl`。 。 。 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetDataOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getdataoptions)` |

**回返情况:** `Promise<[StoredData](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-storeddata)>`

**自:** 8.6.0 (简体中文)

* * *

### 获取SecureData (...)

```typescript
getSecureData(options: GetSecureDataOptions) => Promise<StoredData>
```

为给定的密钥获得生物鉴别保护值. 该值必须是用 `accessControl` 设置为 BIOMETRY CURRENT SET或BIOMETRY ANY.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetSecureDataOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-getsecuredataoptions)` |

**回返情况:** `Promise<[StoredData](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-storeddata)>`

**自:** 8.6.0 (简体中文)

* * *

### 删除数据(...)

```typescript
deleteData(options: DeleteDataOptions) => Promise<void>
```

删除所给密钥的存储值(受保护和无保护).

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[DeleteDataOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-deletedataoptions)` |

**自:** 8.6.0 (简体中文)

* * *

### 已保存数据(...)

```typescript
isDataSaved(options: IsDataSavedOptions) => Promise<IsDataSavedResult>
```

检查是否已为给定的密钥保存一个值 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[IsDataSavedOptions](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-isdatasavedoptions)` |

**回返情况:** `Promise<[IsDataSavedResult](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-isdatasavedresult)>`

**自:** 8.6.0 (简体中文)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本 .

**回返情况:** `Promise<{ version: string; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 接口

#### 可用结果

由表明生物鉴别认证可用性的Available()方法所产生.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`isAvailable`** | `boolean` | 认证是否可用 。 在Android上,只有弱小的生物鉴别技术(如一些面部解锁执行)可供使用 `verifyIdentity()` 否时 `allowedBiometryTypes` 过滤器排除它们。 若为 `useFallback` 真实, PIN/ pattern/ 密码字也可以使这个值成为真实 . |
| **`authenticationStrength`** | `[AuthenticationStrength](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-authenticationstrength)` | 现有认证方法(STRONG、WEAK或无)的强度 |
| **`biometryType`** | `[BiometryType](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometrytype)` | 设备上可用的初级生物测量类型. 在具有多种生物测量类型的Android设备上,这个返回了MULTIPLE. 仅用于显示目的 - 总是用于逻辑决定 . |
| **`deviceIsSecure`** | `boolean` | 设备是否有安全的锁屏(PIN,图案,或密码). 这与生物鉴别学入学无关. |
| **`strongBiometryIsAvailable`** | `boolean` | 强活体测量法(Face ID, touch ID,或认为强活体的装置上的指纹)是否具体可用,与弱活体测量法或装置资质分离. |
| **`errorCode`** | `[BiometricAuthError](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometricautherror)` | 错误代码来自 [生物计量法错误](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometricautherror) um. 惟有虚相相相现. 说明为何没有生物鉴别认证. |

#### 可用选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`useFallback`** | `boolean` | 密码或设备证书在没有生物鉴别记录或没有生物鉴别记录的情况下,应否考虑生物鉴别的可用性。 - 说吧 在iOS上,这影响到两个 `isAvailable()` 财务报告和审定财务报表 `verifyIdentity()`\- 在Android,这是荣耀的 `isAvailable()` 只有——本地支票计算 `fallbackAvailable = useFallback && deviceIsSecure` 并相应报告可用性。 这个 `verifyIdentity()` 流量由于生物Prompt API的限制而忽略了Android上的这个选项(DEVICE CREDENTIAL验证器和负按钮是相互排斥的); 使用 [`BiometricOptions.useFallback`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometricoptions) (iOS - only) 控制 认证- 对话框的倒置 . |  |  |
| **`preferMultipleBiometryType`** | `boolean` | 仅限Android. 报告 [`BiometryType.MULTIPLE`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometrytype) 每当指纹被录入时,设备也为面部或虹膜传感器作广告,即使第二种模式无法确认为录入。 你通常不需要这个 在Android 12上,在指纹旁边注册的一张脸通常被发现并报告为 [`BiometryType.MULTIPLE`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometrytype) 独自一人。 检测是最佳的,在Android 11及更年长的,对于稀有的"第3类"(Strong)面部传感器,或者在销售商所建造的,其生物鉴别标签名称仅为首选模式上,都是不可能的. 未检测设备报告 `BiometryType.FINGERPRINT`,因为大多数设备 广告面部传感器 用户从来没有注册。 设定为 `true` 如果你的UI宁愿过度报道 `MULTIPLE` 在这里. `verifyIdentity()` 不受影响,仍提供设备所支持的每个注册生物鉴别技术;这只改变了报告的类型。 最新值用于 `biometryChange` 事件. | `false` | 8.6.5 (单位:千美元) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 生物计量选项

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`reason`** | `string` |  |  |
| **`title`** | `string` |  |  |
| **`subtitle`** | `string` |  |  |
| **`description`** | `string` |  |  |
| **`negativeButtonText`** | `string` |  |  |
| **`useFallback`** | `boolean` | 只为iOS. 指定如果生物鉴别认证失败, 是否返回密码认证 。 在Android上,由于BiometricPrompt API的限制,这个参数被忽略了: DEVICE CREDENTIAL验证器和负按钮(cancel)是相互排斥的. |  |
| **`fallbackTitle`** | `string` | 只为iOS. 设置认证对话框中倒置按钮的文本 。 如果未指定此属性, 默认文本由系统设置 . |  |
| **`maxAttempts`** | `number` | 只为安卓 设定生物鉴别认证的最大尝试次数。 Android允许的上限为 5. | `1` |
| **`allowedBiometryTypes`** | `BiometryType[]` | 只为安卓 指定允许认证的生物计量类型。 如果没有具体说明,则允许所有注册的生物鉴别课程(强和弱)。 在Android上,面部解锁常被归类为弱生物特征——包括: `BiometryType.FACE_AUTHENTICATION` 或省略此选项以允许它。 使用 [`BiometryType.DEVICE_CREDENTIAL`](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-biometrytype) 对于PIN/pattern/password(取消按钮). |  |

#### 全权证书

| Prop | 类型 |
| --- | --- |
| **`username`** | `string` |
| **`password`** | `string` |

#### 获取证书选项

| Prop | 类型 |
| --- | --- |
| **`server`** | `string` |

#### 设置关键选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`username`** | `string` |  |  |  |
| **`password`** | `string` |  |  |  |
| **`server`** | `string` |  |  |  |
| **`accessControl`** | `[AccessControl](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-accesscontrol)` | 存储证书的访问控制级别 。 当设置到 BIOMETRY CURRENT SET 或 BIOMETRY ANY时,证书是硬件保护的,需要生物鉴别认证才能访问. 在 iOS 上,这将 SecAccess Control 添加到密钥链项中 。 在Android上,这创造了一个有生物特征保护的Keystore密钥,并且需要BiometricPrompt认证来存储和检索证书. | `AccessControl.NONE` | 8.4.0 (单位:百万美元) |
| **`authValidityDuration`** | `number` | 只为安卓 在iOS和网络上被忽略. 只有有意义的一起 `accessControl` 设置为 BIOMETRY CURRENT SET或BIOMETRY ANY。 成功生物鉴别认证的秒数仍然适用于Keystore密钥。 何时 `0` 或省略(默认), Keystore 密钥需要每个操作的新认证 – 每个 `getSecureCredentials()` 调用显示 `BiometricPrompt` 密码学上与该特定内容相连,通过 `CryptoObject`。这是最强的模式:它保证任何代码路径都无法在没有生物特征活检查的情况下使用密钥。 当设定为大于 `0`一个成功的生物鉴别认证 授权Keystore键在多秒钟内使用。 后续 `getSecureCredentials()` 窗口内的呼叫成功而不显示提示 。 这交易安全方便:任何能够通达解密呼叫的应用中代码——而不仅仅是触发了快取的代码路径——都可以默读其余窗口的证书. | `0` | 8.5.0 (中文(简体) ) |
| **`title`** | `string` | 保护证书时显示的生物鉴别提示的标题 。 只为安卓. | `"Protect Credentials"` | 8.4.14 联合国 |
| **`negativeButtonText`** | `string` | 生物鉴别提示中负/取消按钮的文字。 只为安卓. | `"Cancel"` | 8.4.14 联合国 |
| **`maxAttempts`** | `number` | 设定生物鉴别认证的最大尝试次数。 Android允许的最大为5. 只为安卓. | `1` |  |

#### 删除证书选项

| Prop | 类型 |
| --- | --- |
| **`server`** | `string` |

#### 获取证书选项

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`server`** | `string` |  |  |
| **`reason`** | `string` | 解释文本作为触摸ID提示的字幕显示. 脸部标识没有显示 。 只为iOS. |  |
| **`title`** | `string` | 生物识别提示的标题 只为安卓. |  |
| **`subtitle`** | `string` | 生物识别提示的字幕 只为安卓. |  |
| **`description`** | `string` | 生物识别提示说明 只为安卓. |  |
| **`negativeButtonText`** | `string` | 负/取消按钮的文本 。 只为安卓. |  |
| **`maxAttempts`** | `number` | 设定生物鉴别认证的最大尝试次数。 Android允许的最大为5. 只为安卓. | `1` |

#### 证书保存结果

| Prop | 类型 |
| --- | --- |
| **`isSaved`** | `boolean` |

#### 证书保存选项

| Prop | 类型 |
| --- | --- |
| **`server`** | `string` |

#### 设置数据选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`key`** | `string` | 存储值的独特标识符 。 使用稳定的应用特定命名空间(例如. `pin`, (中文(简体) ), `session.token`) (中文(简体) ). |  |  |
| **`value`** | `string` | 任意弦有效载荷. 以 `JSON.stringify()` 在存储之前。 平台限制适用:Android Keystore后置加密在~8 KB下最能与有效载荷相配合;iOS Keychain实用限制较高,但非常大的值被劝阻. |  |  |
| **`accessControl`** | `[AccessControl](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-accesscontrol)` | 存储值的访问控制级别 。 当设定为 BIOMETRY CURRENT SET 或 BIOMETRY ANY时,该值为硬件保护并需要生物鉴别认证才能通过 `getSecureData()`。 。 。 . | `AccessControl.NONE` | 8.6.0 (简体中文) |
| **`authValidityDuration`** | `number` | 只为安卓 在iOS和网络上被忽略. 只有有意义的一起 `accessControl` 设置为 BIOMETRY CURRENT SET或BIOMETRY ANY. | `0` | 8.6.0 (简体中文) |
| **`title`** | `string` | 保护数据时显示的生物鉴别提示的标题 。 只为安卓. | `"Protect Data"` | 8.6.0 (简体中文) |
| **`negativeButtonText`** | `string` | 生物鉴别提示中负/取消按钮的文字。 只为安卓. | `"Cancel"` | 8.6.0 (简体中文) |
| **`maxAttempts`** | `number` | 设定生物鉴别认证的最大尝试次数。 Android允许的最大为5. 只为安卓. | `1` |  |

#### 存储数据

| Prop | 类型 |
| --- | --- |
| **`value`** | `string` |

#### 获取数据选项

| Prop | 类型 |
| --- | --- |
| **`key`** | `string` |

#### 获取安全数据选项

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`key`** | `string` |  |  |
| **`reason`** | `string` | 解释文本作为触摸ID提示的字幕显示. 脸部标识没有显示 。 只为iOS. |  |
| **`title`** | `string` | 生物识别提示的标题 只为安卓. |  |
| **`subtitle`** | `string` | 生物识别提示的字幕 只为安卓. |  |
| **`description`** | `string` | 生物识别提示说明 只为安卓. |  |
| **`negativeButtonText`** | `string` | 负/取消按钮的文本 。 只为安卓. |  |
| **`fallbackTitle`** | `string` | 设置认证对话框中倒置按钮的文本 。 如果未指定此属性, 默认文本由系统设置 。 设置为空字符串来隐藏按钮 。 只为iOS. |  |
| **`maxAttempts`** | `number` | 设定生物鉴别认证的最大尝试次数。 Android允许的最大为5. 只为安卓. | `1` |

#### 删除数据选项

| Prop | 类型 |
| --- | --- |
| **`key`** | `string` |

#### IsData 保存结果

| Prop | 类型 |
| --- | --- |
| **`isSaved`** | `boolean` |

#### IsData 保存选项

| Prop | 类型 |
| --- | --- |
| **`key`** | `string` |

### 类型异名

#### 生物计量变异听器

生物计量变化的回调类型

`(result: [AvailableResult](https://npmcn.com/package/%40capgo/capacitor-native-biometric/#readme-availableresult)): void`

### 数字

#### 认证 强度

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`NONE`** | `0` | 没有可用的认证, 即使可以使用 PIN, 但使用 Fallback = false |
| **`STRONG`** | `1` | 强认证:iOS上的面相ID,认为指纹强的装置上的指纹(Android). 注:PIN/pattern/Password从未被视为STRONG,即使使用Fallback=真实. |
| **`WEAK`** | `2` | 弱认证:在Android设备上,如果使用Fallback = true(PIN总是WEAK,从不STRONG),则考虑面部弱点的Face认证,或者PIN/pattern/password. |

#### 生物测量主题

| 成员 | 数值 |
| --- | --- |
| **`NONE`** | `0` |
| **`TOUCH_ID`** | `1` |
| **`FACE_ID`** | `2` |
| **`FINGERPRINT`** | `3` |
| **`FACE_AUTHENTICATION`** | `4` |
| **`IRIS_AUTHENTICATION`** | `5` |
| **`MULTIPLE`** | `6` |
| **`DEVICE_CREDENTIAL`** | `7` |

#### 生物计量法错误

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`UNKNOWN_ERROR`** | `0` | 发生未知错误 |  |
| **`BIOMETRICS_UNAVAILABLE`** | `1` | 生物计量没有可用(没有硬件或硬件出错) 平台:Android, iOS |  |
| **`USER_LOCKOUT`** | `2` | 由于多次尝试失败,用户被锁定 平台:Android, iOS |  |
| **`BIOMETRICS_NOT_ENROLLED`** | `3` | 设备平台:Android、iOS没有生物鉴别技术 |  |
| **`USER_TEMPORARY_LOCKOUT`** | `4` | 用户暂时被锁出 (Android: 30 second lockout) 平台:Android 官方网站 |  |

## 常见问题

### @capgo/capacitor-native-biometric 是什么？

此插件为 Android 和 iOS 提供了本地生物鉴别类的访问权限

### 如何安装 @capgo/capacitor-native-biometric？

在项目目录运行 npm install @capgo/capacitor-native-biometric，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-native-biometric 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-native-biometric 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-native-biometric 可以商用吗？

@capgo/capacitor-native-biometric 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-native-biometric 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-native-biometric 在 2026/10/09 – 2026/11/07 这 30 天内被下载 972,225 次，日均约 32,408 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-native-biometric 还在维护吗？

最新版本 8\.9\.1 发布于 2026/10/21（19 天前）；至今共发布 80 个版本，其中过去 12 个月发布了 53 个；首次发布于 2023/05/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。