> 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，你仍然可以继续用代码编辑。
## 打开它
使用 **2D** / **3D** 切换位于编辑器左侧面板顶部。 **3D** 就是你已经熟悉的场景画布。 **2D** 就是 UI 编辑器。
{% hint style="warning" %}
**📔 注**：UI 编辑器需要 `@dcl/sdk` 你的场景中版本 7.26.0 或更新版本。对于较旧的场景， **2D** 选项卡会显示 **UI 编辑器不可用** 提示，而不是画布，并带有一个 **更新 SDK** 按钮，可为你升级场景，还有一个 **也许稍后** 按钮用于将其关闭。
{% endhint %}
Creator Hub 会记住你离开某个场景时处于 2D 还是 3D，并以相同方式重新打开它。此设置按项目保存，绝不会随你的场景一起发布。
如果你正在使用 Bevy 场景渲染器，切换到 **2D** 会暂停正在运行的场景，而切回 **3D** 则会在之前正在运行的情况下恢复它。
## 制作你的第一个 UI
1. 切换到 **2D** 选项卡。
2. 点击 **新建 GUI**，无论是空画布中央的按钮，还是 **+** 旁边的 **GUIs** 左侧面板中的按钮。GUI 是一个 UI 组件，存储在自己的文件中。
3. 从底部的部件库中拖一个小部件到画布上。 **全屏** 是一个很好的第一个小部件，它会给你一个覆盖整个屏幕的根节点。然后把其他小部件放到它里面。
4. 选中一个小部件，并在右侧面板中设置其属性。
没有保存按钮。编辑器会在你操作时将更改写入磁盘，而工具栏左侧的徽标会显示 **所有更改已保存**.
## 这些面板
* **左侧**: **GUIs**，你的 UI 组件列表，以及 **Nodes**，所选项的树状结构。搜索框可同时筛选两者。将鼠标悬停在某个节点上可将其锁定、隐藏或删除。
* **右侧**：一个 **Properties** 选项卡，用于显示所选节点，以及一个 **Logic** 选项卡。
* **底部**：小部件库。将一张卡片拖到画布上即可添加。
* **中间**：画布。拖动节点可移动它们，使用手柄可调整大小，也可用鼠标滚轮或拖拽自由平移。
画布右下角有两组浮动控件：
* 该 **预览** 组可切换移动端 HUD 指引和安全区域指引，并在以下模式间切换 **桌面预览** 和 **移动端预览**.
* 该 **缩放** 组包含减号和加号按钮，以及一个百分比输入框。点击百分比即可输入 10 到 200 之间的精确缩放值，然后按 Enter 或点击其他位置应用，或按 Escape 取消。当缩放达到 200% 时，加号按钮会失效。
## 小部件
该部件库将小部件分为三类：
* **容器**: **全屏**, **容器**, **图像**
* **文本**: **标签**, **按钮**
* **输入框**: **输入框**, **下拉框**
**全屏** 是一种容器，会填满它被放置到的任何位置，因此很适合作为覆盖整个屏幕的 UI 的起点。
## 移动和调整大小
工具栏有三种工具模式：
* **自由**：移动和调整大小，通用模式。
* **移动**：仅拖动。
* **调整大小**：仅手柄。
位置会吸附到 10 像素网格。拖动时按住 **Shift** 可忽略网格自由移动。工具按钮旁边的小箭头会打开一个 **吸附** 复选框，可完全关闭吸附。
## 布局：流式与自由定位
有两个独立属性决定节点最终的位置。搞清楚它们可以省去很多困惑。
**Flow** 设置在 **容器** 上，并决定它如何排列其子节点：
* **自由**：子节点会停留在你放置它们的位置。
* **行** / **行反向**：子节点从左到右或从右到左排列。
* **列** / **列反向**：子节点从上到下或从下到上堆叠。
* **换行子节点**：当子节点放不下时，可让它们换到多行。
**忽略布局流** 设置在 **子节点** 并决定该节点是否脱离其父级的排列。关闭时，由父级定位它。开启时，你可以用 Anchor 和 Position 值自己固定它。
由此会带来两个结果：
* 将小部件拖入 **自由** 容器中，它就会停留在你放下它的位置。
* 将它拖入带有方向的容器，它就会加入流式布局，排入队列中。
将容器切换为 **自由** 会将其现有子节点固定在当前所在位置，因此不会发生跳动。
GUI 的根节点始终以自由方式定位。
## 其他值得了解的属性
* **不透明度**：100% 表示完全不透明，0% 表示完全透明。默认值为 100%。
* **场景内嵌**：GUI 所处的屏幕区域。
* **全屏** 使用整个可渲染屏幕。
* **可交互安全区域** 会避开客户端自身的界面，例如聊天、小地图和 HUD 指示器。
* **设备安全区域** 还会避开物理遮挡，例如刘海屏或系统栏。此选项在画布处于移动端预览时提供。
在编辑器写入的代码中，这三种选择会变成 `screenInset: 'none'`, `'interactable'` 和 `'device'`。参见 [屏幕内嵌区域](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#screen-inset-area).
如果你给 GUI 的根节点设置了固定像素宽度和高度，画布会将其框成一个恰好该尺寸的画板，而不是屏幕。
## 在手机上检查你的 UI
画布右下角的控件可在桌面屏幕和手机之间切换预览。在移动端预览中，画布会绘制在带有刘海的手机框中，这样你就能看到屏幕边缘实际落在哪里。
两组指引可帮助你把东西放在玩家看得到、够得到的位置：
* **安全区域指引** 勾勒出你的 GUI 所受限制的屏幕部分，与 **场景内嵌** 你选择的设置相匹配。当场景内嵌为 **设备安全区域** 或 **可交互安全区域** 时，轮廓始终开启，因为 GUI 会被裁剪到这里。将场景内嵌设置为 **全屏** ，你就可以用框架图标按钮打开或关闭轮廓。
* **HUD 指引** 会绘制移动端客户端自身的控件，例如摇杆、跳跃和动作按钮、表情轮盘、个人资料、聊天和指南针。它们仅供参考，你不能选择或移动它们。手柄按钮可将其打开或关闭，它只会在移动端预览中出现，并且当场景内嵌为安全区域时，这些指引默认显示。
放置在安全区域外的内容不会被隐藏，而是会绘制到轮廓之外。这个溢出就是警告：在真实客户端中，它会位于游戏自己的 HUD 下面。
**可交互安全区域** 会清除移动端客户端左侧的一列控件，但它的右边缘与设备区域共享，因此右下角的动作按钮会按设计绘制在其上方。请保持这些角落空出。参见 [客户端控制所在位置](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/safe-area.md#where-the-client-controls-live).
{% hint style="warning" %}
**📔 注**：这些指引只是编辑器内的近似值。真实区域由客户端在运行时报告，并且因设备而异，因此务必在真机上确认。参见 [移动端预览](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/preview-on-mobile.md).
{% endhint %}
## 自定义移动端控制
在移动客户端中，玩家通过一组原生屏幕控件进行移动和操作：摇杆、准星，以及一排动作按钮。 **MobileHUD** 条目可让你无需编写代码就重新塑造该 HUD，并在操作过程中将结果显示在画布上。
一旦你的场景至少有一个 GUI， **MobileHUD** 会作为 **GUIs** 列表中的第一行出现，位于你自己的 GUI 之上。选择它即可在右侧打开其面板。
顶部的三个复选框可隐藏 HUD 的整部分内容：
* **隐藏摇杆**：移除移动摇杆。
* **隐藏准星**：移除瞄准准星。
* **隐藏输入动作**：一次移除所有动作按钮。
在它们下面， **输入动作** 部分按屏幕槽位填充的顺序列出这八个按钮：
| 动作 | 屏幕上的按钮 |
| --------------------------------------- | ---------- |
| `IA_JUMP` | 中央的大按钮，默认是 |
| `IA_POINTER` | 交互按钮 |
| `IA_PRIMARY (E)` | E 按钮 |
| `IA_SECONDARY (F)` | F 按钮 |
| `IA_ACTION_3 (1)` 设置为 `IA_ACTION_6 (4)` | 带数字的按钮 |
每一行提供三项内容：
* **主按钮**：一个单选按钮，将该动作设为中央的大按钮。 `IA_JUMP` 默认是主按钮，同时只能有一个动作处于主按钮状态。
* 一个 **眼睛图标** ，用于显示或隐藏该按钮。隐藏一个按钮后，下面的按钮会向上移动以填补空位。
* **自定义图标**：将按钮的图形替换为场景中的 `.png`, `.jpg` 或 `.jpeg` 图像。
默认情况下没有任何内容被隐藏，并且 `IA_JUMP` 是主按钮，这正是没有修改 HUD 的场景中玩家会得到的样子。
{% hint style="info" %}
**💡 提示**：带数字的按钮通常位于“+”溢出切换按钮后面。隐藏足够多的上方按钮后，它们会直接显示。参见 [屏幕控制](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md#how-the-button-layout-works) 了解这些槽位如何填充。
{% endhint %}
### 它写入的文件
你的更改会写入 `src/mobile-hud.ts`，它导出一个 `setupMobileHud()` 函数，基于 SDK 的 [`TouchScreenControls`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md) 组件：
```ts
import { engine, InputAction, TouchScreenControls } from '@dcl/sdk/ecs'
export function setupMobileHud() {
TouchScreenControls.createOrReplace(engine.RootEntity, {
hideJoystick: true,
hideCrosshair: false,
mainAction: InputAction.IA_PRIMARY,
touchInputs: [
{ inputAction: InputAction.IA_ACTION_3, hide: true },
],
})
}
```
编辑器还会将导入和调用添加到你的 `src/index.ts`:
```ts
import { setupMobileHud } from './mobile-hud'
setupMobileHud()
```
该文件只会在它还有内容可说时存在。如果你把所有内容都改回默认值，或者删除最后一个 GUI，Creator Hub 就会删除 `src/mobile-hud.ts` 并再次移除这两行。
{% hint style="warning" %}
**📔 注**：当 **MobileHUD** 被选中时，小部件库会被禁用，预览控件会被隐藏，因为此时没有可放置的内容，而且 HUD 仅适用于移动端。选择你自己的某个 GUI 即可让它们重新出现。
{% endhint %}
## 文件存放位置
UI 编辑器会直接编辑你场景中的真实源文件。没有单独的保存格式。
* 每个 GUI 对应一个 `.tsx` 文件，位于 `src/ui/`.
* `src/ui/index.tsx` 由编辑器生成，用于将它们汇总在一起。不要手动编辑它。
* `src/mobile-hud.ts` 保存你的 [移动端控制](#customize-the-mobile-controls)，如果你做了任何更改。它特意放在 `src/ui/` 之外，因此永远不会被当作 GUI 处理。
如果你的场景里有一个旧的单一 `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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/gou-jian/ui-editor.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
