# @bytedance/mona-runtime 中文文档

规范地址：https://npmcn.com/package/%40bytedance/mona-runtime/

版本：0\.3\.50
npm 元数据更新时间：2026-01-21T09:38:15.650Z
中文译文更新时间：2026-11-09T00:38:20.029Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bytedance/mona-runtime
原文对照：https://npmcn.com/package/%40bytedance/mona-runtime/?lang=original

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

- 包体积（解压后）：24.2 kB，28 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：6 个
- peer 依赖：react ^17\.0\.2，react-dom ^17\.0\.2
- 首次发布：2021-11-01T07:56:43.868Z
- 最新版本发布：2026-01-21T09:38:15.478Z
- 近 30 天下载量：1904（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：391（近 12 个月 3 个）

## 中文简介

商贸应用软件的开发和制造工具

## 安装

```sh
npm install @bytedance/mona-runtime
```

也可以使用：`pnpm add @bytedance/mona-runtime`、`yarn add @bytedance/mona-runtime`、`bun add @bytedance/mona-runtime`

## README

# mona-runtime

mona 运行时

## 组件

### Link

跳转组件，支持插件/应用间页面跳转

#### 例子

```jsx
import { Link } from '@bytedance/mona-runtime';

const Index = () => {
  return (
    <div>
      <Link to="/pages/home/index">navigate to home </Link>
    </div>
  );
};

export default Index;
```

#### 参数说明

| 参数 | 说明 | 是否必填 | 类型 | 默认值 |
| --- | --- | --- | :-: | :-: |
| to | 要跳转的页面路由 | 是 | string | \- |

## 通用 API

### navigateTo

路由跳转，跳转到新的页面

#### 例子

```js
import { navigateTo } from '@bytedance/mona-runtime';

navigateTo('/pages/home/index');
```

### redirectTo

路由重定向，跳转并替换当前页面路由

#### 例子

```js
import { redirectTo } from '@bytedance/mona-runtime';

redirectTo('/pages/home/index');
```

## 飞鸽 API

飞鸽 API 分为两类

-   以`onXXXX`开头的监听类 API，该类 API 接受回调函数作为参数，当在飞鸽中相应事件发生时，飞鸽会调用传过来的回调函数。注意: 监听类的方法，只会记录最后一次监听的函数, 建议把监听的结果存入到全局变量。
-   非`onXXXX`开头的普通的 API，可以直接触发飞鸽中相应的动作
    
    > 注意：飞鸽 API 需要在开放平台中拥有相应的插件 API 权限包
    

### addToInputBoxSafely

#### 使用场景

复制信息到输入框，支持文字。

#### 对应权限包

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 |
| --- | --- | --- | :-: |
| AddToInputBoxSafely | 端操作权限 | 端操作权限 | 端复制能力 |

#### 入参

| 名称 | 类型 | 是否必填 | 描述 |
| --- | --- | --- | :-: |
| success | Function | ❌ | 1\. 用户未被拉黑  
  
  - 正在接待中 ，✅ 可复制  
  
  - 用户不在接待中，下列条件同时满足， ✅ 可复制  
  
    \_ 客服非离线  
  
    \_ 7 天内有会话  
  
    \* 当前用户没有正在与其他客服对话  
 |
| fail | ( error: { code: number, message: string } ) => void | ❌ | 复制失败 |
| data | string | ✅ | 消息内容，length > 0 |

### login

#### 使用场景

获取当前客服登录态 token，通过开放接口换取当前飞鸽登录用户信息

#### 对应权限包

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 |
| --- | --- | --- | :-: |
| Login | 端操作权限 | 端操作权限 | 飞鸽登录能力 |

#### 入参

| 名称 | 类型 | 是否必填 | 描述 |
| --- | --- | --- | :-: |
| success | ( res: { token: string; shopId: number } ) => void | ❌ | 获取登录态 token |
| fail | ( error: { code: number; message: string } ) => void | ❌ | 获取失败 |

#### 错误码

