diff --git a/docs/login-widget-guide.md b/docs/login-widget-guide.md new file mode 100644 index 0000000..a700761 --- /dev/null +++ b/docs/login-widget-guide.md @@ -0,0 +1,232 @@ +# 登录 Widget 使用指南 + +## 概述 + +登录 Widget 是一个可嵌入到任何网页的登录表单组件。通过一行 ` +``` + +### 2. 创建容器 + +在页面中放置一个 DOM 元素作为 Widget 的挂载点: + +```html +
+``` + +### 3. 初始化 Widget + +在脚本加载后调用 `NewApiLoginWidget.init()`: + +```html + +``` + +### 完整示例 + +```html + + + + + 我的网站 + + +

欢迎

+ + +
+ + + + + + + + +``` + +--- + +## API 参考 + +### `NewApiLoginWidget.init(options)` + +初始化并渲染登录表单。 + +#### 参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `container` | `string` 或 `Element` | 是 | 挂载点,支持 CSS 选择器字符串或 DOM 元素 | +| `apiUrl` | `string` | 是 | New API 服务地址,如 `https://api.example.com` | +| `onSuccess` | `function` | 否 | 登录成功回调,参数为用户数据对象 | +| `onError` | `function` | 否 | 登录失败回调,参数为 `{ message: string }` | +| `theme` | `string` | 否 | 主题,可选 `'light'`(默认)或 `'dark'` | + +#### 返回值 + +返回一个对象,包含以下方法: + +| 方法 | 说明 | +|------|------| +| `destroy()` | 卸载 Widget,清除 DOM | + +#### onSuccess 回调数据 + +```json +{ + "id": 1, + "username": "user", + "display_name": "用户", + "role": 1, + "status": 1, + "group": "default" +} +``` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | number | 用户 ID | +| `username` | string | 用户名 | +| `display_name` | string | 显示名称 | +| `role` | number | 角色(1=普通用户,10+=管理员,100+=超级管理员) | +| `status` | number | 状态 | +| `group` | string | 用户组 | + +--- + +## 主题 + +### Light(默认) + +```js +NewApiLoginWidget.init({ + container: '#login', + apiUrl: 'https://your-domain.com', + // theme: 'light' // 默认就是 light,可省略 +}); +``` + +### Dark + +```js +NewApiLoginWidget.init({ + container: '#login', + apiUrl: 'https://your-domain.com', + theme: 'dark' +}); +``` + +--- + +## 销毁 Widget + +当不再需要登录表单时(如登录成功后),调用 `destroy()` 移除: + +```js +var widget = NewApiLoginWidget.init({ ... }); + +// 登录成功后销毁 +widget.destroy(); +``` + +--- + +## 同一页面多个实例 + +支持在同一页面创建多个 Widget 实例(如同时显示 Light 和 Dark 主题): + +```html +
+
+ + + +``` + +--- + +## 注意事项 + +1. **跨域支持**:Widget 支持跨域嵌入。你的 New API 服务已配置 CORS,允许任意域名调用登录接口。 +2. **HTTPS**:生产环境建议 New API 服务使用 HTTPS,否则部分浏览器功能可能受限。 +3. **不管理会话**:Widget 只负责登录验证并返回用户数据,不会自动管理嵌入方的登录状态。你需要在 `onSuccess` 回调中自行处理用户会话。 +4. **两步验证(2FA)**:当前版本不支持 2FA。如果用户启用了两步验证,`onError` 会收到提示信息。 +5. **文件大小**:Widget JS 约 146KB(含 React 运行时),gzip 后约 48KB。 + +--- + +## 常见问题 + +### Q: 引入脚本后页面报错 `NewApiLoginWidget is not defined` + +确保 `