# 登录 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`
确保 `