642 lines
13 KiB
Markdown
642 lines
13 KiB
Markdown
# FIDO2 UI SDK - API 文档
|
||
|
||
## 目录
|
||
|
||
- [全局对象](#全局对象)
|
||
- [配置选项](#配置选项)
|
||
- [API 方法](#api-方法)
|
||
- [事件系统](#事件系统)
|
||
- [国际化](#国际化)
|
||
- [主题定制](#主题定制)
|
||
|
||
---
|
||
|
||
## 全局对象
|
||
|
||
### Fido2UIManager
|
||
|
||
全局 FIDO2 UI 管理对象。
|
||
|
||
```javascript
|
||
window.Fido2UIManager
|
||
```
|
||
|
||
---
|
||
|
||
## 配置选项
|
||
|
||
### config
|
||
|
||
配置对象，用于初始化设备管理器。
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| serverUrl | String | 'https://fido2.amipro.me' | FIDO2 服务器地址 |
|
||
| mode | String | 'modal' | 渲染模式：'modal' \| 'standalone' |
|
||
| container | String \| Element | null | 容器选择器或 DOM 元素（modal 模式必需） |
|
||
| theme | Object | 见下方 | 主题配置 |
|
||
| language | String | 'zh-CN' | 语言：'en-US' \| 'zh-CN' \| 'ja' |
|
||
| customI18n | Object | {} | 自定义翻译 |
|
||
| features | Object | 见下方 | 功能开关 |
|
||
| callbacks | Object | {} | 事件回调 |
|
||
| rpId | String \| null | null | Relying Party ID |
|
||
| autoRefresh | Boolean | true | 是否自动刷新设备列表 |
|
||
| refreshInterval | Number | 5000 | 刷新间隔（毫秒） |
|
||
|
||
### config.theme
|
||
|
||
主题配置对象。
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| logo | String \| null | null | Logo 图片 URL |
|
||
| primaryColor | String | '#696cff' | 主色调（十六进制颜色值） |
|
||
| backgroundColor | String | '#ffffff' | 背景色 |
|
||
| textColor | String | '#333333' | 文字颜色 |
|
||
| borderRadius | String | '8px' | 圆角大小 |
|
||
|
||
### config.features
|
||
|
||
功能开关对象。
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| showAddButton | Boolean | true | 是否显示添加按钮 |
|
||
| showDeleteButton | Boolean | true | 是否显示删除按钮 |
|
||
| showUserInfo | Boolean | true | 是否显示用户信息 |
|
||
| showSessionStatus | Boolean | true | 是否显示会话状态 |
|
||
|
||
### config.callbacks
|
||
|
||
事件回调对象。
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| onInit | Function | null | 初始化完成回调 |
|
||
| onDeviceAdded | Function | null | 设备添加成功回调 |
|
||
| onDeviceDeleted | Function | null | 设备删除成功回调 |
|
||
| onDeviceListLoaded | Function | null | 设备列表加载完成回调 |
|
||
| onError | Function | null | 错误发生回调 |
|
||
| onClose | Function | null | 窗口关闭回调（仅 modal 模式） |
|
||
|
||
---
|
||
|
||
## API 方法
|
||
|
||
### renderDeviceManager(config)
|
||
|
||
渲染设备管理器。
|
||
|
||
**语法：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager(config)
|
||
```
|
||
|
||
**参数：**
|
||
|
||
- `config` (Object) - 配置对象，详见[配置选项](#配置选项)
|
||
|
||
**返回值：**
|
||
|
||
- (Object) - 设备管理器实例
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
const manager = Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal',
|
||
serverUrl: 'https://fido2.amipro.me'
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### close()
|
||
|
||
关闭模态框（仅 modal 模式有效）。
|
||
|
||
**语法：**
|
||
|
||
```javascript
|
||
Fido2UIManager.close()
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.close();
|
||
```
|
||
|
||
---
|
||
|
||
### refresh()
|
||
|
||
刷新设备列表和会话状态。
|
||
|
||
**语法：**
|
||
|
||
```javascript
|
||
Fido2UIManager.refresh()
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.refresh();
|
||
```
|
||
|
||
---
|
||
|
||
### destroy()
|
||
|
||
销毁设备管理器实例，清理资源。
|
||
|
||
**语法：**
|
||
|
||
```javascript
|
||
Fido2UIManager.destroy()
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.destroy();
|
||
```
|
||
|
||
---
|
||
|
||
## 事件系统
|
||
|
||
### 事件列表
|
||
|
||
| 事件名称 | 触发时机 | 回调参数 |
|
||
|---------|---------|---------|
|
||
| `init` | 初始化完成 | (manager: Object) |
|
||
| `deviceAdded` | 设备添加成功 | (device: Object) |
|
||
| `deviceDeleted` | 设备删除成功 | (deviceId: String) |
|
||
| `deviceListLoaded` | 设备列表加载完成 | (devices: Array) |
|
||
| `sessionStatusChanged` | 会话状态改变 | (isValid: Boolean) |
|
||
| `error` | 发生错误 | (error: Error) |
|
||
| `close` | 窗口关闭 | 无 |
|
||
|
||
### 事件参数详解
|
||
|
||
#### init
|
||
|
||
初始化完成时触发。
|
||
|
||
**参数：**
|
||
|
||
- `manager` (Object) - 设备管理器实例
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
callbacks: {
|
||
onInit: function(manager) {
|
||
console.log('设备管理器已初始化', manager);
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
#### deviceAdded
|
||
|
||
设备添加成功时触发。
|
||
|
||
**参数：**
|
||
|
||
- `device` (Object) - 添加的设备信息
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
callbacks: {
|
||
onDeviceAdded: function(device) {
|
||
console.log('设备添加成功', device);
|
||
// 刷新用户界面
|
||
refreshUserInterface();
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
#### deviceDeleted
|
||
|
||
设备删除成功时触发。
|
||
|
||
**参数：**
|
||
|
||
- `deviceId` (String) - 被删除设备的 ID
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
callbacks: {
|
||
onDeviceDeleted: function(deviceId) {
|
||
console.log('设备删除成功', deviceId);
|
||
// 显示成功提示
|
||
showNotification('设备删除成功');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
#### deviceListLoaded
|
||
|
||
设备列表加载完成时触发。
|
||
|
||
**参数：**
|
||
|
||
- `devices` (Array) - 设备列表
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
callbacks: {
|
||
onDeviceListLoaded: function(devices) {
|
||
console.log('设备列表加载完成，共', devices.length, '个设备');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
#### sessionStatusChanged
|
||
|
||
会话状态改变时触发。
|
||
|
||
**参数：**
|
||
|
||
- `isValid` (Boolean) - 会话是否有效
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
callbacks: {
|
||
onSessionStatusChanged: function(isValid) {
|
||
if (isValid) {
|
||
console.log('会话有效');
|
||
} else {
|
||
console.log('会话无效，请重新登录');
|
||
}
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
#### error
|
||
|
||
发生错误时触发。
|
||
|
||
**参数：**
|
||
|
||
- `error` (Error) - 错误对象
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
callbacks: {
|
||
onError: function(error) {
|
||
console.error('发生错误:', error.message);
|
||
// 显示错误提示
|
||
showErrorNotification(error.message);
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
#### close
|
||
|
||
模态框关闭时触发（仅 modal 模式）。
|
||
|
||
**参数：**
|
||
|
||
- 无
|
||
|
||
**示例：**
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
callbacks: {
|
||
onClose: function() {
|
||
console.log('模态框已关闭');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 国际化
|
||
|
||
### 支持的语言
|
||
|
||
- `en-US` - 英文
|
||
- `zh-CN` - 简体中文
|
||
- `ja` - 日文
|
||
|
||
### 设置语言
|
||
|
||
通过 `language` 参数设置语言：
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
language: 'zh-CN'
|
||
});
|
||
```
|
||
|
||
### 默认翻译键
|
||
|
||
| 键 | 英文 | 中文 | 日文 |
|
||
|----|------|------|------|
|
||
| `my_devices` | My devices | 我的设备 | マイデバイス |
|
||
| `btn_add` | Add device | 添加设备 | デバイスを追加 |
|
||
| `title_device` | Device | 设备 | デバイス |
|
||
| `title_time` | Registered time | 添加时间 | 登録時間 |
|
||
| `title_act` | Actions | 操作 | 操作 |
|
||
| `title_del` | Delete | 删除 | 削除 |
|
||
| `title_logout` | Log out | 登出 | ログアウト |
|
||
| `title_empty_list` | No devices, please add. | 无设备，请添加。 | デバイスがなし、追加してください。 |
|
||
| `msg_register_ok` | Device registered successfully | 添加设备成功 | デバイス登録完了 |
|
||
| `msg_deldev_ok` | Device deleted successfully | 设备删除成功 | デバイスを削除しました |
|
||
| `msg_confirm_deldev` | Do you want to delete this device? | 确认删除此设备吗？ | デバイスを削除しますか？ |
|
||
| `msg_session_status_ok` | FIDO2 session is valid | FIDO2会话正常 | FIDO2セッションは正常です |
|
||
| `msg_session_status_fail` | FIDO2 session is invalid | FIDO2会话无效 | FIDO2セッションは無効です |
|
||
| `btn_close` | Close | 关闭 | 閉じる |
|
||
| `title_welcome` | Welcome | 欢迎 | ようこそ |
|
||
|
||
### 自定义翻译
|
||
|
||
通过 `customI18n` 参数自定义翻译：
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
language: 'zh-CN',
|
||
customI18n: {
|
||
'my_devices': {
|
||
'zh-CN': '我的 FIDO2 设备'
|
||
},
|
||
'btn_add': {
|
||
'zh-CN': '添加新设备'
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 主题定制
|
||
|
||
### 主题配置参数
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| logo | String \| null | null | Logo 图片 URL |
|
||
| primaryColor | String | '#696cff' | 主色调 |
|
||
| backgroundColor | String | '#ffffff' | 背景色 |
|
||
| textColor | String | '#333333' | 文字颜色 |
|
||
| borderRadius | String | '8px' | 圆角大小 |
|
||
|
||
### 基础主题定制
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
theme: {
|
||
logo: '/assets/my-logo.png',
|
||
primaryColor: '#ce59d9',
|
||
backgroundColor: '#ffffff'
|
||
}
|
||
});
|
||
```
|
||
|
||
### 完整主题定制
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
theme: {
|
||
logo: '/assets/my-logo.png',
|
||
primaryColor: '#0066cc',
|
||
backgroundColor: '#f8f9fa',
|
||
textColor: '#333333',
|
||
borderRadius: '12px'
|
||
}
|
||
});
|
||
```
|
||
|
||
### 深色主题示例
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
theme: {
|
||
logo: '/assets/logo.png',
|
||
primaryColor: '#4a9eff',
|
||
backgroundColor: '#1a1a2e',
|
||
textColor: '#ffffff',
|
||
borderRadius: '8px'
|
||
}
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 设备管理器实例方法
|
||
|
||
如果需要访问设备管理器实例，可以保存 `renderDeviceManager` 的返回值：
|
||
|
||
```javascript
|
||
const manager = Fido2UIManager.renderDeviceManager(config);
|
||
```
|
||
|
||
### 实例方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `close()` | 关闭模态框（仅 modal 模式） |
|
||
| `refresh()` | 刷新设备列表和会话状态 |
|
||
| `destroy()` | 销毁设备管理器实例 |
|
||
|
||
### 示例
|
||
|
||
```javascript
|
||
const manager = Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal'
|
||
});
|
||
|
||
// 手动刷新
|
||
manager.refresh();
|
||
|
||
// 关闭模态框
|
||
manager.close();
|
||
|
||
// 销毁实例
|
||
manager.destroy();
|
||
```
|
||
|
||
---
|
||
|
||
## CSS 类名
|
||
|
||
SDK 使用以下 CSS 类名，可以通过 CSS 覆盖样式：
|
||
|
||
| 类名 | 说明 |
|
||
|------|------|
|
||
| `.fido2-sdk-modal` | 模态框容器 |
|
||
| `.fido2-sdk-card` | 卡片容器 |
|
||
| `.fido2-sdk-header` | 头部区域 |
|
||
| `.fido2-sdk-container` | 内容容器 |
|
||
| `.fido2-sdk-body` | 主体内容 |
|
||
| `.fido2-sdk-text` | 文字样式 |
|
||
| `.fido2-sdk-table` | 表格样式 |
|
||
| `.fido2-sdk-btn` | 按钮样式 |
|
||
| `.fido2-sdk-btn-primary` | 主要按钮样式 |
|
||
| `.fido2-sdk-status-badge` | 状态徽章样式 |
|
||
| `.fido2-sdk-user-info` | 用户信息样式 |
|
||
| `.fido2-sdk-standalone` | 独立页面样式 |
|
||
| `.fido2-sdk-logo` | Logo 样式 |
|
||
|
||
### 自定义 CSS 示例
|
||
|
||
```css
|
||
/* 自定义按钮样式 */
|
||
.fido2-sdk-btn-primary {
|
||
background-color: #ff6b6b !important;
|
||
font-weight: bold;
|
||
}
|
||
|
||
/* 自定义表格样式 */
|
||
.fido2-sdk-table th {
|
||
font-size: 14px;
|
||
color: #666;
|
||
}
|
||
|
||
/* 自定义模态框样式 */
|
||
.fido2-sdk-modal .modal-content {
|
||
box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 类型定义
|
||
|
||
### ConfigObject
|
||
|
||
```typescript
|
||
interface ConfigObject {
|
||
serverUrl?: string;
|
||
mode?: 'modal' | 'standalone';
|
||
container?: string | Element;
|
||
theme?: ThemeObject;
|
||
language?: string;
|
||
customI18n?: Record<string, Record<string, string>>;
|
||
features?: FeaturesObject;
|
||
callbacks?: CallbacksObject;
|
||
rpId?: string | null;
|
||
autoRefresh?: boolean;
|
||
refreshInterval?: number;
|
||
}
|
||
```
|
||
|
||
### ThemeObject
|
||
|
||
```typescript
|
||
interface ThemeObject {
|
||
logo?: string | null;
|
||
primaryColor?: string;
|
||
backgroundColor?: string;
|
||
textColor?: string;
|
||
borderRadius?: string;
|
||
}
|
||
```
|
||
|
||
### FeaturesObject
|
||
|
||
```typescript
|
||
interface FeaturesObject {
|
||
showAddButton?: boolean;
|
||
showDeleteButton?: boolean;
|
||
showUserInfo?: boolean;
|
||
showSessionStatus?: boolean;
|
||
}
|
||
```
|
||
|
||
### CallbacksObject
|
||
|
||
```typescript
|
||
interface CallbacksObject {
|
||
onInit?: (manager: any) => void;
|
||
onDeviceAdded?: (device: any) => void;
|
||
onDeviceDeleted?: (deviceId: string) => void;
|
||
onDeviceListLoaded?: (devices: any[]) => void;
|
||
onError?: (error: Error) => void;
|
||
onClose?: () => void;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何在页面加载后自动打开设备管理器？
|
||
|
||
```javascript
|
||
window.onload = function() {
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal'
|
||
});
|
||
};
|
||
```
|
||
|
||
### Q: 如何在用户点击按钮后才打开设备管理器？
|
||
|
||
```html
|
||
<button onclick="openDeviceManager()">管理设备</button>
|
||
<div id="device-container"></div>
|
||
|
||
<script>
|
||
function openDeviceManager() {
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal'
|
||
});
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### Q: 如何禁用自动刷新？
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
autoRefresh: false
|
||
});
|
||
```
|
||
|
||
### Q: 如何更改刷新间隔？
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
autoRefresh: true,
|
||
refreshInterval: 10000 // 10秒
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
- **v1.0.0** - 初始版本
|
||
- 支持模态框和独立页面两种模式
|
||
- 支持主题定制
|
||
- 支持国际化
|
||
- 完整的事件系统
|