# 生物识别

> 用 Biometry.isAvailable() 和 authenticate(...) 实现可移植的生物识别认证。

Source: https://crossfly.dev/zh/docs/data-and-services/device-biometry — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 生物识别

用 **`Biometry`** 以可移植的方式进行指纹/人脸认证。结果通过回调**异步**到达 ——
请用 `onUI(...)` 分派到 UI。

## 用法
```java
if (!Biometry.isAvailable()) {
   loginPorSenha();               // 无生物识别时的回退
   return;
}
Biometry.authenticate(
   "Confirme sua identidade",     // reason（展示给用户）
   "Cancelar",                    // 取消按钮的文本
   false,                         // onlyBiometric: false = 允许系统 PIN 作为回退
   (resultado, mensagem) -> Component.onUI(() -> {
      switch (resultado) {
         case SUCCESS:   abrirAreaSegura(); break;
         case FAILURE:   Hint.show("Não reconhecido", 2000); break;
         case CANCELLED: /* 用户放弃了 */ break;
         case ERROR:     Hint.show("Erro: " + mensagem, 2000); loginPorSenha(); break;
      }
   })
);
```

## API
| 成员 | 签名 |
|---|---|
| `Biometry.isAvailable()` | `static boolean` —— 是否存在已注册的硬件/生物识别？ |
| `Biometry.authenticate(...)` | `static void (String reason, String cancel, boolean onlyBiometric, Callback)` |
| `Callback.onResult(...)` | `(AuthResult result, String message)` |
| `AuthResult` | `SUCCESS` · `FAILURE` · `CANCELLED` · `ERROR` |

- **`onlyBiometric = true`** 要求生物识别（不会回退到系统 PIN/密码）；`false` 允许
  操作系统的回退方式。

## 安全性
- **生物识别数据绝不会离开设备** —— 应用只收到 `SUCCESS`/`FAILURE` 等结果，
  永远拿不到指纹/人脸本身。
- **始终提供应用级的回退方式**（登录/密码），用于 `ERROR` 以及
  `isAvailable()` 为 `false` 的情况。

## 常见错误
- 只处理 `SUCCESS` 而忽略 `CANCELLED`/`ERROR`（用户被卡住）。
- 在回调中直接操作 UI —— 它**不在**绘制线程上；请用 `onUI(...)`。
- 在没有生物识别时没有备选路径。

## 另见
- [声音与设备工具](/docs/data-and-services/device-sound-and-misc) · [各平台权限](/docs/platforms)