AuthWidget.js 使用教程

这是什么

auth-widget.min.js 是一个可嵌入任意网站的登录注册UI 组件。它提供悬浮按钮、弹窗、表单校验、邮箱验证码交互、明暗主题适配，但不包含任何后端逻辑——用户存哪、邮件怎么发，由你自己的后端决定。

你只需要实现 8 个简单的 JSON 接口，这个组件就能跑起来。后端可以是任何语言（Node/Python/Go/PHP/Java 都行）。

1 分钟接入

场景 A：同站后端（最简单）

你的网站和 API 在同一个域名下，API 路径是 /api/auth/*：

<script>
  window.AuthWidgetConfig = { apiBase: '/api/auth' };
</script>
<script src="https://liuli.xx.kg/js/auth-widget.min.js"></script>

场景 B：跨域后端（第三方网站）

你的 API 在别的域名（例如 https://api.example.com）：

<script>
  window.AuthWidgetConfig = {
    apiBase:  'https://api.example.com/api/auth',
    brand:    '我的网站',
    color:    '#10b981',
    position: 'bottom-right',
  };
</script>
<script src="https://liuli.xx.kg/js/auth-widget.min.js"></script>

跨域注意：后端必须返回 CORS 头 Access-Control-Allow-Credentials: true 并显式允许你的站点 Origin；会话 Cookie 必须设 SameSite=None; Secure。

本页实时演示

右下角按钮就是本页引入插件渲染的（本页故意不配 apiBase，点登录会提示先配置）：

配置项

两种方式二选一：全局对象 window.AuthWidgetConfig，或 script 标签上的 data-*。

参数	默认值	说明
`apiBase`	`""`（必须配）	后端 API 基址，如 `/api/auth` 或 `https://api.x.com/auth`。不配会报错
`position`	`bottom-right`	悬浮位置：`bottom-right / bottom-left / top-right / top-left`
`container`	`null`	CSS 选择器，给了就渲染到该容器内、不悬浮（如 `#login-box`）
`color`	`#3b82f6`	主题色：按钮、链接、聚焦环
`brand`	`我的网站`	弹窗顶部品牌名
`defaultTab`	`login`	首次打开默认 tab：`login / register`
`onLogin`	`null`	登录成功回调，参数 `{id, username, email}`
`onLogout`	`null`	退出回调

后端接口契约（必看）

所有请求都是 POST JSON（/me 是 GET），响应也是 JSON。成功返回 { user: {...} } 或 { ok: true }；失败返回 { error: "中文提示" }，组件会直接把 error 显示在弹窗里。

① GET {apiBase}/me 查询当前登录态

成功：{ "user": { "id": 1, "username": "alice", "email": "a@b.c" } } 或 { "user": null }

② POST {apiBase}/send-code 发送邮箱验证码

请求：{ "email": "a@b.c", "purpose": "register" | "login" | "reset" }

成功：{ "ok": true }（即使邮箱无效也返回 ok，防枚举）

③ POST {apiBase}/register 注册

请求：{ "username": "alice", "password": "******", "email": "a@b.c", "emailCode": "123456" }

成功：{ "user": { ... } }，后端应同时 Set-Cookie 下发会话

④ POST {apiBase}/login 账号密码登录

请求：{ "account": "alice 或 a@b.c", "password": "******" }

成功：{ "user": { ... } }，同时下发会话 Cookie

⑤ POST {apiBase}/login-code 邮箱验证码登录

请求：{ "email": "a@b.c", "emailCode": "123456" }

成功：{ "user": { ... } }

⑥ POST {apiBase}/reset-password 忘记密码

请求：{ "email": "a@b.c", "emailCode": "123456", "newPassword": "******" }

成功：{ "ok": true }

⑦ POST {apiBase}/change-password 修改密码（需登录）

请求：{ "oldPassword": "******", "newPassword": "******" }

成功：{ "ok": true }

⑧ POST {apiBase}/logout 退出

成功：{ "ok": true }，后端应清除会话 Cookie

会话怎么传：组件用 fetch(..., { credentials: 'include' })，浏览器自动携带 HttpOnly Cookie。你不需要在前端存 token，后端自己签发 session 即可。

后端参考实现（Node.js / Cloudflare Workers）

本站（liuli.xx.kg）的 portal 项目就是这套契约的参考实现，源码在 deploy/portal/_worker.js 的 handleAuth 函数——但它不对外开放，你的用户库和邮件服务必须自己搭。

固定到导航栏（不悬浮）

<header>
  <div id="login-mount" style="margin-left:auto"></div>
</header>
<script>
  window.AuthWidgetConfig = {
    apiBase: '/api/auth',
    container: '#login-mount',
  };
</script>
<script src="https://liuli.xx.kg/js/auth-widget.min.js"></script>

手动 API

方法	作用
`AuthWidget.open('login')`	打开弹窗，可指定 `login / register / reset / code`
`AuthWidget.close()`	关闭弹窗
`AuthWidget.getUser()`	返回当前用户对象，未登录返回 null
`AuthWidget.refresh()`	重新拉取登录态（Promise）
`AuthWidget.logout()`	退出登录

常见问题

按钮点了没反应 / 提示"未配置 apiBase"

你没设置 window.AuthWidgetConfig.apiBase。组件设计上不绑定任何默认后端，必须显式指定。

跨域登录失败 / Cookie 不携带

后端必须返回 Access-Control-Allow-Credentials: true
不能用 Access-Control-Allow-Origin: *，要显式回显你的 Origin
Set-Cookie 必须 Secure; SameSite=None（跨站）

能改样式吗？

主题色用 color 参数；深度定制可覆写 CSS 变量 --aw-color 或 .aw-* 类名。

支持 IE 吗？

不支持。面向近两年的 Chrome / Edge / Safari / Firefox。