6.5 KiB
6.5 KiB
UI
命名空间: XCEngine::Editor::UI
类型: submodule
描述: 编辑器基于 Dear ImGui 的 UI 基础设施层，负责会话、主题 token、面板 chrome、树视图、属性布局和通用控件封装。
概述
XCEngine::Editor::UI 不是单个 widget 库，而是一组逐层叠加的编辑器 UI 基建。它的目标是把 Dear ImGui 这种非常自由、非常底层的即时模式 API 收束成一套可维护的“编辑器内建控件层”。
当前源码里，这一层大致可以分成四层：
- 会话与后端层 负责 ImGui 上下文、ini 持久化、后端桥接和纹理描述符分配。
- 主题与设计 token 层 负责颜色、尺寸、间距、dock host 风格与常用视觉常量。
- chrome 与布局层 负责面板窗口、工具栏、树视图、splitter、divider、属性行布局和自定义 dock 标签栏。
- 语义化控件层 负责属性网格、资产卡片、面包屑、弹窗、组件折叠段和各种编辑器专用小部件。
这类分层方式非常接近商业级游戏引擎编辑器的组织方式。原因很简单：如果每个面板都直接拼原始 ImGui 调用，代码很快就会变成不可维护的样式杂糅体；而先建设统一 UI 层，后续任何面板重构、主题调整和交互升级都会容易很多。
聚合头文件
源文件: editor/src/UI/UI.h
UI.h 当前是一个标准的 umbrella header。它的职责是把 Editor UI 常用 helper 聚合到同一个入口，而不是声明新的运行时类型。
因此这页文档直接承担 UI.h 的说明职责，不再额外创建一个重复的类型页。
当前架构重点
结合当前 editor/src/UI/** 与最近一次 Editor UI 重构，以下几层是现在最值得读的核心：
ImGuiSession + ImGuiBackendBridge管理 ImGui 上下文、DPI、SRV 描述符与窗口后端对接。BaseTheme + StyleTokens + DockHostStyle管理设计 token 和 dock host 外观，是全局视觉风格的起点。Core + DividerChrome + SplitterChrome + DockTabBarChrome + PanelChrome管理窗口 chrome、底边线、拖拽分隔条与自定义 dock 标签栏。TreeView + BuiltInIcons管理层级树 / 目录树的共享节点表现与图标前缀。PropertyLayout + ScalarControls + VectorControls + PropertyGrid管理 Inspector 的属性布局、标量控件、向量控件和高层属性编辑入口。Widgets + PopupState + SceneStatusWidget + AboutEditorDialog提供更接近编辑器业务语义的通用 widget。
这次重构里，TreeView、PropertyLayout、BuiltInIcons 和 DockTabBarChrome 是最明显的新基础设施，它们共同把原先分散在具体面板中的 UI 技巧沉淀成了复用层。
设计说明
如果把它和 Unity 一类成熟编辑器对照，可以把 Editor::UI 理解成“编辑器内部控件系统”，而不是游戏运行时 UI 框架：
- 它面向工具开发，不面向游戏内 HUD。
- 它可以为编辑器体验服务而使用较强约束的 helper。
- 它允许把某些风格、布局和交互策略写死在共享层，以换取整个工具界面的统一性。
这种设计的好处是：
- 面板作者写的代码更接近业务语义，而不是样式拼装。
- 主题、间距、树视图和 Inspector 布局能在全局范围内保持一致。
- 面板之间可以共享拖拽、上下文菜单、资产卡片、树节点前缀等成熟模式。
代价也很明确：
- 当前 UI 层明显偏 Editor 私有实现，不是面向外部插件的稳定 ABI。
- 很多 helper 仍然是 header-only inline 形式，接口演化速度会比较快。
- 当前实现强依赖 Windows + D3D12 + Dear ImGui 的编辑器运行路径。
头文件
- AboutEditorDialog -
AboutEditorDialog.h，关于对话框相关 UI。 - BaseTheme -
BaseTheme.h，编辑器基础主题安装。 - BuiltInIcons -
BuiltInIcons.h，内置资源/对象图标系统。 - ConsoleFilterState -
ConsoleFilterState.h，Console 过滤状态。 - ConsoleLogFormatter -
ConsoleLogFormatter.h，Console 日志格式化。 - Core -
Core.h，底层 ImGui helper 与 popup chrome 包装。 - DividerChrome -
DividerChrome.h，统一分隔线绘制。 - DockHostStyle -
DockHostStyle.h，dock host 风格压栈。 - DockTabBarChrome -
DockTabBarChrome.h，自定义 dock 标签栏。 - ImGuiBackendBridge -
ImGuiBackendBridge.h，ImGui 与 D3D12 之间的桥接层。 - ImGuiSession -
ImGuiSession.h，ImGui 会话生命周期。 - PanelChrome -
PanelChrome.h，面板窗口 / 工具栏 / 内容区 RAII 外壳。 - PopupState -
PopupState.h，延迟弹窗与目标型弹窗状态。 - PropertyGrid -
PropertyGrid.h，Inspector 级属性编辑入口。 - PropertyLayout -
PropertyLayout.h，属性行几何布局层。 - ScalarControls -
ScalarControls.h，标量属性控件。 - SceneStatusWidget -
SceneStatusWidget.h，场景状态部件。 - SplitterChrome -
SplitterChrome.h，分隔条交互与绘制。 - StyleTokens -
StyleTokens.h，Editor UI 设计 token 中心。 - TreeView -
TreeView.h，树视图共享基础设施。 - VectorControls -
VectorControls.h，向量属性控件。 - Widgets -
Widgets.h，资产卡片、面包屑、组件折叠段等通用 widget。
当前实现边界
- 这是 Editor 应用层 UI，不是运行时
engine/include/XCEngine风格的公共引擎 API。 - 当前很多接口仍然直接暴露 ImGui 类型，如
ImDrawList、ImVec2、ImGuiID。 - 自定义 dock 标签栏、树视图和图标系统都明显面向当前编辑器产品形态，而不是通用 GUI 框架。