> 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-bian-ji-qi/gou-jian/ui-editor.md).

# UI 编辑器

在 Creator Hub 中以可视化方式设计场景的屏幕 UI，而不是在代码中进行。

UI 编辑器让你通过将小部件拖到画布上来构建场景的屏幕界面，而不是手动编写布局代码。它会把真实文件写入你的场景中，因此你在这里制作的任何内容，都是可以继续用代码编辑的普通 SDK7 UI。

UI 编辑器是一个实验性功能，默认处于关闭状态。

## 将其打开

1. 打开设置（右上角的齿轮图标）。
2. 前往 **实验性** 选项卡中。
3. 开启 **启用 UI 编辑器**.

一个 **2D** / **3D** 切换后会出现在编辑器中。 **3D** 是你已经熟悉的场景画布。 **2D** 是 UI 编辑器。

{% hint style="warning" %}
**📔 注意**：UI 编辑器需要 `@dcl/sdk` 你的场景中使用 7.26.0 版本或更高版本。在较旧的场景中，它会显示一个 **UI 编辑器不可用** 提示，并带有一个 **更新 SDK** 按钮，可为你升级场景。
{% endhint %}

Creator Hub 会记住你离开某个场景时处于 2D 还是 3D，并以相同方式重新打开。此设置按项目保存，绝不会随你的场景一起发布。

如果你使用的是 Bevy 场景渲染器，切换到 **2D** 会暂停正在运行的场景，切换回 **3D** 如果它之前正在运行，则会恢复运行。

## 制作你的第一个 UI

1. 切换到 **2D** 选项卡中。
2. 在左侧面板中，点击 **新建 GUI**。GUI 是一个 UI 组件，存储在自己的文件中。
3. 将底部调色板中的一个小部件拖到画布上。
4. 选中它，并在右侧面板中设置其属性。

没有保存按钮。编辑器会在你编辑时将更改写入磁盘，而工具栏会显示 **所有更改已保存**.

## 这些面板

* **左侧**: **GUI**，你的 UI 组件列表，以及 **节点**，所选项的树状结构。搜索框会同时过滤两者。
* **右侧**：一个 **属性** 用于所选节点的选项卡，以及一个 **逻辑** 选项卡中。
* **底部**：小部件调色板。将卡片拖到画布上即可添加。
* **中间**：画布。拖动节点可移动它们，使用控制点可调整大小，也可以用鼠标滚轮或拖拽自由平移。 **重置视图** 会重新居中。

## 小部件

调色板将小部件分为三类：

* **容器**: **全屏**, **容器**, **图像**
* **文本**: **Label**, **按钮**
* **输入框**: **输入框**, **下拉框**

**全屏** 是一个会填满其所在空间的容器，这使它成为适合覆盖整个屏幕的 UI 的良好起点。

## 移动与调整大小

工具栏有三种工具模式：

* **自由**：移动和调整大小，通用模式。
* **移动**：仅拖动。
* **调整大小**：仅使用控制点。

位置会吸附到 10 像素网格。按住 **Shift** 拖动时可自由移动，不受网格影响。工具栏中的 **吸附** 下拉菜单可完全关闭吸附。

## 布局：流式与自由定位

有两个独立属性决定节点最终的位置。把它们弄清楚能省去很多困惑。

**流式** 设置在一个 **容器** 上，并决定它如何排列其子项：

* **自由**：子项会停留在你放置它们的位置。
* **行** / **反向行**：子项会从左到右，或从右到左排列。
* **列** / **反向列**：子项会从上到下，或从下到上堆叠。
* **自动换行子项**：当子项放不下时，可让它们换到多行。

**忽略布局流** 设置在一个 **子项** ，并决定该节点是否脱离其父级的排列。关闭时，由父级来定位它。开启时，你可以使用锚点和值位置自己固定它。

这会带来两个结果：

* 将小部件拖到一个 **自由** 容器中，它就会停留在你放下的位置。
* 将它拖到一个带有方向的容器中，它就会加入流式布局，排到队列中。

将容器切换为 **自由** 会把它现有的子项固定在当前所在位置，因此不会跳动。

GUI 的根节点始终采用自由定位。

## 其他值得了解的属性

* **不透明度**：100% 表示完全不透明，0% 表示完全透明。默认值为 100%。
* **场景内边距**：GUI 所处于屏幕的哪一部分。
  * **全屏** 使用整个可渲染屏幕。
  * **游戏安全区域** 会避开客户端自身的界面，例如聊天框、小地图和 HUD 指示器。
  * **设备安全区域** 也会避开物理遮挡，例如刘海或系统栏。此选项在画布处于移动端预览时提供。

如果你为 GUI 的根节点设置固定像素宽度和高度，画布会将其框定为恰好该尺寸的画板，而不是屏幕。

## 文件放在哪里

UI 编辑器编辑的是你场景中的真实源文件。没有单独的保存格式。

* 每个 GUI 都是一个 `.tsx` 文件，位于 `src/ui/`.
* `src/ui/index.tsx` 由编辑器生成，用于将它们汇总在一起。不要手动编辑它。

如果你的场景有一个较旧的单个 `src/ui.tsx` 文件，编辑器会在你第一次打开 UI 编辑器时将其备份为 `src/ui.tsx.bak` 。

因为这些都是普通文件，你可以随时在你的 [代码编辑器](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/overview.md) 中打开它们。查看 [UI](https://github.com/decentraland/docs/tree/main/creator/sdk7/2d-ui/README.md) 以了解底层代码的作用。

## 编辑器无法编辑的代码

编辑器只识别某一种特定形状的 UI 代码。例如，某个节点如果以其他方式编写，比如在循环或条件语句中构建，或者使用自定义组件或展开属性，它会在画布上显示为一个灰色块，并带有 **非标准，请在代码中编辑** 徽标。它的子项不会显示，你需要改为在代码中编辑它。

其余围绕它的 GUI 仍会正常工作。

## 相关页面

* [UI](https://github.com/decentraland/docs/tree/main/creator/sdk7/2d-ui/README.md)：用代码编写场景 UI。
* [与代码结合使用](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/overview.md)：在代码编辑器中打开你的场景。
* [实体和组件](/creator/content-creator-zh/chang-jing-bian-ji-qi/gou-jian/components.md)：编辑器的 3D 部分。


---

# 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-bian-ji-qi/gou-jian/ui-editor.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.