# @appboxo/web-sdk 中文文档 规范地址：https://npmcn.com/package/%40appboxo/web-sdk/ 版本：1\.4\.4 npm 元数据更新时间：2026-02-26T04:29:32.646Z 中文译文更新时间：2026-11-06T12:25:31.347Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40appboxo/web-sdk 原文对照：https://npmcn.com/package/%40appboxo/web-sdk/?lang=original 项目主页：https://github.com/Appboxo/web-sdk#readme 源码仓库：https://github.com/Appboxo/web-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：202 kB，67 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2025-10-29T06:45:12.131Z - 最新版本发布：2026-02-26T04:29:31.877Z - 近 30 天下载量：3215（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：32（近 12 个月 9 个） ## 中文简介 Boxo 桌面主机 App SDK 处理小型应用事件 ## 安装 ```sh npm install @appboxo/web-sdk ``` 也可以使用：`pnpm add @appboxo/web-sdk`、`yarn add @appboxo/web-sdk`、`bun add @appboxo/web-sdk` ## README # Appoxo 网络 SDK 使用 Iframe 通讯将微型应用程序嵌入您的桌面应用程序 . ## 快速启动 ```typescript import { AppboxoWebSDK } from "@appboxo/web-sdk"; const sdk = new AppboxoWebSDK({ clientId: "your-client-id", appId: "your-app-id" }); // Get auth code from your backend const authCode = await fetch('/api/auth-code').then(r => r.json()); sdk.setAuthCode(authCode); // Mount miniapp (SDK will automatically fetch URL from API) await sdk.mount({ container: document.getElementById("miniapp") }); ``` ## 安装 ```bash npm install @appboxo/web-sdk # or pnpm install @appboxo/web-sdk ``` ## 配置 ```typescript const sdk = new AppboxoWebSDK({ clientId: string; // Required appId: string; // Required userId?: string; // Optional, user reference identifier baseUrl?: string; // Optional, default: "https://dashboard.boxo.io/api/v1" sandboxMode?: boolean; // Optional, default: false debug?: boolean; // Optional, default: false. When true, enables all console logs for debugging. When false, no console logs are output. locale?: string; // Optional, locale/language code (e.g., 'en', 'en-US', 'ru', 'zh-CN') theme?: 'dark' | 'light' | 'system'; // Optional, theme/color scheme preference (default: 'system') onGetAuthCode?: () => Promise; // Optional, for automatic auth code retrieval onGetAuthTokens?: () => Promise; // Optional, for direct auth tokens onPaymentRequest?: (params: PaymentRequest) => Promise; // Optional, for handling payment requests }); ``` ### 认证 **OAuth 流量 :** ```typescript sdk.setAuthCode(authCode); ``` 或提供回电: ```typescript const sdk = new AppboxoWebSDK({ clientId: "your-client-id", appId: "your-app-id", onGetAuthCode: async () => { const res = await fetch('/api/generate-auth-code'); return (await res.json()).auth_code; } }); ``` **直接认证流 :** ```typescript sdk.onAuth(async () => { const response = await fetch('/api/get-miniapp-tokens'); const tokens = await response.json(); sdk.setAuthTokens(tokens.access_token, tokens.refresh_token); }); ``` 或使用回调: ```typescript const sdk = new AppboxoWebSDK({ clientId: "your-client-id", appId: "your-app-id", onGetAuthTokens: async () => { const res = await fetch('/api/get-miniapp-tokens'); const result = await res.json(); return { token: result.access_token, refresh_token: result.refresh_token }; } }); ``` 或者直接设置符号 : ```typescript const tokens = await getTokensFromBackend(); sdk.setAuthTokens(tokens.access_token, tokens.refresh_token); ``` SDK会尝试这些顺序: 1. 预设的符号( A)`setAuthTokens`(中文(简体) ) 2. 直接认证召回( N)`onGetAuthTokens`(中文(简体) ) 3. OAuth 认证代码 (`setAuthCode` 或者说 `onGetAuthCode` 调用) ### 付款处理 当一个小程序打电话 `appboxo.pay()`SDK会打电话给你 `onPaymentRequest` 调用。 处理付款并返回结果. 付款状况值: `'success'`, (中文(简体) ), `'failed'`,或 `'cancelled'`。 。 。 . ```typescript const sdk = new AppboxoWebSDK({ clientId: "your-client-id", appId: "your-app-id", onPaymentRequest: async (paymentData) => { // Process payment with your backend const response = await fetch('/api/payments/process', { method: 'POST', body: JSON.stringify(paymentData) }); const result = await response.json(); return { ...paymentData, status: result.status, // 'success', 'failed', or 'cancelled' hostappOrderId: result.orderId, transactionId: result.transactionId, // optional }; }, }); // Optional: listen for payment completion sdk.onPaymentComplete((success, data) => { if (success) { console.log('Payment succeeded:', data); } }); ``` **重要注释 :** - 何时 `onPaymentRequest` 设定, SDK 自动告诉它支持的小程序 `AppBoxoWebAppPay`,所以它可以调用 `appboxo.pay()`。 。 。 . - **若为 `onPaymentRequest` 未配置**,则付款请求会失败。 启用 `debug: true` 以查看错误消息. - **关于 `debug` 模式 :** - `debug: false` (默认):没有控制台日志是输出. 适于出产. - `debug: true`:所有SDK操作都登录到控制台. 有利于发展和解决问题. - 这个 `debug` 选项不影响 SDK 功能 - 它只控制控制控制台记录 . ### 地方/语言 设定本地语区/ 语言代码传递到小app. 该地块将被纳入InitData响应. ```typescript // Set locale during initialization const sdk = new AppboxoWebSDK({ clientId: "your-client-id", appId: "your-app-id", locale: "en-US" // or 'ru', 'zh-CN', etc. }); // Or set locale dynamically sdk.setLocale("ru"); ``` 地方通过 `InitData.data.locale` 下一个 `AppBoxoWebAppGetInitData` 请求. **重要注释 :** - 如果你打电话 `setLocale()` 在迷你app已经加载后, 语言将包含在下一个 InitData 请求中 。 迷你app可能需要重新装入或再次请求InitData来接收更新后的语言. - 为了确保立即提供该地块,在SDK初始化期间或打电话之前设置该地块 `mount()`。 。 。 . ### 主题/ 黑暗模式 设置主题/ 颜色方案首选项以传递到小应用程序 。 主题将纳入InitData回复. ```typescript // Set theme during initialization const sdk = new AppboxoWebSDK({ clientId: "your-client-id", appId: "your-app-id", theme: "dark" // or 'light', 'system' }); // Or set theme dynamically sdk.setTheme("light"); ``` 主题通过 `InitData.data.theme` 下一个 `AppBoxoWebAppGetInitData` 请求. **主题值 :** - `'dark'`: 强制黑暗模式 - `'light'`: 强制灯光模式 - `'system'`: 使用系统首选项(默认) **重要注释 :** - 如果你打电话 `setTheme()` 在迷你app已经加载后,主题将包含在下个 InitData 请求中. 迷你app可能需要重新装入或再次请求InitData来接收更新后的主题. - 为了确保立即提供主题,在 SDK 初始化期间或呼叫前设置 `mount()`。 。 。 . ### 注销 这个 `logout()` 方法清除主机应用的存储和SDK的内部认证数据. ```typescript sdk.logout(); ``` **重要注释 :** - 这只能澄清 **主机应用程序** `localStorage` 财务报告和审定财务报表 `sessionStorage` - Miniapp的存储是独立的(不同来源),由于浏览器安全限制而无法从主机应用程序中清除 - SDK会通过微程序发送登出通知 `postMessage` 使用标准 `appboxo-host-response` 格式 - 迷你游戏应该听 `AppBoxoWebAppLogout` 清除自己存储的处理器 - SDK的内部 `authCode` 财务报告和审定财务报表 `authTokens` 也被清除 **最小化集成 :** 要在您的小app中接收登出通知, 请添加一个消息倾听器 : ```typescript useEffect(() => { const handleMessage = (event: MessageEvent) => { if ( event.data?.type === "appboxo-host-response" && event.data?.handler === "AppBoxoWebAppLogout" && event.data?.data?.action === "logout" ) { // Clear miniapp's storage localStorage.clear(); sessionStorage.clear(); } }; window.addEventListener("message", handleMessage); return () => window.removeEventListener("message", handleMessage); }, []); ``` ## 方法 | 方法 | 说明 | | --- | --- | | `setAuthCode(code)` | 设置认证代码 | | `setAuthTokens(token, refreshToken?)` | 直接设置认证符 | | `setLocale(locale)` | 设置地语/语言代码(例如"en","en-US","ru","zh-CN") | | `setTheme(theme)` | 设置主题/ 颜色方案偏好( “ 暗 ” ) | | `onAuth(callback)` | 认证事件的注册回调 | | `mount(config)` | 创建 Iframe并初始化 SDK | | `getMiniappUrl()` | 从 API 设置中获取小应用程序 URL | | `setIframe(iframe)` | 手动设定 Iframe 元素 | | `initialize()` | 开始聆听事件 | | `onEvent(type, handler)` | 注册自定义事件处理器 | | `onLoginComplete(callback)` | 登录补全调用 | | `onPaymentComplete(callback)` | 支付补收 | | `logout()` | 清除主机应用程序的本地Storage, sessionStorage, 以及 SDK 的内部认证数据 | | `destroy()` | 清理资源 | ## 活动 SDK处理这些小型应用事件: - `AppBoxoWebAppLogin` - 用户认证 - `AppBoxoWebAppPay` - 付款处理 - `AppBoxoWebAppGetInitData` - 初步数据要求 - `AppBoxoWebAppCustomEvent` - 自定义活动 ## 实例 ### 反应示例 ```tsx import { AppboxoWebSDK } from "@appboxo/web-sdk"; import type { PaymentRequest, PaymentResponse } from "@appboxo/web-sdk"; function App() { const iframeRef = useRef(null); const [sdk, setSdk] = useState(null); useEffect(() => { const s = new AppboxoWebSDK({ clientId: "your-client-id", appId: "your-app-id", onPaymentRequest: async (paymentData: PaymentRequest): Promise => { const response = await fetch('/api/payments/process', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(paymentData) }); const result = await response.json(); return { ...paymentData, status: result.status, hostappOrderId: result.hostappOrderId, }; }, }); s.setAuthCode("your-auth-code"); s.onLoginComplete((success, data) => { console.log('Login:', success ? 'success' : 'failed', data); }); s.onPaymentComplete((success, data) => { console.log('Payment:', success ? 'success' : 'failed', data); }); setSdk(s); return () => s.destroy(); }, []); useEffect(() => { const fetchUrl = async () => { if (sdk && iframeRef.current) { const url = await sdk.getMiniappUrl(); iframeRef.current.src = url; } }; fetchUrl(); }, [sdk]); const handleLoad = () => { if (sdk && iframeRef.current) { sdk.setIframe(iframeRef.current); sdk.initialize(); } }; return