星火 2.0 开发文档

主题

UI 编辑器基本操作 ​

UI 编辑器用于在编辑器的真实运行时预览中查看和调整 GameUI 页面。它适合处理页面结构、控件位置和常用属性；业务逻辑、复杂交互和运行时代码仍应在项目代码中完成。

开始前 ​

  1. 用星火 2.0 编辑器打开项目。
  2. 确认项目已经有可编辑的 GameUI 页面或 UserControl。
  3. 从编辑器的 UI 编辑器入口启动预览，等待页面目录和画布加载完成。

UI 编辑器使用独立的 Workbench 窗口。编辑地形或场景时，Workbench 会保持在编辑器窗口上方，便于同时观察页面和场景。

认识 Workbench ​

Workbench 主要分为三部分：

  • 页面目录：选择要预览的 Page 或 UserControl，并切换预览页面。
  • 页面结构：显示可保存的页面层级，用于选择、添加和编辑控件。
  • 运行时检查器：显示当前运行时完整 UI 树，用于检查实际生成的控件；运行时专用节点通常是只读的。

画布显示当前页面的真实运行效果。选中控件后，可以在属性区域查看当前值，并根据控件类型进行拖动、缩放或属性修改。

选择页面和控件 ​

  1. 在页面目录中选择 Page 或 UserControl。
  2. 在页面结构中展开父控件，点击要编辑的控件。
  3. 如果画布上难以点中控件，优先从页面结构树选择；树和画布会同步当前选择。
  4. 需要检查临时生成或运行时包装节点时，切换到运行时检查器。这类节点不能直接保存为项目页面结构。

页面目录只显示页面名称。正式 Page 和 UserControl 的生命周期不同，编辑时应先确认选中了正确的页面类型。

添加控件 ​

  1. 在页面结构中选中允许包含子控件的父控件。
  2. 在工具栏的控件类型选择器中选择控件类型。
  3. 点击添加控件。
  4. 新控件创建后会加入页面结构，并自动成为当前选择对象。

如果父控件不允许添加子控件，按钮会保持可见但显示不可用原因。高级结构操作（例如在前后插入、复制、删除、对齐、分布和吸附）位于更多结构工具中。

编辑属性、移动和缩放 ​

选中页面结构中的可编辑控件后，在属性区域修改当前支持的字段。普通字段会自动提交；复杂属性组会按组提交。缺失的属性在第一次填写时会自动创建，不提供把字段恢复为“未设置”的按钮。

拖动和缩放是否可用取决于控件的布局方式和当前选择。若控件是运行时生成、只读或不支持当前布局操作，请回到页面结构选择其可保存的源控件。

编辑模式和交互模式 ​

  • 编辑模式：画布点击用于选择控件，拖动和属性修改用于编辑页面。
  • 交互模式：输入传递给页面中的游戏 UI，用于测试按钮、滚动和其他交互；结构编辑操作会暂停。

需要修改结构时切回编辑模式；需要验证实际点击效果时切到交互模式。

控件边界显示 ​

工具栏中的边界显示可以选择：

  • 结构：显示页面结构相关的边界，适合日常编辑。默认使用此模式。
  • 全部：显示所有可识别控件的边界，适合排查重叠和命中区域。
  • 关闭：隐藏非必要边界，查看接近最终效果的画面。当前选中或悬停的控件仍可定位。

撤销、重做、刷新和保存 ​

  • 使用撤销和重做回退或恢复最近一次编辑操作。移动、缩放、属性修改和结构操作应分别形成可理解的操作记录。
  • 树状态异常或页面刚刚发生结构变化时，使用刷新层级重新读取页面结构。
  • 完成修改后执行项目的正常保存流程；需要让修改进入新的运行包时，再按项目的标准生成/编译流程更新运行内容。
  • 重新加载页面或关闭预览前，如果存在未保存修改，应先保存，避免丢失当前编辑结果。

常见问题 ​

页面目录为空 ​

确认项目已打开、UI 编辑器预览已启动，并且项目中存在 Page 或 UserControl。必要时关闭当前预览后重新打开。

画布上看得到，但不能修改 ​

运行时检查器包含完整运行树，其中一部分节点只是运行时包装或生成结果。请在页面结构中选择对应的源控件；如果源控件不存在，则需要先在项目数据中创建页面结构。

新控件没有出现在游戏中 ​

先保存项目，再按项目的标准生成、编译和启动流程运行。UI 编辑器中的预览修改不会替代正式运行包的生成流程。

找不到添加控件按钮 ​

先选中页面结构中的父控件，并确认当前处于编辑模式。控件类型选择器和添加控件是主要入口；其他结构命令收在更多结构工具中。

相关文档 ​