Arthub Portal Login SDK

一个用于 arthub.qq.com 子站登录的轻量级 SDK。调用即可弹出登录窗口（基于 iframe），登录成功后通过 postMessage 取回 token 并以 Promise 形式返回。

特性

• 🚀 零依赖，纯浏览器环境运行
• 📦 同时输出 ESM / CJS / UMD 三种产物，支持 <script> 标签直接引入
• 🔒 内置 postMessage 来源（origin）校验，避免恶意页面伪造 token
• 🎨 自带遮罩层、ESC 关闭、点击遮罩关闭等交互
• 🧩 支持自定义 iframe 尺寸、URL、超时时间等参数
• 💪 完整的 TypeScript 类型声明

安装

npm install arthub-portal-login
# 或
yarn add arthub-portal-login

或通过 <script> 引入 UMD 包（暴露全局变量 ArthubPortalLogin）：

<script src="https://your-cdn.com/arthub-portal-login/dist/index.umd.min.js"></script>

快速开始

ES Module

import { ArthubPortalLogin } from "arthub-portal-login";

const sdk = new ArthubPortalLogin();

try {
  const { token, raw } = await sdk.login();
  console.log("登录成功，token =", token);
} catch (err) {
  console.error("登录失败：", err);
}

一次性调用（便捷方法）

import { login } from "arthub-portal-login";

const { token } = await login({ width: 720, height: 900 });

UMD / <script> 方式

<script src="./dist/index.umd.js"></script>
<script>
  const sdk = new ArthubPortalLogin.ArthubPortalLogin();
  sdk.login().then(({ token }) => {
    console.log(token);
  });
</script>

API

new ArthubPortalLogin(defaults?: LoginOptions)

创建 SDK 实例。可在构造时传入默认配置，调用 login() 时再覆盖。

sdk.login(options?: LoginOptions): Promise<LoginResult>

打开登录弹窗，返回登录结果的 Promise。

sdk.close(): void

主动关闭登录弹窗（如果有正在进行的 login() 调用，会以 USER_CLOSED 错误 reject）。

LoginOptions

| 字段 | 类型 | 默认值 | 说明 | | ------------------ | -------------------- | -------------------------------------------- | ----------------------------------- | | width | number | 638 | iframe 宽度 (px) | | height | number | 954 | iframe 高度 (px) | | url | string | https://arthub.qq.com/login?onlyLogin=true | 登录页 URL | | allowedOrigin | string \| string[] | 由 url 推导 | 允许接收消息的 origin，建议保持默认 | | mask | boolean | true | 是否显示遮罩层 | | closeOnMaskClick | boolean | false | 点击遮罩是否关闭弹窗 | | zIndex | number | 9999 | 弹窗层级 | | autoClose | boolean | true | 收到 token 后是否自动关闭弹窗 | | timeout | number | 0 | 超时时间 (ms)，0 表示不超时 |

LoginResult

interface LoginResult {
  token: string; // 登录 token
  raw: LoginSuccessMessage; // 完整的原始消息载荷
}

错误处理

SDK 抛出的异常均为 LoginError 实例，含 code 字段：

| code | 说明 | | -------------- | --------------------------------- | | USER_CLOSED | 用户主动关闭弹窗 / ESC / 点击遮罩 | | TIMEOUT | 超过 timeout 时间未收到 token | | ALREADY_OPEN | 已有弹窗在打开中 | | INVALID_ENV | 非浏览器环境 |

登录页需要做什么？

登录页（https://arthub.qq.com/login?onlyLogin=true）在登录成功后，需要通过 window.parent.postMessage 把 token 发送给 SDK：

// 登录成功的页面侧代码
window.parent.postMessage(
  {
    type: "arthub-login-success", // 或者 'login-success' / 事件名 'loginSuccess'
    token: "YOUR_TOKEN_HERE",
    // 可选：附加任何额外字段，会原样回传到 raw
    userInfo: {
      /* ... */
    },
  },
  "*", // 建议指定 SDK 宿主页面的 origin 而非 '*'
);

SDK 默认仅识别 type 或 event 字段为 arthub-login-success、login-success、loginSuccess 三种之一的消息。

开发

npm install
npm run build      # 打包产物到 dist/
npm run dev        # 开发模式 (watch)
npm run type-check # 仅类型检查

打开 examples/index.html 即可在浏览器中试跑。

License

MIT