> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ku/create-libraries.md).

# 创建库

创建你自己的 Decentraland 库，与他人分享

库是共享常见问题解决方案的绝佳方式。复杂的挑战可以只处理一次，将解决方案封装到库中，每当再次遇到时，你只需要写一行代码。通过与社区共享库，我们可以让所有创作者的生产力呈指数级增长。

目前，这些库在 [示例页面](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library) 可供所有人使用。我们也鼓励你创建并分享自己的库。

按照这里详细说明的步骤，你可以避开创建一个与 Decentraland 场景兼容且易于与他人共享的库时所带来的大部分复杂性。

## 创建一个库

> **📔 注意**：在构建库之前，请确保你使用的是 Node 20 版或更高版本。

要创建你自己的库并通过 NPM 共享，请执行以下操作：

1. 创建一个新的空文件夹，并在其中打开一个新的 VS Studio Code 窗口。
2. 在 Visual Studio 左侧边栏中选择 Decentraland 选项卡
3. 点击 **创建项目**，然后选择 **库**

   这将为 Decentraland 库创建所有默认文件和依赖项。
4. 设置一个唯一的 `名称` 在 `package.json`。这是发布到 NPM 时使用的名称，请确保在 npm 上没有其他现有项目使用该名称。还要填写描述和任何标签，以帮助他人找到你的库。
5. 创建一个新的 *公开* GitHub 仓库，用于你的项目。

   该项目已配置为使用 GitHub Actions，在每次推送到 `main`.

   在 `package.json` 文件中，请确保在 `仓库` 你将 `url` 字段指向你的仓库 URL。这样用户在浏览 [npmjs.com](https://www.npmjs.com).
6. 获取一个 NPM 令牌：
   1. 创建一个账户或登录 <https://www.npmjs.com/。>
   2. 前往 **账户 > 访问令牌 > 生成新令牌** 创建一个新令牌，并赋予它 **发布** 权限。

      成功消息中包含一个新生成令牌的字符串。复制这串字符串并将其存放在安全的地方。
7. 在你的 GitHub 仓库中，前往 **设置 > 机密 > Actions**，然后点击 **新建仓库机密**.

   为你的机密命名 **NPM\_TOKEN**，并将 NPM 令牌中的字符串粘贴为其值。
8. 将一个更改（任意更改）推送到你的 GitHub 仓库的主分支，包就会被发布。

   就是这样，现在任何人都可以使用以下方式安装该包 `npm i <package-name>`！现在，如果你在……中按名称搜索，就可以找到你的库 [npmjs.com](https://www.npmjs.com).
9. 充实你的 `/src` 项目文件夹，加入你想要公开的全部功能，并将更改推送到 GitHub。

## 开发

将你想要公开的任何函数、组件等添加到库的 `index.ts` 文件中，这样它们就很容易导入。

例如，如果你添加一个 `RotatorComponent` 组件的 `index.ts`，然后你可以通过编写以下内容将此组件导入到场景中：

`import { RotatorComponent } from 'my-library'`

在开发过程中，使用一个新的 Decentraland 场景来测试你的库。通过运行以下命令将你的 npm 包安装到场景中 `npm i <package-name>`。然后构建一个用于试用库功能的场景。尝试用你的场景覆盖不同的测试用例，以确保你的库在各种情况下都能按预期工作。

### 快速迭代

如果你需要不断对库做小调整并进行测试，那么每次都要提交更改、然后等待 npm 发布完成，之后才能在场景中试用新版本，这会很耗费精力。幸运的是，有一种更快得多的替代方案可以用来测试你的库。

在一个 **测试场景项目**:

1. 将此脚本添加到 `scripts` 列表中，位于 package.json： `"link-sdk": "cd node_modules/@dcl/sdk && npm link && cd ../js-runtime && npm link"`
2. 运行 `npm install`
3. 运行 `npm install YOUR_LIBRARY_PATH`，例如， `npm install /User/projects/dcl-sdk7-library-test`
4. 运行 `npm run link-sdk`

在 **库项目**:

1. 运行 `npm install`
2. 运行 `npm run build`
3. 运行： `npm link @dcl/sdk @dcl/js-runtime`

> **❗警告**：这些步骤的顺序很重要。换个顺序可能行不通。

这将使你的场景与本地磁盘上直接存在的库版本保持同步。对于你想测试的任何库更改，只需运行 `npm run build` 在库文件夹中执行即可，无需将更改发布到 GitHub 或 NPM。

> **💡 提示**：要验证链接是否成功，请运行 `npm ls --link`。你应该会看到库名称指向你本地文件中的文件夹。

如果你对库做了更改，你必须运行 `npm run build` 来更新它们。为了避免每次都这样做：

1. 将脚本 "start": "tsc -p tsconfig.json --watch" 添加到库的
2. 运行 `npm start` 在库中

完成测试后，记得取消链接该库。

1. 在场景文件夹中运行 `npm install <library name>`
2. 然后在库中运行 `rm -rf node_modules && npm install`

## 版本控制

你的库版本会自动发布到 `npm` 并配合一个 `@latest` 和一个 `@next` 标记。

该 `@next` 标记始终指向……上的最后一次提交 `main` 分支。由于最后的更改可能尚未经过测试，这个版本可能不稳定。你的库用户可以通过执行以下操作安装它（风险自负）： `npm i <library name>@next`.

该 `@latest` 标记指向该库的最后一个稳定版本。你的库用户通常应安装这个版本。npm 在他们执行以下操作时获取的就是这个版本 `npm i <library name>`.

要使 `@latest` 标记指向你最新的提交，你需要创建一个 **发布版本** ，在 GitHub 上发布你的库。

1. 打开你项目的 GitHub 页面。打开 **发布版本** 链接，位于页面右侧边栏。
2. 点击 **起草新版本**.
3. 开启 **选择标签** 为你的新版本写一个名称，例如“1.1.0”。同时在 **发布标题**上填写一个名称。通常这与版本号相同，例如“1.1.0”。

   > 重要：标签必须是数字，不能包含其他字母或符号。该数字必须高于之前已发布版本的数字。
4. 描述你的发布内容，让用户知道有哪些新内容。

   > 提示：点击按钮 **自动生成发布说明** 即可列出自上次发布以来的所有提交。
5. 点击 **发布版本**。此操作会触发一次新的自动发布到 npm，并带有 `@latest` 标记。你的库用户现在将下载这个版本。

## 可用性说明

尽你所能让你的库易于其他创作者使用。我们的假设总是会帮助塑造我们所制作的工具。很多时候，这些假设在我们看来显而易见，但处于其他语境中的人可能会有完全不同的假设。

* 为库中的一切仔细选择名称，包括函数、组件和参数。一个能够自解释的长名称，胜过一个令人完全摸不着头脑的短名称。
* 广泛思考你的库可能的不同使用场景。也许有人会在智能可穿戴设备中使用你的库，也许有人需要在某些时候开启或关闭你的系统，也许有人需要在同一个场景中添加你系统的多个实例。并不是每个人都会面临与你相同的挑战。
* 话虽如此，你不需要支持所有可能的使用场景。事实上，在灵活性与易用性之间总是需要权衡，打造好工具的关键就在于找到合适的平衡。要有策略地决定你不支持哪些内容，以及界限画在哪里。不过，清晰地记录你决定采用的限制条件也很重要。
* 这就引出了文档。请清晰地为你的库编写文档，包含示例、每个参数的作用说明、哪些场景不适用的说明，以及你对其使用环境所做的假设。库的 README.md 通常是展示这些内容的最佳位置。
* 另一个很棒的方法是直接在代码中添加元数据注释。当你的库用户输入时，IDE（如 VS Studio Code）会显示这些注释。你可以描述每个函数/组件的用途，描述每个参数期望接收什么，以及函数返回什么。得益于此，你的库用户无需在代码和文档之间切换，一切都集中在一个地方！例如，看看来自以下库的这个函数： `@dcl/ecs-scene-utils` 库：

  ```ts
  /**
   * 将某个值限制在不超过最小值或最大值的范围内。
   *
   * @param value - 输入数字
   * @param min - 最小输出值。
   * @param max - 最大输出值。
   * @returns 最终映射到 min 和 max 之间的结果值
   * @public
   */
  export function clamp(value: number, min: number, max: number) {
  	let result = value

  	if (value > max) {
  		result = max
  	} else if (value < min) {
  		result = min
  	}
  	return result
  }
  ```

  该库的用户在输入时会看到这些提示显示为 `clamp()` 函数：
* 始终声明类型。不要让人去猜测他们将要使用的对象结构。
* 让你的库保持轻量，并专注于单一功能。当一个 Decentraland 场景被编译时，它所使用的所有库中的所有代码都会被打包进去，甚至包括场景从未调用过的代码。因此，最好避免创建庞大臃肿的库。更好的做法是使用精简的库，让创作者只使用他们真正需要的部分。
* 留意你的库仓库，别人可能会提交拉取请求或报告问题。
* 在你的仓库中包含许可证信息，这样别人就知道他们是否可以自由使用你的库。默认库包含一个开放的 Apache 2 许可证，如果你愿意，随时可以更改它。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ku/create-libraries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.