| 错误码 | 错误描述 | 排查 |
| --- | --- | --- |
| \-100 | 未知错误 | 可能主应用内部原因。 |
| \-101 | 缺参数、入参类型错误 | 检查入参类型 |
| \-102 | 无权限 | 无权限，到开放平台申请权限包 |
| \-103 | 应用不提供此能力 | 本身无此能力/ 应用未实现此功能 |

#### 示例代码

```javascript
import { pigeon } from '@bytedance/mona-runtime';

pigeon.login({
  success: token => {
    // 传输token到自己服务端换以取自己的登录态
  },
  fail: error => {
    console.log(error);
  }, // {code: -100, message: '未知错误'}
});
```

### getInitInfo

#### 使用场景

应用初始化时获取信息。

#### 对应权限

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | 对应参数 |
| --- | --- | --- | :-: | :-: |
| UserID | 用户数据权限 | 端数据权限 | 用户 ID | user\_id |
| ShopID | 店铺数据权限 | 端数据权限 | 店铺 ID | shop\_id |
| CustomsServiceNo | 客服数据权限 | 端数据权限 | 客服编号 | customer\_service\_id |
| CustomsServiceNickName | 客服数据权限 | 端数据权限 | 客服昵称 | customer\_service\_name |

#### 入参

| 名称 | 类型 | 是否必填 | 描述 |
| --- | --- | --- | :-: |
| success | (data: InitInfo) => void  
 | ❌ | 会将有权限的数据，透传给插件。 |
| fail | ( error: { code: number, message: string } ) => void | ❌ | 获取数据失败 |

#### 出参

#### 错误码

| 错误码 | 错误描述 | 排查 |
| --- | --- | --- |
| \-100 | 未知错误 | ① 非飞鸽容器环境  
② 飞鸽内部原因，请咨询官方人员 |
| \-103 | 应用不提供此能力 | 本身无此能力/ 应用未实现此功能 |

#### 示例代码

```javascript
import { pigeon } from '@bytedance/mona-runtime';

pigeon.getInitInfo({
  success: data => {
    //  {
    //    user_id: '',
    //    customer_service_id '': ,
    //    customer_service_name: '',
    //    shop_id: ''
    //  }
    console.log(data);
  },
  fail: error => {
    console.log(error);
  }, // {code: -100, message: '未知错误'}
});
```

### onCurrentCustomerChange

#### 使用场景

监听用户改变，当切换飞鸽左侧的用户时，会触发该 API 回调。 没申请 user\_id 权限包时，将不会监听到对应变化。

#### 对应权限

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | 对应参数 |
| --- | --- | --- | :-: | :-: |
| UserID | 用户数据权限 | 端数据权限 | 用户 ID | user\_id |

#### 出参

|  | 类型 | 含义 |
| --- | --- | --- |
| UserInfo | {  
user\_id: string  
} | 用户 openid |

#### 示例代码

```javascript
import { pigeon } from '@bytedance/mona-runtime';

pigeon.onCurrentCustomerChange(data => {
  console.log(data);
  // {
  //   user_id: 'xxxxxxx',
  // }
});
```

### onShow

#### 使用场景

监听插件展示，当插件在飞鸽中前台展示时，会触发该 API 回调

-   自定义按钮跳转, 会携带部分参数。申请权限后，才会携带相应数据。
    
-   从 tab 点击进入
    

#### 参数对应权限包

| 位置 | 入口 | 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | 对应参数 |
| --- | --- | --- | :-: | :-: | :-: | :-: |
| 位置 1 | 售后单入口 | AfterSaleID | 售后单数据权限 | 端数据权限 | 售后单 ID | after\_sale\_id |
| 位置 2 | 商品单入口 | SkuOrderID | 订单数据权限 | 端数据权限 | sku 单 ID | sku\_order\_id |
| 位置 3 | 店铺单入口 | OrderID | 订单数据权限 | 端数据权限 | 订单 ID | order\_id |
| 位置 4 | 商品列表入口 | ProductID | 商品数据权限 | 端数据权限 | 商品 ID | product\_id |

