XCEngine/docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md

XCUI NewEditor主线重建计划

日期：2026-04-07

1. 文档定位

本文档用于收口 XCUI / XCEditor / new_editor 当前阶段的真实执行主线。

它不是重复定义 XCUI 全部架构，而是把“接下来到底怎么做”重新拍板，并覆盖之前已经不再成立的执行假设。

本文档与现有文档的关系如下：

• docs/plan/XCUI完整架构设计与执行计划.md
  • 继续作为 XCUI 总体架构与三层设计的总纲参考。
• 本文档
  • 作为 new_editor 主线重建的最新执行计划。
  • 优先级高于旧的阶段状态快照与旧执行顺序说明。

---

2. 当前拍板结论

当前必须明确以下结论，并作为后续开发硬约束：

2.1 旧 editor/ 不再作为 XCUI 替换目标

• editor/ 当前 ImGui 版本继续保留。
• 它是参考实现、行为对照和视觉基线来源。
• 当前阶段不再把主要精力放在“把 XCEditor 回填进旧 editor/ 并替掉 ImGui”这条路线。

2.2 new_editor/ 是未来正式编辑器主线

• new_editor/ 不再只是临时名字上的沙盒。
• 它应被视为未来正式编辑器的新主线工作区。
• 后续真正重建编辑器时，应以 new_editor/ 为宿主和产品主线，而不是回头改旧 editor/。

2.3 tests/UI 仍然是基础层唯一实验场

• tests/UI/Core 只验证 Core 共享能力。
• tests/UI/Editor 只验证 Editor 基础层能力。
• tests/UI/Runtime 只验证 Runtime 层能力。
• 所有基础层验证、交互试验、截图检查，都优先放在 tests/UI。

2.4 new_editor/ 当前不承担“实验面板堆场”

• new_editor/ 当前只承载：
  • XCEditor 基础层库
  • new_editor 的真实宿主与产品装配代码
