# @deskpro/app-sdk 中文文档

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

版本：6\.0\.9
npm 元数据更新时间：2026-09-23T14:25:42.152Z
中文译文更新时间：2026-11-12T01:23:55.828Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：7.2 MB，256 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：27 个
- peer 依赖：react ^18，react-dom ^18，@types/react ^18，@types/react-dom ^18，@deskpro/deskpro-ui ^8\.0\.0
- 首次发布：2022-02-04T11:59:08.688Z
- 最新版本发布：2026-09-23T14:25:41.975Z
- 近 30 天下载量：5257（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：156（近 12 个月 2 个）

## 中文简介

桌面软件应用程序 SDK

## 安装

```sh
npm install @deskpro/app-sdk
```

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

## README

# 桌面软件应用程序 SDK

Deskpro Apps SDK 提供了一个客户端,用于与 Deskpro 系统通信, React UI 组件以及基础 用于简单的应用程序和部件的样式和公用事业.

## 安装

通过安装 SDK `pnpm` 或者说 `npm`数字 :

```bash
pnpm add @deskpro/app-sdk
```

或

```bash
npm install @deskpro/app-sdk
```

## 基本用途

在与 Deskpro 系统通信时, 应用程序或部件必须注册关键事件的“听众 ” :

-   **准备** - 当应用程序被装入时,但不一定向用户显示
-   **显示** - 应用程序已经透露给用户
-   **变化** - 数据(文稿)从Officepro传送到应用程序已经改变

要注册一个收听器, 您需要先导入并创建一个 Appro 客户端, 注册 收听器, 最后运行客户端 :

```javascript
import { createClient } from "@deskpro/app-sdk";

const client = createClient();

client.onReady((context) => {
  // do something when the app is ready
});

client.onShow((context) => {
  // do something when the app is shown to the user
});

client.onChange((context) => {
  // do something when the "context" data has changed
});

client.run();
```

顺便说一句,在页面装入后"运行"客户端总是最好的,最简单的方式 这是用来注册 `client.run()` 调用为 `window.onload` 方法 :

```javascript
import { createClient } from "@deskpro/app-sdk";

const client = createClient();

window.onload = () => client.run();

// ...
```

来做 `fetch` 通过应用程序代理请求, 并因此获得访问应用程序设置, 我们已经提供了 覆盖原生工具 `fetch` 在浏览器中的函数 :

```javascript
import { createClient, proxyFetch } from "@deskpro/app-sdk";

const client = createClient();

window.onload = () => client.run();

proxyFetch(client).then((dpFetch) => {
  // Use dpFetch() just like you would use fetch() natively.
  dpFetch("https://example.com/api/things?api_key=__key__").then((res) => {
    // ...
  });
});
```

通知代理将替换格式的占位符 `__<setting>__`在这个例子中, `__key__` 将 替换为app后端设置 `key`。代理设置占位符可放入 URL, 请求头或正文.

您也可以控制 Askpro 本身的方面, 如 app 标题和图标徽章 计数 。 要做到这一点,请使用客户端 再次设置这些属性 :

```javascript
import { createClient } from "@deskpro/app-sdk";

const client = createClient();

window.onload = () => client.run();

client.setTitle("My New Title");
client.setBadgeCount(42);
```

## UI 组件

Apps SDK 输出数个 [服务台](https://github.com/deskpro/deskpro-product/tree/master/packages/deskpro-ui) 组件和组件 由出版的每个故事书支持.

所有应用 UI 组件都位于 `src/ui/components` 通常由三个文件组成:

-   组件文件,例如:. `Button.tsx` 出口或复合部分
-   故事文件,例如:. `Button.stories.tsx` 包含组件的故事
-   索引文件

要开始开发UI组件,请使用:

```bash
pnpm start
```

准备建设时,运行此库的标准建设过程:

```bash
pnpm build
```

**说明:** UI 组件为 **未捆绑**相反,它们可以在无害环境管理和CJS模块中找到.

## 测试

要运行 SDK 测试套件, 请执行以下操作 :

```bash
pnpm test
```

或

```bash
npm run test
```

## 常见问题

### @deskpro/app-sdk 是什么？

桌面软件应用程序 SDK

### 如何安装 @deskpro/app-sdk？

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

### @deskpro/app-sdk 支持 TypeScript 吗？

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

### @deskpro/app-sdk 支持 ESM 还是 CommonJS？

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

### @deskpro/app-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deskpro/app-sdk 可以商用吗？

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

### @deskpro/app-sdk 的下载量有多少？

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

### @deskpro/app-sdk 还在维护吗？

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