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

# XCUI NewEditor主线重建计划

日期：2026-04-09

## 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`。
- `tests/UI` 同时也是当前 XCUI 的唯一正式验证入口。

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

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

### 2.5 Core/Runtime 可资源化，Editor 固定代码样式

- `Core / Runtime` 仍可继续推进资源化、热重载与资源驱动验证。
- `Editor` 当前默认样式、palette、metrics 与视觉语义固定在代码层，不再把 Editor 主题解析作为主线。
- workspace、panel session、状态机、命令派发、业务装配与控制器仍保留在代码层。
- 在 `Core / Editor` 基础层没有收口前，不提前在 `new_editor/` 推进业务面板。

### 2.6 当前主线优先级是 `Editor`，不是 `Runtime`

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

### 2.7 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` 不负责：

- 旧 `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 固定样式常量仍未收口

- 当前大量 Editor palette / metrics / font size / rounding / inset 仍分散在不同控件实现里。
- 问题不在于 `.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 样式固定在代码层，资源与代码边界固定

- 样式机制归 `Core`
- Editor 默认风格语义归 `Editor`
- `Core / Runtime` 可以继续使用资源化样式与热重载
- `Editor` 默认颜色 / spacing / radius / border / density / typography 固定在代码层
- 控件行为、状态机、workspace/panel session、命令派发与业务装配仍由 `Editor` 代码层控制

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

- 当前正式验证入口继续固定在 `tests/UI`
- `new_editor/` 只保留未来正式编辑器真正需要的宿主、装配、资源与业务层结构
- `new_editor/` 只做宿主装配与后续业务承载，不承担当前基础层验证入口职责

---

## 6. Editor基础层完成标准

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

### 6.1 视觉与样式层

- 已建立统一的 Editor 固定样式常量出口
- widget 的 palette / metrics 不再分散硬编码，而是通过统一代码入口收口
- 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` 当前分散的硬编码视觉常量，收口为统一的固定代码样式体系。

### 任务

- 定义统一的 Editor 样式常量与 helper 命名规范。
- 收口以下语义槽位：
  - 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 风格对齐”的基准场景与截图检查。

### 完成标准

- Editor 默认视觉不再依赖主题解析测试。
- 调整 Editor 默认样式时，改动集中在统一代码出口，而不是散落在各控件里。

## Phase B：字段件体系补齐

### 目标

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

### 任务

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

### 完成标准

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

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

- `TextField` 已完成正式接入：
  - `XCEditor` 已提供 `UIEditorTextField` 与 `UIEditorTextFieldInteraction`
  - 已补齐 `TextField` 的 hosted builder 与固定样式装配入口
  - `PropertyGrid` 的 `Text` 行已切到正式 `TextField` 复用链路
- `Vector2Field` 已完成第一批复合字段件接入：
  - `XCEditor` 已提供 `UIEditorVector2Field` 与 `UIEditorVector2FieldInteraction`
  - 已补齐 `Vector2Field` 的 hosted builder 与固定样式装配入口
  - `tests/UI/Editor` 已补齐 `Vector2Field` 的 layout / hit-test / interaction 单测
  - `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 已被覆盖的旧结论

本节即当前归档说明。仓库当前未单独维护 `docs/plan/used` 目录时，凡被本节点名覆盖的旧口径，一律视为已归档、不再执行。

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

- “后续主要目标是把 XCUI 直接嵌回旧 `editor/` 并替掉 ImGui”
- “`new_editor/` 长期只作为临时沙盒存在”
- “可以在 `new_editor/` 中继续堆各类试验面板作为主验证入口”
- “可以在 `Core / Editor` 基础层未完成前，直接进入 `new_editor` 业务面板开发”

## 10. 当前结论

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

- `UI Core`
- `UI Editor`
- `new_editor` 正式宿主边界

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

正确路径是：

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

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