XCEngine/docs/plan/Editor重构3.26.md

Editor重构 3.26

当前判断

截至 2026-03-26，Editor 的 UI 架构重构如果只计算“架构层整理”，不计算 Viewport/RHI 和 Scene/Game 真正内容开发，整体进度大约在 92%。

如果把“编辑器整体可用度”也算进去，则大约在 65% 左右，因为 Scene / Game 面板目前仍然只是占位壳，Viewport 仍未回归，且部分编辑语义与回归验证还未补齐。

已完成的架构层

1. UI 主题与样式 Token 层

已将大量直接散落在 panel 中的颜色、间距、控件尺寸、Dock 外观收口到统一 UI 基础层。

当前主要入口：

• editor/src/UI/BaseTheme.h
• editor/src/UI/StyleTokens.h
• editor/src/UI/DockHostStyle.h
• editor/src/UI/PanelChrome.h
• editor/src/UI/Core.h
• editor/src/UI/Widgets.h
• editor/src/UI/PopupState.h
• editor/src/UI/PropertyGrid.h
• editor/src/UI/UI.h

这一层的意义是：

• 主题值不再零散写在各个 panel 里
• panel chrome、toolbar、popup、property row、asset tile 等基础外观开始统一
• 后续继续调 UI 观感时，优先改 shared layer，而不是到处修 panel

2. 面板共享控件层

已抽出并统一了：

• toolbar 搜索框
• toolbar 按钮 / 切换按钮
• 空状态绘制
• 面包屑
• hierarchy tree node
• asset tile
• deferred popup / modal state
• inline text edit state
• inspector component section
• dialog action row
• property grid / scalar / vector 控件

当前结果是 Hierarchy / Project / Inspector / Console / MenuBar 的基础表现逻辑已经大面积转向 shared widget，而不是每个 panel 手搓一遍。

3. Command 层

已经从 panel 中抽出了大部分直接业务操作，形成内部命令层：

• editor/src/Commands/SceneCommands.h
• editor/src/Commands/EntityCommands.h
• editor/src/Commands/ProjectCommands.h
• editor/src/Commands/ComponentCommands.h

当前已进入 command 的行为包括：

• 新建 / 打开 / 保存场景
• 启动场景加载与退出时脏场景保存
• 创建 / 复制 / 粘贴 / Duplicate / 删除 / 重命名 / 重挂接实体
• 创建文件夹、删除资源、打开资源、移动资源
• 添加 / 移除组件

这一层已经把大量 undo / dirty / selection reset / scene switch confirm 从 panel 中剥离出来。

4. Action / Shortcut 层

这一层是 3.26 新补上的，用于承接：

• 文案
• shortcut 文本
• enabled 状态
• 文本输入时是否允许触发
• shortcut 触发上下文
• menu 与 shortcut 的统一绑定
• button / toolbar / inspector action 的统一接线

当前文件：

• editor/src/Actions/ActionBinding.h
• editor/src/Actions/EditorActions.h

已覆盖的区域：

• MenuBar
• Hierarchy
• Project
• Inspector
• Console

这一层已经不再只是 MenuBar + Hierarchy 的试点，而是开始成为 editor 范围内的统一动作定义入口。

当前新增结果：

• 已补 shared shortcut context
• Global 与 FocusedWindow 两种快捷键路由开始统一
• Hierarchy 与 Project 已接入同一套 shortcut 分发
• 已补 active action route
• MenuBar Edit 已开始跟随 Hierarchy / Project 切换动作目标
• Rename 这类依赖 panel 内联状态的动作，开始通过 EventBus 请求而不是直接耦合 panel 实现
• Edit 动作解析与菜单绘制 / shortcut 分发已开始从 MenuBar 抽成共享 router
• Hierarchy / Project 的上下文菜单与创建弹窗也开始下沉到 shared action router
• Project 右键菜单目标已不再依赖 panel 内裸索引字段，而是改成 targeted popup state

5. Dock / Layout 层

Dock / Layout 已从 EditorLayer::setupDockspace() 中抽出，形成独立 layout controller：

• editor/src/Layout/DockLayoutController.h

当前已完成：

• dock host 渲染与默认布局重建从 EditorLayer 中移出
• Reset Layout 已接入真正行为
• MenuBar -> EventBus -> DockLayoutController 的事件链已经打通
• ImGui layout 已持久化到 <project>/.xceditor/imgui_layout.ini

当前仍待完成：

• 默认布局参数进一步数据化
• 更细致的 layout 状态管理

6. Panel 生命周期层

已开始把 EditorLayer 内手写的 panel 创建、context 注入、attach、detach、update、event、render 流程，收口到统一 panel collection。

当前意义是：

• EditorLayer 不再保存一串分散的 panel 生命周期样板代码
• panel 的 attach / detach / render 顺序有了统一入口
• 后续继续拆 panel 或补 panel 时，不需要再改一大片壳层代码
• startup scene / dock attach / panel tree 组装已继续从 EditorLayer 收口到 EditorWorkspace

7. Application / ImGui Session 层

Application 中原先混在一起的 ImGui context 创建、字体加载、ini 路径配置、layout 持久化，已经开始抽成独立 session：

• editor/src/UI/ImGuiSession.h
• editor/src/UI/ImGuiBackendBridge.h

这一层的意义是：

