# @appboxo/js-sdk 中文文档

规范地址：https://npmcn.com/package/%40appboxo/js-sdk/

版本：2\.2\.1
npm 元数据更新时间：2026-08-27T08:07:03.254Z
中文译文更新时间：2026-11-06T11:19:19.593Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40appboxo/js-sdk
原文对照：https://npmcn.com/package/%40appboxo/js-sdk/?lang=original
项目主页：https://github.com/Appboxo/js-sdk#readme
源码仓库：https://github.com/Appboxo/js-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：95.5 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2019-11-14T05:01:27.087Z
- 最新版本发布：2026-08-27T08:07:03.045Z
- 近 30 天下载量：7606（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 3 个）

## 中文简介

用于 AppBoxo 小型应用平台的 JavaScript SDK

## 安装

```sh
npm install @appboxo/js-sdk
```

也可以使用：`pnpm add @appboxo/js-sdk`、`yarn add @appboxo/js-sdk`、`bun add @appboxo/js-sdk`

## README

# AppBoxo JS SDK 通用软件

Appboxo JS SDK是微型app和本土应用之间的接通桥,它具有丰富的API特性,让你的微型应用感觉像本土. 使用Appboxo JS SDK,主机应用程序可以将用户电子邮件传递给微型app,在微型app中自动注册用户.

## 使用量

```js
import appboxoSdk from '@appboxo/js-sdk';

// Sends event to client
appboxoSdk.send('AppBoxoWebAppInit');

// Subscribes to event, sended by client
appboxoSdk.subscribe(e => console.log(e));
```

用于浏览器, 包括文件 [`dist/index.umd.js`](https://unpkg.com/@appboxo/js-sdk/dist/index.umd.js) 使用情况如下:

```html
<script src="dist/index.umd.js"></script>

<script>
  // Sends event to client
  appboxoSdk.send('AppBoxoWebAppInit');
</script>
```

## 本地客户

本地客户端(Android和iOS)应该使用这个来将数据传递给小型app:

```js
window.dispatchEvent(new window.CustomEvent('AppBoxoWebAppEvent', {
  bubbles: false,
  cancelable: false,
  detail: {
    type: 'AppBoxoWebAppGetInitData',
    data: {
      app_id: 234234,
      client_id: 344343,
      payload: 'asdlj2323ljaoiw',
      token: 'qerljljqwerqwe',
      request_id: 1
    }
  }
}))
```

**重要**

如果小型应用程序引发的事件 `request_id` 内部 `data` (如上面的例子),而不是意味着 `sendPromise` 已调用, 并与 `request_id` 活动 `type` 应返回以解决这一承诺.

## 认证

### `appboxoSdk.login(optionalProps)`

向本地客户端发送消息以打开带有默认确认消息的确认模式 。 在确认后,它向平台发送请求并返回已解决的认证信使对微型app的承诺.

**参数**

-   `optionalProps` _选项_ 扩展默认登录行为的道具

**示例**

```js
try {
  const token = await appboxoSdk.login({
    confirmModalText: 'This is my custom confirmation message',
    postConfirmCallback: (isConfirmed) => { console.log('Confirmation status: ', isConfirmed) }
  });
} catch (error) {
  // Handling an error
}
```

### `appboxoSdk.logout()`

向本地客户端发送消息以清除认证符.

## API 参考

### `appboxoSdk.sendPromise(method[, params])`

向本地客户端发送消息并返回 `Promise` 有响应数据的对象

**参数**

-   `method` _所需经费_ AppBoxo js sdk 方法
-   `params` _选项_ 信件数据对象

**示例**

```js
// Sending event to client
appboxoSdk
  .sendPromise('AppBoxoWebAppGetInitData')
  .then(data => {
    // Handling received data
    console.log(data.email);
  })
  .catch(error => {
    // Handling an error
  });
```

也可以用必经之道

```js
try {
  const data = await appboxoSdk.sendPromise('AppBoxoWebAppGetInitData');

  // Handling received data
  console.log(data.email);
} catch (error) {
  // Handling an error
}
```

### `appboxoSdk.send(method[, params])`

向本地客户端发送消息

**参数**

-   `method` _所需经费_ AppBoxo js sdk 方法
-   `params` _选项_ 信件数据对象

**示例**

```js
// App initialization
appboxoSdk.send('AppBoxoWebAppInit');

// Opening images
appboxoSdk.send('AppBoxoWebAppShowImages', {
  images: [
    "https://pp.userapi.com/c639229/v639229113/31b31/KLVUrSZwAM4.jpg",
    "https://pp.userapi.com/c639229/v639229113/31b94/mWQwkgDjav0.jpg",
    "https://pp.userapi.com/c639229/v639229113/31b3a/Lw2it6bdISc.jpg"
  ]
}
```

### `appboxoSdk.subscribe(fn)`

订阅一个函数到静听事件

**参数**

-   `fn` _所需经费_ 要订阅的事件的函数

**示例**

```js
// Subscribing to receiving events
appboxoSdk.subscribe(event => {
  if (!event.detail) {
    return;
  }

  const { type, data } = event.detail;

  if (type === 'AppBoxoWebAppOpenCodeReaderResult') {
    // Reading result of the Code Reader
    console.log(data.code_data);
  }

  if (type === 'AppBoxoWebAppOpenCodeReaderFailed') {
    // Catching the error
    console.log(data.error_type, data.error_data);
  }
});

// Sending method
appboxoSdk.send('AppBoxoWebAppOpenCodeReader', {});
```

### `appboxoSdk.unsubscribe(fn)`

取消从事件监听的函数

**参数**

-   `fn` _所需经费_ 事件订阅函数

**示例**

```js
const fn = event => {
  // ...
};

// Subscribing
appboxoSdk.subscribe(fn);

// Unsubscribing
appboxoSdk.unsubscribe(fn);
```

### `appboxoSdk.supports(method)`

检查当前设备是否有事件可用

**参数**

-   `method` _所需经费_ AppBoxo js sdk 方法

### `appboxoSdk.isWebView()`

回返 `true` 如果 AppBoxo js sdk 在移动应用程序中运行,或 `false` 如果不是的话

## 常见问题

### @appboxo/js-sdk 是什么？

用于 AppBoxo 小型应用平台的 JavaScript SDK

### 如何安装 @appboxo/js-sdk？

在项目目录运行 npm install @appboxo/js-sdk，或使用 pnpm add / yarn add / bun add。

### @appboxo/js-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @appboxo/js-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @appboxo/js-sdk 可以商用吗？

@appboxo/js-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @appboxo/js-sdk 的下载量有多少？

根据 npm 官方下载统计，@appboxo/js-sdk 在 2026/10/07 – 2026/11/05 这 30 天内被下载 7,606 次，日均约 254 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @appboxo/js-sdk 还在维护吗？

最新版本 2\.2\.1 发布于 2026/08/27（2 个月前）；至今共发布 62 个版本，其中过去 12 个月发布了 3 个；首次发布于 2019/11/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。