![](https://p3-ecom-fe.byteimg.com/tos-cn-i-w59vco1lho/04922a15758344339194b16dad5ea2e2.png~tplv-w59vco1lho-png.png) ![](https://p3-ecom-fe.byteimg.com/tos-cn-i-w59vco1lho/9c5dd44059381606a3d2cd90b359c83b.png~tplv-w59vco1lho-png.png)

#### 出参

| key | 类型 | 含义 |
| --- | --- | --- |
| showFrom  
 | 0 | 1 | 2 | 3 | 4  
 | 0：点击 tab 进入  
自定义按钮跳转  
1：店铺单进入 order\_id  
2：商品单进入 sku\_order\_id  
3：售后单进入 after\_sale\_id  
4：商品列表进入 product\_id |
| query  
 | interface InitInfo {  
order\_id?: string;  
sku\_order\_id?: product\_id;  
after\_sale\_id?: string;  
product\_id?: string;  
} | 官方参数。申请权限后，自定义按钮跳转会携带位置对应参数。  
 |
| extraData  
 | Record<string,string>  
 | 自定义按钮中配置的参数  
路径【飞鸽】-【客服管理】-【应用管理】- 【应用设置】-【非官方插件-设置】  
![](https://p3-ecom-fe.byteimg.com/tos-cn-i-w59vco1lho/b77b699287e5692cd940b000c60b6965.png~tplv-w59vco1lho-png.png)  
![](https://p3-ecom-fe.byteimg.com/tos-cn-i-w59vco1lho/0e075d12e48790fde76a6dd6d8b87245.png~tplv-w59vco1lho-png.png)  
 |

#### 示例代码

```javascript
import { pigeon } from '@bytedance/mona-runtime';

pigeon.onShow(data => {
  console.log(data);
  // {
  //   showFrom: 0,
  //   query: {},
  //   extraData: {},
  // }
});
```

## 店铺装修 API

### 1.拉取ts声明

使用`MaxSubAutoTypeWebpackPlugin`插件，并在启动项目时便会自动拉取ts声明。

```js
//webpack.config.js
const { MaxSubAutoTypeWebpackPlugin } = require("@bytedance/mona-plugin-events");

module.exports = {
  // ....
  plugins: [
    // ...
    new MaxSubAutoTypeWebpackPlugin(),
  ]
};
//运行webpack serve 获得代码提示
```

### 2.使用JsApi

```js
import {max} from '@bytedance/mona-runtime';
//假设店铺端注册了getUserInfo以及getUserInfoSync两个方法
//调用同步getUserInfoSync方法
let user=max.getUserInfoSync({userName:'kenny'});
//调用异步getUserInfo方法
max.getUserInfo({userName:kenny}).then(res=>{console.log(res)}).catch(err=>console.error(err))
```

### 3.注册装修组件端api

通过on或once前缀的方法调用，便可进行api注册

```js
import {max} from '@bytedance/mona-runtime';
//同步方法注册
max.onShowSync((data)=>{},{isSync:true});
//异步方法注册
max.onShow((data)=>{});

//使用once，调用一次后自动注销api
//同步方法注册
max.onceShowSync((data)=>{},{isSync:true});
//异步方法注册
max.onceShow((data)=>{});
```

使用off前缀方法可对api进行手动移除

```js
import {max} from '@bytedance/mona-runtime';
let listener=max.onShow((data)=>{});
max.offShow(listener);
```

## 常见问题

### @bytedance/mona-runtime 是什么？

商贸应用软件的开发和制造工具

### 如何安装 @bytedance/mona-runtime？

在项目目录运行 npm install @bytedance/mona-runtime，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^17\.0\.2）、react-dom（^17\.0\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bytedance/mona-runtime 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bytedance\_\_mona-runtime 是否存在。

### @bytedance/mona-runtime 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bytedance/mona-runtime 可以商用吗？

@bytedance/mona-runtime 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bytedance/mona-runtime 的下载量有多少？

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

### @bytedance/mona-runtime 还在维护吗？

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