dqj/sample-site

Fork 0

Files

dqj 6c9491bfd0 Add SSO and device management samples

2026-05-20 22:40:32 +09:00

13 KiB

Raw Blame History

FIDO2 UI SDK - API 文档

全局对象

Fido2UIManager

全局 FIDO2 UI 管理对象。

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)

渲染设备管理器。

语法：

Fido2UIManager.renderDeviceManager(config)

参数：

config (Object) - 配置对象，详见配置选项

返回值：

(Object) - 设备管理器实例

示例：

const manager = Fido2UIManager.renderDeviceManager({
  container: '#device-container',
  mode: 'modal',
  serverUrl: 'https://fido2.amipro.me'
});

close()

关闭模态框（仅 modal 模式有效）。

语法：

Fido2UIManager.close()

示例：

Fido2UIManager.close();

refresh()

刷新设备列表和会话状态。

语法：

Fido2UIManager.refresh()

示例：

Fido2UIManager.refresh();

destroy()

销毁设备管理器实例，清理资源。

语法：

Fido2UIManager.destroy()

示例：

Fido2UIManager.destroy();

事件系统

事件列表

事件名称	触发时机	回调参数
`init`	初始化完成	(manager: Object)
`deviceAdded`	设备添加成功	(device: Object)
`deviceDeleted`	设备删除成功	(deviceId: String)
`deviceListLoaded`	设备列表加载完成	(devices: Array)
`sessionStatusChanged`	会话状态改变	(isValid: Boolean)
`error`	发生错误	(error: Error)
`close`	窗口关闭	无

事件参数详解

init

初始化完成时触发。

参数：

manager (Object) - 设备管理器实例

示例：

Fido2UIManager.renderDeviceManager({
  callbacks: {
    onInit: function(manager) {
      console.log('设备管理器已初始化', manager);
    }
  }
});

deviceAdded

设备添加成功时触发。

参数：

device (Object) - 添加的设备信息

示例：

Fido2UIManager.renderDeviceManager({
  callbacks: {
    onDeviceAdded: function(device) {
      console.log('设备添加成功', device);
      // 刷新用户界面
      refreshUserInterface();
    }
  }
});

deviceDeleted

设备删除成功时触发。

参数：

deviceId (String) - 被删除设备的 ID

示例：

Fido2UIManager.renderDeviceManager({
  callbacks: {
    onDeviceDeleted: function(deviceId) {
      console.log('设备删除成功', deviceId);
      // 显示成功提示
      showNotification('设备删除成功');
    }
  }
});

deviceListLoaded

设备列表加载完成时触发。

参数：

devices (Array) - 设备列表

示例：

Fido2UIManager.renderDeviceManager({
  callbacks: {
    onDeviceListLoaded: function(devices) {
      console.log('设备列表加载完成，共', devices.length, '个设备');
    }
  }
});

sessionStatusChanged

会话状态改变时触发。

参数：

isValid (Boolean) - 会话是否有效

示例：

Fido2UIManager.renderDeviceManager({
  callbacks: {
    onSessionStatusChanged: function(isValid) {
      if (isValid) {
        console.log('会话有效');
      } else {
        console.log('会话无效，请重新登录');
      }
    }
  }
});

error

发生错误时触发。

参数：

error (Error) - 错误对象

示例：

Fido2UIManager.renderDeviceManager({
  callbacks: {
    onError: function(error) {
      console.error('发生错误:', error.message);
      // 显示错误提示
      showErrorNotification(error.message);
    }
  }
});

close

模态框关闭时触发（仅 modal 模式）。

参数：

示例：

Fido2UIManager.renderDeviceManager({
  callbacks: {
    onClose: function() {
      console.log('模态框已关闭');
    }
  }
});

国际化

支持的语言

en-US - 英文
zh-CN - 简体中文
ja - 日文

设置语言

通过 language 参数设置语言：

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 参数自定义翻译：

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'	圆角大小

基础主题定制

Fido2UIManager.renderDeviceManager({
  theme: {
    logo: '/assets/my-logo.png',
    primaryColor: '#ce59d9',
    backgroundColor: '#ffffff'
  }
});

完整主题定制

Fido2UIManager.renderDeviceManager({
  theme: {
    logo: '/assets/my-logo.png',
    primaryColor: '#0066cc',
    backgroundColor: '#f8f9fa',
    textColor: '#333333',
    borderRadius: '12px'
  }
});

深色主题示例

Fido2UIManager.renderDeviceManager({
  theme: {
    logo: '/assets/logo.png',
    primaryColor: '#4a9eff',
    backgroundColor: '#1a1a2e',
    textColor: '#ffffff',
    borderRadius: '8px'
  }
});

设备管理器实例方法

如果需要访问设备管理器实例，可以保存 renderDeviceManager 的返回值：

const manager = Fido2UIManager.renderDeviceManager(config);

实例方法

方法	说明
`close()`	关闭模态框（仅 modal 模式）
`refresh()`	刷新设备列表和会话状态
`destroy()`	销毁设备管理器实例

示例

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 示例

/* 自定义按钮样式 */
.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

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

interface ThemeObject {
  logo?: string | null;
  primaryColor?: string;
  backgroundColor?: string;
  textColor?: string;
  borderRadius?: string;
}

FeaturesObject

interface FeaturesObject {
  showAddButton?: boolean;
  showDeleteButton?: boolean;
  showUserInfo?: boolean;
  showSessionStatus?: boolean;
}

CallbacksObject

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: 如何在页面加载后自动打开设备管理器？

window.onload = function() {
  Fido2UIManager.renderDeviceManager({
    container: '#device-container',
    mode: 'modal'
  });
};

Q: 如何在用户点击按钮后才打开设备管理器？

<button onclick="openDeviceManager()">管理设备</button>
<div id="device-container"></div>

<script>
function openDeviceManager() {
  Fido2UIManager.renderDeviceManager({
    container: '#device-container',
    mode: 'modal'
  });
}
</script>

Q: 如何禁用自动刷新？

Fido2UIManager.renderDeviceManager({
  autoRefresh: false
});

Q: 如何更改刷新间隔？

Fido2UIManager.renderDeviceManager({
  autoRefresh: true,
  refreshInterval: 10000  // 10秒
});

版本历史

v1.0.0 - 初始版本
- 支持模态框和独立页面两种模式
- 支持主题定制
- 支持国际化
- 完整的事件系统

13 KiB Raw Blame History Unescape Escape

FIDO2 UI SDK - API 文档

目录

全局对象

Fido2UIManager

配置选项

config

config.theme

config.features

config.callbacks

API 方法

renderDeviceManager(config)

close()

refresh()

destroy()

事件系统

事件列表

事件参数详解

init

deviceAdded

deviceDeleted

deviceListLoaded

sessionStatusChanged

error

close

国际化

支持的语言

设置语言

默认翻译键

自定义翻译

主题定制

主题配置参数

基础主题定制

完整主题定制

深色主题示例

设备管理器实例方法

实例方法

示例

CSS 类名

自定义 CSS 示例

类型定义

ConfigObject

ThemeObject

FeaturesObject

CallbacksObject

常见问题

Q: 如何在页面加载后自动打开设备管理器？

Q: 如何在用户点击按钮后才打开设备管理器？

Q: 如何禁用自动刷新？

Q: 如何更改刷新间隔？

版本历史

13 KiB

Raw Blame History