323 lines
7.6 KiB
Markdown
323 lines
7.6 KiB
Markdown
# FIDO2 UI SDK
|
||
|
||
一个简单易用的 FIDO2 设备管理 UI 库，支持快速集成 FIDO2 认证设备管理功能。
|
||
|
||
## 特性
|
||
|
||
- 🚀 **快速集成** - 一行代码即可集成设备管理功能
|
||
- 🎨 **主题定制** - 支持自定义 Logo、颜色、背景等
|
||
- 🌐 **国际化** - 内置中文、英文、日文支持
|
||
- 📱 **响应式** - 支持桌面端和移动端
|
||
- 🎭 **双模式** - 支持弹出窗口和独立页面两种模式
|
||
- 🎯 **事件回调** - 完整的事件系统，灵活处理各种操作
|
||
- ♿ **向后兼容** - 完全兼容现有的对接方式
|
||
|
||
## 快速开始
|
||
|
||
### 1. 引入依赖
|
||
|
||
```html
|
||
<!-- 必需的依赖 -->
|
||
<script src="files/jquery.js"></script>
|
||
<script src="files/bootstrap.js"></script>
|
||
<script src="files/dfido2-lib.js"></script>
|
||
|
||
<!-- 引入 SDK -->
|
||
<script src="files/fido2-ui-sdk.js"></script>
|
||
<link rel="stylesheet" href="files/fido2-ui-sdk.css">
|
||
```
|
||
|
||
### 2. 添加容器（仅模态框模式需要）
|
||
|
||
```html
|
||
<div id="device-container"></div>
|
||
```
|
||
|
||
### 3. 调用 SDK
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal',
|
||
serverUrl: 'https://fido2.amipro.me'
|
||
});
|
||
```
|
||
|
||
## 使用模式
|
||
|
||
### 模式 1: 弹出窗口 (推荐)
|
||
|
||
弹出窗口模式在当前页面上显示模态框，用户操作完成后自动关闭。
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal',
|
||
serverUrl: 'https://fido2.amipro.me'
|
||
});
|
||
```
|
||
|
||
**适用场景：**
|
||
- 用户在设置页面需要管理设备
|
||
- 不希望离开当前页面
|
||
- 快速查看和管理设备
|
||
|
||
### 模式 2: 独立页面
|
||
|
||
独立页面模式会渲染完整的设备管理页面，适合作为独立的页面功能。
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
mode: 'standalone',
|
||
serverUrl: 'https://fido2.amipro.me'
|
||
});
|
||
```
|
||
|
||
**适用场景：**
|
||
- 需要独立的设备管理页面
|
||
- 通过链接直接访问设备管理
|
||
- 需要更多屏幕空间显示设备信息
|
||
|
||
## 配置选项
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
// === 核心配置 ===
|
||
serverUrl: 'https://fido2.amipro.me', // FIDO2 服务器地址
|
||
mode: 'modal', // 'modal' | 'standalone'
|
||
|
||
// === 容器配置 (仅 modal 模式需要) ===
|
||
container: '#device-container', // 容器选择器或 DOM 元素
|
||
|
||
// === 主题定制 ===
|
||
theme: {
|
||
logo: 'path/to/logo.png', // Logo URL
|
||
primaryColor: '#ce59d9', // 主色调
|
||
backgroundColor: '#ffffff', // 背景色
|
||
textColor: '#333333', // 文字颜色
|
||
borderRadius: '8px', // 圆角
|
||
},
|
||
|
||
// === 国际化 ===
|
||
language: 'zh-CN', // 'en-US' | 'zh-CN' | 'ja'
|
||
customI18n: { // 自定义翻译
|
||
'my_devices': { 'zh-CN': '我的设备' },
|
||
// ...
|
||
},
|
||
|
||
// === 功能开关 ===
|
||
features: {
|
||
showAddButton: true,
|
||
showDeleteButton: true,
|
||
showUserInfo: true,
|
||
showSessionStatus: true,
|
||
},
|
||
|
||
// === 事件回调 ===
|
||
callbacks: {
|
||
onInit: () => {}, // 初始化完成
|
||
onDeviceAdded: (device) => {}, // 设备添加成功
|
||
onDeviceDeleted: (deviceId) => {}, // 设备删除成功
|
||
onDeviceListLoaded: (devices) => {}, // 设备列表加载完成
|
||
onError: (error) => {}, // 错误发生
|
||
onClose: () => {}, // 窗口关闭 (仅 modal 模式)
|
||
},
|
||
|
||
// === 其他 ===
|
||
rpId: null, // Relying Party ID
|
||
autoRefresh: true, // 自动刷新设备列表
|
||
refreshInterval: 5000, // 刷新间隔(ms)
|
||
});
|
||
```
|
||
|
||
## 完整示例
|
||
|
||
### 示例 1: 基础集成
|
||
|
||
```html
|
||
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<script src="files/jquery.js"></script>
|
||
<script src="files/bootstrap.js"></script>
|
||
<script src="files/dfido2-lib.js"></script>
|
||
<script src="files/fido2-ui-sdk.js"></script>
|
||
<link rel="stylesheet" href="files/fido2-ui-sdk.css">
|
||
</head>
|
||
<body>
|
||
<button onclick="openDeviceManager()">管理设备</button>
|
||
<div id="device-container"></div>
|
||
|
||
<script>
|
||
function openDeviceManager() {
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal',
|
||
serverUrl: 'https://fido2.amipro.me'
|
||
});
|
||
}
|
||
</script>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
### 示例 2: 带主题定制
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal',
|
||
serverUrl: 'https://fido2.amipro.me',
|
||
theme: {
|
||
logo: '/assets/my-logo.png',
|
||
primaryColor: '#0066cc',
|
||
backgroundColor: '#f8f9fa',
|
||
textColor: '#333333',
|
||
borderRadius: '12px'
|
||
},
|
||
language: 'zh-CN'
|
||
});
|
||
```
|
||
|
||
### 示例 3: 带事件回调
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal',
|
||
serverUrl: 'https://fido2.amipro.me',
|
||
callbacks: {
|
||
onInit: function(manager) {
|
||
console.log('设备管理器初始化完成');
|
||
},
|
||
onDeviceAdded: function(device) {
|
||
console.log('设备添加成功:', device);
|
||
// 刷新用户界面或其他逻辑
|
||
},
|
||
onDeviceDeleted: function(deviceId) {
|
||
console.log('设备删除成功:', deviceId);
|
||
},
|
||
onDeviceListLoaded: function(devices) {
|
||
console.log('设备列表加载完成:', devices.length, '个设备');
|
||
},
|
||
onError: function(error) {
|
||
console.error('发生错误:', error);
|
||
},
|
||
onClose: function() {
|
||
console.log('窗口关闭');
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
### 示例 4: 自定义翻译
|
||
|
||
```javascript
|
||
Fido2UIManager.renderDeviceManager({
|
||
container: '#device-container',
|
||
mode: 'modal',
|
||
serverUrl: 'https://fido2.amipro.me',
|
||
language: 'zh-CN',
|
||
customI18n: {
|
||
'my_devices': {
|
||
'zh-CN': '我的 FIDO2 设备'
|
||
},
|
||
'btn_add': {
|
||
'zh-CN': '添加新设备'
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
## API 方法
|
||
|
||
### renderDeviceManager(config)
|
||
|
||
渲染设备管理器。
|
||
|
||
**参数：**
|
||
- `config` (Object) - 配置对象
|
||
|
||
**返回：**
|
||
- (Object) - 设备管理器实例
|
||
|
||
### close()
|
||
|
||
关闭模态框（仅 modal 模式）。
|
||
|
||
```javascript
|
||
Fido2UIManager.close();
|
||
```
|
||
|
||
### refresh()
|
||
|
||
刷新设备列表和会话状态。
|
||
|
||
```javascript
|
||
Fido2UIManager.refresh();
|
||
```
|
||
|
||
### destroy()
|
||
|
||
销毁设备管理器实例。
|
||
|
||
```javascript
|
||
Fido2UIManager.destroy();
|
||
```
|
||
|
||
## 事件系统
|
||
|
||
SDK 提供以下事件：
|
||
|
||
| 事件名称 | 触发时机 | 回调参数 |
|
||
|---------|---------|---------|
|
||
| `init` | 初始化完成 | (manager) |
|
||
| `deviceAdded` | 设备添加成功 | (device) |
|
||
| `deviceDeleted` | 设备删除成功 | (deviceId) |
|
||
| `deviceListLoaded` | 设备列表加载完成 | (devices) |
|
||
| `sessionStatusChanged` | 会话状态改变 | (isValid) |
|
||
| `error` | 发生错误 | (error) |
|
||
| `close` | 窗口关闭 | 无 |
|
||
|
||
## 向后兼容性
|
||
|
||
SDK 完全兼容现有的对接方式：
|
||
|
||
- ✅ `devices.html` - 继续使用现有逻辑，无需修改
|
||
- ✅ `login.html` - 继续使用现有逻辑，无需修改
|
||
- ✅ `dfido2-lib.js` - 核心库保持不变
|
||
- ✅ 所有 CSS 文件 - 保持原样
|
||
|
||
## 浏览器支持
|
||
|
||
- Chrome 67+
|
||
- Firefox 60+
|
||
- Safari 13+
|
||
- Edge 18+
|
||
|
||
## 依赖
|
||
|
||
- jQuery 3.x
|
||
- Bootstrap 5.x
|
||
- dfido2-lib.js（核心 FIDO2 库）
|
||
|
||
## 演示
|
||
|
||
- [模态框模式演示](modal-demo.html)
|
||
- [独立页面模式演示](standalone-demo.html)
|
||
|
||
## 注意事项
|
||
|
||
1. 确保 `dfido2-lib.js` 在 `fido2-ui-sdk.js` 之前加载
|
||
2. Modal 模式需要提供有效的容器选择器
|
||
3. 独立页面模式会替换当前页面的内容
|
||
4. 确保浏览器支持 WebAuthn API
|
||
|
||
## 许可证
|
||
|
||
[根据您的项目许可证填写]
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请联系 [您的联系方式]
|