Client with UI
This commit is contained in:
dqj
322
docs/README.md
Normal file
322
docs/README.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# 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
|
||||
|
||||
## 许可证
|
||||
|
||||
[根据您的项目许可证填写]
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题或建议，请联系 [您的联系方式]
|
||||
Reference in New Issue
Block a user