# @appsemble/sdk 中文文档

规范地址：https://npmcn.com/package/%40appsemble/sdk/

版本：0\.40\.9
npm 元数据更新时间：2026-10-29T22:59:51.741Z
中文译文更新时间：2026-11-06T15:46:42.062Z
软件包许可：LGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40appsemble/sdk
原文对照：https://npmcn.com/package/%40appsemble/sdk/?lang=original
项目主页：https://appsemble.app/
源码仓库：https://gitlab.com/appsemble/appsemble

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

- 包体积（解压后）：25.1 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2017-06-14T09:12:42.194Z
- 最新版本发布：2026-10-29T22:59:51.383Z
- 近 30 天下载量：2841（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：379（近 12 个月 62 个）

## 中文简介

自己建块

## 安装

```sh
npm install @appsemble/sdk
```

也可以使用：`pnpm add @appsemble/sdk`、`yarn add @appsemble/sdk`、`bun add @appsemble/sdk`

## README

# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.40.9/config/assets/logo.svg) 应用 SDK

> 自己建块

[![npm](https://img.shields.io/npm/v/@appsemble/sdk)](https://www.npmjs.com/package/@appsemble/sdk) [![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.40.9/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.40.9) [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io/)

## 目录

-   [安装](https://npmcn.com/package/%40appsemble/sdk/#readme-installation)
-   [使用量](https://npmcn.com/package/%40appsemble/sdk/#readme-usage)
    -   [`bootstrap`](https://npmcn.com/package/%40appsemble/sdk/#readme-bootstrap)
    -   [类型脚本接口](https://npmcn.com/package/%40appsemble/sdk/#readme-typescript-interfaces)
        -   [参数](https://npmcn.com/package/%40appsemble/sdk/#readme-parameters)
        -   [行动](https://npmcn.com/package/%40appsemble/sdk/#readme-actions)
        -   [活动](https://npmcn.com/package/%40appsemble/sdk/#readme-events)
        -   [信件](https://npmcn.com/package/%40appsemble/sdk/#readme-messages)
-   [许可证](https://npmcn.com/package/%40appsemble/sdk/#readme-license)

## 安装

```sh
npm install @appsemble/sdk
```

## 使用量

### `bootstrap`

拖曳功能会记录一个函数, 每次区块的新实例都会被调用 创建。 如果块返回一个 DOM 节点, 它会附在块的阴影根上 .

功能可能是同步的,但不应该等待动作完成,因为动作是 延迟到页面上的所有块都准备好 .

```js
import { bootstrap } from '@appsemble/sdk';

bootstrap(({ utils }) => {
  const root = document.createElement('span');
  root.textContent = utils.formatMessage('hello');
  return root;
});
```

### 类型脚本接口

可以通过在 `@appsemble/sdk`。这允许您 作为块开发者以安全的方式工作,同时提供验证和文档 用户在应用程序中执行您的块.

#### 参数

区块参数可通过扩大 `@appsemble/sdk#Parameters` 接口。 这个 应用 CLI 将从这些类型定义中自动创建 JSON schema. 这包括 信技司的评论。 强烈建议正确记录生成的此界面 文档是用户化的。 JSON schema属性可以被写作TSDoc标记. 马克下是 在描述中支持.

```ts
declare module '@appsemble/sdk' {
  interface Parameters {
    /**
     * This is an example string parameter.
     *
     * @format email
     * @maxLength 50
     * @minLength 10
     * @pattern ^.+@.*+\..+$
     * @example 'Example string'
     */
    exampleString: string;

    /**
     * This is an number parameter.
     *
     * @type integer
     * @maximum 1337
     * @minimum 42
     * @multipleOf 3
     * @example 123
     */
    exampleNumber: number;
  }
}
```

#### 行动

区块动作可以通过增加 `@appsemble/sdk#Action` 接口。 只有动作 使用了密钥和TSDoc描述。 标记被支持在描述中 .

```ts
declare module '@appsemble/sdk' {
  interface Action {
    /**
     * This is an example action.
     */
    onClick: never;
  }
}
```

#### 活动

块事件发射器可以通过增强 `@appsemble/sdk#EventEmitters` 接口. 块事件听众可以通过增强 `@appsemble/sdk#EventListeners` 接口. 对发射人和听众都只使用密钥和TSDoc描述. 马克下是 在描述中支持.

```ts
declare module '@appsemble/sdk' {
  interface EventEmitters {
    /**
     * This is an example event emitter.
     */
    data: never;
  }

  interface EventListeners {
    /**
     * This is an example event listener.
     */
    refresh: never;
  }
}
```

#### 信件

块信息可以通过增强 `@appsemble/sdk#Messages` 接口。 价值观 调用时这些属性用于类型安全 `utils.formatMessage()`。马克德是 在描述中支持.

```ts
declare module '@appsemble/sdk' {
  interface Messages {
    /**
     * This message doesn’t support variables
     */
    bye: never;

    /**
     * This message accepts a variable named `name`.
     */
    hello: {
      name: string;
    };
  }
}
```

## 许可证

[LGPL-3.0 仅限](https://gitlab.com/appsemble/appsemble/-/blob/0.40.9/LICENSE.md) © [应用](https://appsemble.com/)

## 常见问题

### @appsemble/sdk 是什么？

自己建块

### 如何安装 @appsemble/sdk？

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

### @appsemble/sdk 支持 TypeScript 吗？

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

### @appsemble/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @appsemble/sdk 可以商用吗？

@appsemble/sdk 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @appsemble/sdk 的下载量有多少？

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

### @appsemble/sdk 还在维护吗？

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