Nelze vybrat více než 25 témat Téma musí začínat písmenem nebo číslem, může obsahovat pomlčky („-“) a může být dlouhé až 35 znaků.
 
 
 

3.6 KiB

登录 Widget 设计文档

日期:2026-05-20 | 分支:master | 状态:已批准

概述

将现有前端登录表单封装为独立的 JS Widget,嵌入方通过 <script> 标签引入后渲染登录表单,调用现有 /api/user/login 接口完成认证,登录成功后通过回调返回用户数据。

核心原则:零后端改动,纯前端实现。

嵌入方使用方式

<div id="login-container"></div>
<script src="https://new-api.example.com/static/login-widget.js"></script>
<script>
  const widget = NewApiLoginWidget.init({
    container: '#login-container',
    apiUrl: 'https://new-api.example.com',
    onSuccess: (data) => {
      // data = { id, username, display_name, role, status, group }
      console.log('登录成功:', data);
    },
    onError: (err) => {
      console.log('登录失败:', err.message);
    }
  });

  // 销毁
  widget.destroy();
</script>

Widget API

NewApiLoginWidget.init(options)

参数 类型 必填 说明
container string \| Element 挂载点,CSS 选择器或 DOM 元素
apiUrl string new-api 服务地址
onSuccess (data: UserData) => void 登录成功回调
onError (err: { message: string }) => void 登录失败回调
theme 'light' \| 'dark' 主题,默认 'light'

返回值

{ destroy: () => void } — 调用 destroy() 卸载 Widget 并清理 DOM。

回调数据格式

// onSuccess 回调参数
interface UserData {
  id: number;
  username: string;
  display_name: string;
  role: number;
  status: number;
  group: string;
}

技术方案

构建方式

web/widget/ 目录下创建独立的 Vite 入口,打包成 UMD 格式。

web/widget/
  index.jsx          # 入口:init() API,创建 Shadow DOM 并挂载 React 组件
  LoginForm.jsx      # 登录表单组件(参考 web/src/components/auth/LoginForm.jsx)
  styles.css         # Widget 样式
  vite.config.js     # UMD 打包配置

样式隔离

使用 Shadow DOM 隔离 Widget 样式,防止与嵌入方 CSS 冲突。

API 调用

直接调用现有 POST /api/user/login 接口,跨域 CORS 已开启(AllowAllOrigins + AllowCredentials)。

请求:

POST {apiUrl}/api/user/login
{ "username": "xxx", "password": "xxx" }

响应(成功):

{
  "success": true,
  "data": {
    "id": 1,
    "username": "user",
    "display_name": "User",
    "role": 1,
    "status": 1,
    "group": "default"
  }
}

响应(失败):

{ "success": false, "message": "用户名或密码错误" }

打包产物

  • 输出:web/build/static/login-widget.js
  • 格式:UMD(全局暴露 NewApiLoginWidget
  • CSS 内联到 JS bundle 中,通过 Shadow DOM 注入
  • React 和 ReactDOM 打包进 bundle(避免要求嵌入方提供 React)

托管

由 new-api 后端的静态文件服务自动托管。构建流程:

  1. cd web && bun run build — 构建主前端
  2. cd web/widget && bun run build — 构建 Widget(输出到 web/build/static/
  3. 最终 web/build/static/login-widget.js 随 new-api 部署

改动范围

位置 改动
web/widget/ 新增目录,Widget 源码
后端 无改动
构建流程 Makefileweb/package.json 添加 Widget 构建步骤

范围限定(当前迭代)

  • 仅支持密码登录
  • 不处理 2FA
  • 不处理 OAuth/Passkey 等其他登录方式
  • 不管理嵌入方的认证状态(通过回调交由嵌入方处理)