• 在 Editor 基础层收口前，禁止把 new_editor/ 继续做成杂乱的试验场或验证面板集合。
• 需要人工操作检查的内容，仍然通过 tests/UI/*/integration 提供。

2.5 当前主线优先级是 Editor，不是 Runtime

• Runtime 继续按三层设计保留，但不是当前最高优先级。
• 当前最高优先级是先把 UI Core + UI Editor 做成熟，并让其具备支撑 new_editor 正式重建的能力。

2.6 Editor 视觉基线以旧 editor/ 为准

• XCEditor 当前默认视觉还没有达到旧 editor/ 的程度。
• 后续 Editor UI 的默认主题、控件密度、边框、分隔线、状态反馈强度，都要以旧 editor/ 现有风格为基线。
• 目标不是做一套“看起来差不多的深色 UI”，而是做出可以承载当前编辑器产品感的正式 Editor 风格。

---

3. 三层边界再次确认

3.1 Core

Core 负责：

• retained-mode UI 运行机制
• layout / input / focus / scroll / popup / text / render contract
• theme / token / style resolve 的通用机制
• 与 Editor / Runtime 都共享的基础能力

Core 不负责：

• Editor 风格语义
• Runtime screen/player 宿主策略
• 业务面板

3.2 Runtime

Runtime 负责：

• game UI 的 screen / layer / player / system
• runtime 输入路由、阻塞、导航、menu/hud/modal 语义
• 面向游戏开发者的运行时宿主层

Runtime 不负责：

• Editor 专用控件
• Editor 默认风格
• 新编辑器重建主线

3.3 Editor

Editor 负责：

• editor-only widget
• editor-only shell / dock / workspace / panel session / viewport shell
• editor 风格语义
• 默认 editor theme token 与资源化样式体系

Editor 不负责：

• 旧 editor/ 的就地替换
• 直接承担游戏 Runtime UI

---

4. 当前状态评估

4.1 已有基础

当前 XCEditor 已经具备以下基础：

• shell 级模型与状态骨架：
  • workspace
  • dock host
  • panel registry
  • panel lifecycle
  • layout persistence
  • shortcut / command 基础路径
• editor 常用基础件：
  • menu bar / popup / context menu
  • tab strip
  • tree view / list view
  • scroll view
  • property grid
  • viewport shell / viewport slot
  • bool / number / enum field
• tests/UI/Editor 已形成 unit + integration 的基础验证体系。

结论：

• XCEditor 已经不是 demo 级玩具。
• 它已经具备继续作为 new_editor 底座推进的资格。

4.2 当前最突出的缺口

当前离“可正式支撑 new_editor 重建”的差距主要在以下几点：

4.2.1 Editor 默认样式资源层太薄

• 当前 .xctheme 只能控制少量颜色、spacing、radius。
• 远不足以承载旧 editor 那种完整的产品级视觉体系。
• 目前很多控件仍然只是在通用深色皮肤上运行，不是正式 Editor 风格。

4.2.2 Widget 视觉参数仍未充分资源化

• 仍有大量 palette / metrics / font size / rounding / inset 硬编码在 C++ 里。
• 这会导致 .xctheme 只能“改一点颜色”，无法真正控制 Editor 外观。

4.2.3 视觉基线还未对齐旧 editor

• 当前 widget 默认密度偏松。
• 圆角偏大。
• 行高偏高。
• 分隔线与层级关系不够清晰。
• 菜单栏、面板框架、属性行、tab 等视觉结构还没有贴近旧 editor。

4.2.4 仍缺少若干 Editor 通用字段件与高级能力

• TextField
• Vector2Field
• Vector3Field
• Vector4Field
• ColorField
• 后续可扩展的 AssetField / ObjectField

4.2.5 collection / shell 高级能力还未收口

• multi-selection
• inline rename
• drag/drop contract
• virtualization
• icon / glyph 统一语义
• 更完整的 toolbar / status / shell chrome 体系

---

5. 当前阶段硬规则

5.1 先做基础层，不提前做业务面板

在 Editor 基础层完成收口前：

• 不开始复刻 Hierarchy / Inspector / Console / Project 这些完整业务面板。
• 只允许做承载这些面板将来必需的通用 Editor 基础件。

5.2 Core 能力缺口必须先回补 Core

凡是发现缺的是：

• layout
• input
• focus
• popup
• text
• render contract
• shared widget primitive

都必须优先回补到 Core 或 shared 层，而不是在 Editor 层写临时绕过实现。

5.3 Editor 风格必须资源化，但语义归 Editor 层管理

• 样式机制归 Core
• Editor 默认风格语义归 Editor
• 颜色 / spacing / radius / border / density / typography 应尽量走资源化 token
• 控件行为与结构语义仍由 Editor 代码层控制

5.4 new_editor/ 只做正式产品装配，不做测试堆场

• 验证入口继续放在 tests/UI
• new_editor/ 只保留未来正式编辑器真正需要的宿主、装配、资源与业务层结构

---

6. Editor基础层完成标准

只有当以下条件基本满足后，才允许进入 new_editor 业务面板重建阶段：

6.1 视觉与样式层

• 已建立足够厚的 Editor token 体系
• widget 的 palette / metrics 基本完成 theme 驱动
• menu / popup / tab / panel / property / list / tree / status / scrollbar / splitter 都已接入 Editor 主题
• 新主题能稳定逼近旧 editor 的视觉基线

6.2 字段件层

• BoolField / NumberField / EnumField / TextField / Vector2/3/4Field / ColorField 可稳定使用
• PropertyGrid 能复用这些字段件，而不是自己硬画假控件

6.3 collection / shell 层

• tree / list / tab / popup / scroll / dock / workspace 都具备稳定基础交互
• keyboard / focus / shortcut / popup / panel session 契约稳定
• 关键状态机已通过 unit

6.4 验证层

• 每个重要基础件都有对应 unit
• 每个重要交互点都有对应 integration exe
• 截图检查链路可用
• 中文操作指示和检查重点明确

---

7. 分阶段执行计划

Phase A：Editor主题系统重构

目标

把 Editor 当前“薄主题 + 硬编码 widget 视觉”的状态，重构为“厚 token + 统一默认 Editor Theme”。

任务

• 定义 Editor 主题 token 命名规范。
• 覆盖以下语义槽位：
  • workspace
  • panel
  • header
  • footer
  • menu bar
  • popup
  • tab
  • property row
  • field label/value
  • status bar
  • splitter
  • scrollbar
  • selection / hover / active / focus
• 把现有 widget 中的默认 palette / metrics 尽量迁出为 Editor theme 可控项。
• 建立“旧 editor 风格对齐”的基准场景与截图检查。

完成标准

• 主题资源文件已足够控制主要 Editor 视觉。
• 修改主题时，不再需要频繁改 widget 绘制代码。

Phase B：字段件体系补齐

目标

补齐 Editor 通用字段件，为后续 Inspector / 面板表单重建打基础。

任务

• 正式完成 TextField
• 完成 Vector2Field
• 完成 Vector3Field
• 完成 Vector4Field
• 完成 ColorField
• 视需要评估 AssetField / ObjectField 的基础契约
• 让 PropertyGrid 正式承接这些字段件

完成标准

• PropertyGrid 不再停留在基础标量字段件阶段。
• 复合字段件已有完整 unit + integration。

当前检查点（2026-04-08）

• TextField 已完成正式接入：
  • XCEditor 已提供 UIEditorTextField 与 UIEditorTextFieldInteraction
  • UIEditorTheme 已补齐 TextField theme resolver 与 hosted builder
  • PropertyGrid 的 Text 行已切到正式 TextField 复用链路
• Vector2Field 已完成第一批复合字段件接入：
  • XCEditor 已提供 UIEditorVector2Field 与 UIEditorVector2FieldInteraction
  • UIEditorTheme 已补齐 Vector2Field theme resolver 与 hosted builder
  • tests/UI/Editor 已补齐 Vector2Field 的 layout / hit-test / interaction / theme 单测
  • editor_ui_vector2_field_basic_validation 已可编译、运行、自动截图，并已接入 editor_ui_integration_tests
• 当前 tests/UI/Editor 中，这两批字段件都遵守同一条验证规范：
  • 顶部必须明确写“这个测试验证什么功能”
  • 试验面板只放当前批次要检查的控件
  • 保持 Unity 向黑白灰风格，不把业务面板塞进 new_editor
• 因此 Phase B 当前已正式完成前两项：
  1. TextField
  2. Vector2Field
• 下一批主线顺序固定为：
  1. Vector3Field
  2. Vector4Field
  3. ColorField

Phase C：Collection与交互高级能力收口

目标

让 tree/list/tab/menu/property 进入可长期复用的 Editor 基础件水平。

任务

• multi-selection
• inline rename/edit session
• drag/drop contract
• virtualization 基础设计与第一轮实现
• icon / glyph / disclosure / dropdown indicator 统一语义
• collection 与 keyboard navigation/focus 的进一步收口

完成标准

• collection 控件不再只是演示级原型。
• 已具备支撑真实 editor 面板的核心交互能力。

Phase D：Shell与Workspace正式收口

目标

把 shell 基础层从“能演示”推进到“可作为新编辑器外壳底座”。

任务

• menu bar / popup / context menu 视觉与交互对齐旧 editor 基线
• panel frame / status bar / tab strip / dock host 进一步主题化和结构收口
• workspace session / panel lifecycle / shortcut / command / layout persistence 继续补齐
• viewport shell / viewport input bridge 与 Editor shell 契约继续稳定

完成标准

• shell 基础层达到可承载空业务编辑器外壳的程度。

Phase E：new_editor 空壳正式接管

目标

在不引入具体业务面板的前提下，让 new_editor 正式使用 XCEditor 搭建空编辑器壳层。

任务

• new_editor 中装配：
  • 主菜单壳层
  • 工具栏占位
  • workspace / dock 壳层
  • status bar
  • viewport shell 占位
• 保持业务内容为空或极简占位，不提前混入具体面板逻辑。

完成标准

• new_editor 具备“正式产品空壳”形态。
• 旧 editor/ 继续只承担参考作用。

Phase F：业务面板分批重建

前置条件

只有在 Phase A 到 Phase E 基本完成后，才进入本阶段。

执行原则

• 以旧 editor/ 为行为和视觉参考
• 以 new_editor/ 为正式宿主
• 业务面板按独立垂直切片逐个迁入

候选顺序

• Inspector 基础表单链路
• Hierarchy
• Console
• Project
• Scene/Game 相关工具壳层

---

8. 测试与验收规则

8.1 Core 能力进 tests/UI/Core

凡是共享能力，一律在 tests/UI/Core 验证：

• popup overlay primitive
• scroll / focus / keyboard navigation
• text input / style resolve / layout

8.2 Editor-only 能力进 tests/UI/Editor

凡是 editor-only，一律在 tests/UI/Editor 验证：

• field widgets
• property grid
• menu / popup / tab / dock / workspace
• shell state / panel lifecycle / viewport shell

8.3 new_editor 不承担测试职责

• new_editor 只做产品集成冒烟检查
• 不把验证场景继续塞到 new_editor 里

8.4 每批次收口要求

每推进一个 Editor 基础件批次，至少必须完成：

• 对应 unit
• 对应 integration exe
• 人工截图检查
• 风格与交互结论记录

---

9. 与其它计划的关系

9.1 继续有效的文档

• docs/plan/XCUI完整架构设计与执行计划.md
  • 继续作为 XCUI 总体架构总纲
• docs/plan/Material Inspector与Shader属性面板收口计划_2026-04-07.md
  • 继续作为未来业务层计划保留
  • 但执行前提是本计划中的 Editor 基础层先收口

9.2 已被覆盖的旧结论

以下旧结论不再作为当前主线执行依据：

• “后续主要目标是把 XCUI 直接嵌回旧 editor/ 并替掉 ImGui”
• “new_editor/ 长期只作为临时沙盒存在”
• “可以在 new_editor/ 中继续堆各类试验面板作为主验证入口”

---

补充归档结论：

• docs/plan/used/XCUI_Phase_Status_2026-04-05.md 已转入归档，不再作为当前主线执行依据。

10. 当前结论

当前最重要的不是立刻复刻旧 editor 的具体业务面板，而是先把：

• UI Core
• UI Editor
• new_editor 正式宿主边界

这三者之间的职责彻底做对。

正确路径是：

1. 继续在 tests/UI 中把基础层做成熟
2. 以旧 editor/ 为风格与行为参考
3. 以 new_editor/ 为未来正式编辑器主线
4. 待基础层达标后，再进入业务面板分批重建

这条路线比“直接替换旧 editor 中的 ImGui”风险更低，也更符合当前工程实际。