# Fido2Login SDK API 文档
## 概述
`Fido2UIManager.renderLogin()` 是一个用于渲染登录组件的API，支持：
- Fido2/Passkey 自动登录
- 密码登录回退
- 密码重试次数限制
- 完全的回调驱动（SDK不跳转页面）
## 使用方法
### 1. 引入依赖
```html
```
### 2. 添加容器
```html
```
### 3. 初始化登录组件
```javascript
const loginManager = Fido2UIManager.renderLogin({
container: '#login-container',
features: {
autoAuth: true,
enablePasswordLogin: true,
maxPasswordAttempts: 3,
showRemainingAttempts: true
},
callbacks: {
onFido2Success: (userId, session) => {
// 处理Fido2登录成功
},
onFido2Error: (error) => {
// 处理Fido2登录失败
},
onPasswordLogin: (userId, password) => {
// 返回 Promise
},
onPasswordExhausted: (userId, attempts, maxAttempts) => {
// 密码重试次数耗尽
},
onLoginClosed: () => {
// UI被关闭
}
}
});
```
## 配置参数
### container
- **类型**: `string | Element`
- **必填**: 是
- **说明**: 模态框容器元素
### features
- **类型**: `Object`
- **默认值**: 见下方
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `autoAuth` | boolean | true | 有注册设备时自动Fido2登录 |
| `enablePasswordLogin` | boolean | true | 是否启用密码登录功能 |
| `autoShowPassword` | boolean | false | Fido2失败后是否自动显示密码框 |
| `maxPasswordAttempts` | number | 3 | 密码最大重试次数 |
| `showRemainingAttempts` | boolean | true | 是否显示剩余尝试次数 |
### theme
- **类型**: `Object`
- **说明**: 复用 `renderDeviceManager` 的theme配置
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `logo` | string | null | Logo图片URL |
| `primaryColor` | string | '#696cff' | 主色调 |
| `backgroundColor` | string | '#ffffff' | 背景色 |
| `textColor` | string | '#333333' | 文字颜色 |
| `borderRadius` | string | '8px' | 边框圆角 |
### language
- **类型**: `string`
- **默认值**: `'zh-CN'`
- **说明**: 支持9种语言
### callbacks
#### onFido2Success(userId, session)
- **触发时机**: Fido2登录认证成功
- **参数**:
- `userId`: string - 用户ID
- `session`: object - 会话信息
- **注意**: SDK不跳转页面，由调用端处理跳转
#### onFido2Error(error)
- **触发时机**: Fido2登录失败或取消
- **参数**: `error` 对象
- `code`: string - 错误码
- `message`: string - 错误信息
- `originalError`: object - 原始错误
**error.code 值**:
| code | 说明 |
|------|------|
| `CANCELED` | 用户取消认证 |
| `AUTH_FAILED` | 认证失败 |
| `NO_REGISTRATION` | 无注册设备且未启用密码登录 |
| `NOT_SUPPORTED` | 浏览器不支持WebAuthn |
#### onPasswordLogin(userId, password)
- **触发时机**: 用户点击密码登录按钮
- **参数**:
- `userId`: string - 用户ID
- `password`: string - 密码
- **返回值**: `Promise`
- `true`: 登录成功
- `false`: 登录失败
#### onPasswordExhausted(userId, attempts, maxAttempts)
- **触发时机**: 密码重试次数耗尽
- **参数**:
- `userId`: string - 用户ID
- `attempts`: number - 已尝试次数
- `maxAttempts`: number - 最大允许次数
- **注意**: UI已自动关闭
#### onLoginClosed()
- **触发时机**: 用户关闭模态框（点击×或调用hide()）
## 实例方法
### show()
显示登录模态框
### hide()
隐藏登录模态框，触发 `onLoginClosed` 回调
### destroy()
销毁登录组件实例，不触发任何回调
### setMode(mode)
切换登录模式
- `mode`: `'fido2'` 或 `'password'`
### getUserId()
获取当前输入的用户ID
### getState()
获取当前状态
- 返回值: `'loading'` | `'fido2'` | `'password'` | `'closed'`
### getMode()
获取当前模式
- 返回值: `'fido2'` | `'password'`
### getAttemptCount()
获取当前密码尝试次数
### getRemainingAttempts()
获取剩余尝试次数
### resetPasswordAttempts()
重置密码尝试计数器
## 国际化支持
默认支持9种语言：
- `en-US` (英语)
- `zh-CN` (简体中文)
- `ja` (日语)
- `es` (西班牙语)
- `de` (德语)
- `fr` (法语)
- `pt` (葡萄牙语)
- `ko` (韩语)
- `ru` (俄语)
- `it` (意大利语)
可通过 `customI18n` 配置自定义文本：
```javascript
Fido2UIManager.renderLogin({
customI18n: {
'title_login': {
'en-US': 'Custom Login',
'zh-CN': '自定义登录'
}
}
});
```
## 完整示例
```html
Login Example
```
## 版本信息
- **FIDO2 UI SDK**: v1.0.0+
- **文件**: `files/fido2-ui-sdk.js`
- **新增功能**: `Fido2UIManager.renderLogin()`