• Application 更接近窗口 / 设备 / layer host
• ImGui 生命周期不再继续堆在 Application.cpp
• Win32 / DX12 backend API 不再散落在 Application.cpp 与 main.cpp
• 后续继续清理 backend 初始化边界时，有稳定落点
• Win32 window/message pump 已抽成 Platform/Win32EditorHost.h
• DX12 swapchain / render target / present / resize 已抽成 Platform/D3D12WindowRenderer.h
• scene title 拼装已抽成 Core/EditorWindowTitle.h

主要面板状态

MenuBar

已完成：

• 文件菜单场景动作走 command
• undo / redo / copy / paste 动作开始统一
• shortcut 接入 action 层
• scene 状态显示统一
• Reset Layout 已接入事件驱动行为
• About 已接入真实 modal popup
• Exit 已通过事件驱动关闭 editor
• Edit 菜单已开始跟随 active action route 在 Hierarchy / Project 之间切换
• Edit 菜单与上下文快捷键开始共享同一套 edit action router

仍待完成：

• help / app 级动作继续向更统一的 application shell 收口

Hierarchy

已完成：

• 搜索栏、节点样式、上下文菜单、创建菜单已共享化
• 创建 / 删除 / 重命名 / 复制 / 粘贴 / Duplicate / 重挂接走 command
• 快捷键已接 action 层
• 重命名状态已收成 Begin / Commit / Cancel
• 重命名交互已从 panel 局部字段收口到 shared inline edit state
• Rename 请求已能从 MenuBar -> EventBus -> Hierarchy inline edit 触发

仍待完成：

• 拖拽 / 空白区域目标等细节继续统一

Project

已完成：

• toolbar、breadcrumb、search、asset grid、empty state 已共享化
• 打开资源、删除资源、创建文件夹、拖拽移动走 command
• 上下文菜单、返回按钮、创建文件夹对话框已接 action 层
• 资源图标绘制与图标配色已下沉到 shared UI token / widget
• 创建文件夹弹窗已改成 shared popup state 驱动
• Back / Open / Delete 已接 panel-focused keyboard action

仍待完成：

• 更多资源对话框 / 多选语义继续统一

Inspector

已完成：

• component section 已共享化
• Add Component 已放到底部
• 组件增删已走 command
• 组件内容编辑大部分已走 property grid
• Add Component 按钮与 popup 项已接 action 层
• Add Component popup 已接 shared popup state

仍待完成：

• section header 的动作继续统一
• 组件编辑交互与 undo 提交边界继续收口

Console

已完成：

• 工具栏与内容区布局已共享化
• 日志行 hover 表现已统一
• Clear / Filter 已接 action 层
• console filter 状态已从 panel 裸布尔字段收成独立 state object

仍待完成：

• 控制台状态与动作定义继续统一

Scene / Game

当前状态：

• 只保留空壳 panel
• 暂时不做内容

这符合当前阶段决策，因为 Viewport 依赖的 RHI 模块仍在重构中。

还未完成的架构事项

高优先级

1. 整理 Application.cpp 和 EditorLayer.cpp 中剩余的 UI 壳逻辑
   包括 backend 初始化边界、主循环中剩余 ImGui / render 壳逻辑、部分样式 push / pop 的收口。

中优先级

2. 继续将 panel 的本地状态机抽离
   包括：

   • console filter state
   • 其他仍散落在 panel 内的临时交互状态

3. 将剩余少量视觉硬编码继续下沉到 token / widget 层
   尤其是 ProjectPanel 中的 icon color 和一部分 panel 局部尺寸。

4. 统一 editor 范围内的编辑语义
   例如：

   • 哪些 panel 消费 Copy / Paste / Delete / Open / Back
   • 哪些动作受 selection 驱动
   • 哪些动作在文本输入时必须屏蔽
   • 哪些动作通过 command，哪些动作通过 event 请求 panel 内联状态

低优先级

5. 再整理一次目录边界
   当前 UI / Commands / Actions / Layout 方向是对的，但后续还可以再决定哪些继续 header-only，哪些拆 .cpp 更合适。

6. 补一份更正式的 editor 架构说明
   说明 panel、actions、commands、layout、managers 的职责边界，便于后续继续迭代。

7. 根据条件补最小回归测试或最小验证脚本
   重点验证 shortcut、undo、scene dirty/save switch、drag-drop/reparent。

下一阶段建议执行顺序

第一阶段

1. 清理 Application + EditorLayer UI 壳层
2. 清理 panel 内剩余局部状态逻辑

第二阶段

3. 收口剩余视觉硬编码
4. 统一 editor 范围内的编辑语义

第三阶段

5. 根据需要继续细分 Actions / Commands / Layout 的目录边界
6. 补最小回归验证
7. 为 Viewport 回归预留 editor shell 接口

阶段性结论

当前 editor 重构已经从“到处修视觉 bug”切换到了“逐层收口架构”的状态，方向是正确的。

最关键的变化不是某个 panel 看起来更像 Unity，而是已经开始形成稳定分层：

• UI 负责外观与共享控件
• Actions 负责动作定义与 shortcut / button 绑定
• Commands 负责编辑器业务行为
• Layout 负责 dock host 与默认布局
• Panels 逐步退化为纯 UI 壳

只要继续沿这个方向收口，后面再做 Scene/Game 接入、Viewport 回归时，成本会明显低于继续在 panel 内部堆逻辑。