XCEngine/docs/plan/NewEditor_PropertyGridInputRoutingRefactorPlan_2026-04-23.md

NewEditor PropertyGrid Input Routing Refactor Plan

Date: 2026-04-23 Status: Planned

1. Objective

彻底解决 new_editor Inspector PropertyGrid 中由共享输入状态污染导致的交互异常，重点包括但不限于：

1. Color 字段关闭颜色选择器后首击失效、需要双击、甚至双击也无反应。
2. 不同字段类型之间切换时，前一个字段的焦点、按下态、编辑态污染后一个字段。
3. PropertyGrid 内部同样表现为“看起来都是按钮/控件”，但行为不一致，Enum、Color、Bool、Asset、Number/Text/Vector 各走各的隐式输入规则。

这次不是做症状修补，而是把 PropertyGrid 的输入架构改成单目标路由和明确所有权模型，从根上消掉这类首击被吃、状态串扰、字段间抢状态的问题。

2. Confirmed Root Cause

当前问题不是颜色选择器窗口生命周期本身导致的，而是 PropertyGrid 输入分发架构有设计缺陷。

已确认的根因如下：

1. UpdateUIEditorPropertyGridInteraction(...) 会把同一个事件依次送进多套字段处理逻辑：
   • ProcessNumberFieldEvent(...)
   • ProcessTextFieldEvent(...)
   • ProcessColorFieldEvent(...)
   • ProcessVector*FieldEvent(...)
   • ProcessAssetFieldEvent(...) 见 new_editor/src/Fields/UIEditorPropertyGridInteraction.cpp
2. Number/Text/Vector 的共享处理器内部不是只处理“当前命中的那个字段”，而是遍历所有可见字段，并把 hadFocus、focused 也视为本次事件的有效证据。
3. 共享编辑会话 editableFieldSession 会被拷入每个字段的局部交互状态，再被某个字段处理器写回全局，导致一次事件期间多个字段都可能改写共享状态。
4. pressedFieldId 是 PropertyGrid 级别的共享按下态，但多个字段处理器会在处理中途清掉它。
5. Color 字段打开颜色选择器依赖“两阶段命中”：
   • PointerButtonDown 时 pressedFieldId = 当前 color 字段
   • PointerButtonUp 时再次确认 pressedFieldId 仍然是该字段 所以它对共享按下态污染最敏感。
6. Enum 下拉菜单则不同，它在 PropertyGrid 的通用 PointerButtonUp 路径里直接根据当前命中结果 OpenPopup(...)，不依赖 Color 那套专门的 armed/确认链路，所以表面上表现更稳定。

结论是：当前 bug 的根不是 ColorPicker，而是 PropertyGrid 自身没有明确的输入 owner，导致事件广播、共享状态回写、字段局部状态和全局状态互相污染。

3. Problem Statement

当前架构同时踩中了下面几个反模式：

1. 广播式分发：一个事件被多套字段逻辑重复消费。
2. 共享可变状态：pressedFieldId、editableFieldSession、propertyGridState.focused 由多个处理器写入。
3. 旧焦点兜底：把 hadFocus、focused 这种陈旧状态当作本次点击的直接交互证据。
4. 路由和行为耦合：PropertyGrid 既负责决定事件给谁，又让字段处理器反过来改全局路由状态。
5. 字段类别缺少统一抽象：Color 和 Enum 都像“动作型控件”，但输入语义却不统一。

如果继续在现状上加特判，只会形成新的状态分叉，后面还会在 Asset、Bool、Vector、键盘导航、失焦恢复上继续炸。

4. Target End State

重构完成后，PropertyGrid 必须满足下面这些结构性约束：

1. 每个输入事件在进入字段处理前，先由 PropertyGrid 路由层解析出唯一目标。
2. 任意时刻只有一个字段拥有“按下态”。
3. 任意时刻只有一个字段拥有“活动编辑态”。
4. 任意时刻只有一个字段拥有“弹出层所有权”。
5. 字段处理器不再直接清理或重置 PropertyGrid 的共享路由状态。
6. Selection、Focus、Armed、ActiveEdit、PopupOwner 是不同概念，不能再混用。
7. Color、Enum、Bool、Asset 这类动作型字段遵循统一输入契约。
8. Number、Text、Vector2/3/4 这类内联编辑字段遵循统一输入契约。
9. 关闭颜色选择器、关闭枚举下拉、提交数值编辑、切换字段后，下一次首击必须稳定命中目标控件。

5. Architectural Decision

5.1 引入单目标路由层

PropertyGrid 必须先做一次统一 hit test 和 owner 解析，再决定这次事件只派发给谁。不能继续让每类字段都自己遍历所有字段再“看看自己是不是该处理”。

路由层需要先得到：

1. hoveredFieldId
2. hoveredPart
3. armedFieldId
4. capturedFieldId
5. activeEditFieldId
6. popupFieldId

然后按事件类型走固定路由规则：

1. PointerMove 只更新 hover，以及发给 capturedFieldId 或当前 hover 字段。
2. PointerButtonDown 只发给当前命中字段，并决定是否设置 armedFieldId / capturedFieldId。
3. PointerButtonUp 只发给 armedFieldId 或 capturedFieldId，而不是再次广播给所有字段。
4. KeyDown / TextInput 只发给 activeEditFieldId 或 popupFieldId。
5. FocusLost 由路由层统一处理清理顺序，而不是让每个字段各自猜测。

5.2 引入明确的输入所有权状态

现有状态过于粗糙，后续需要拆成下面几个正交状态：

1. gridFocused
2. hoveredFieldId
3. hoveredPart
4. armedFieldId
5. capturedFieldId
6. activeEditFieldId
7. popupFieldId
8. popupHighlightedIndex

原则：

1. selectionModel 只表示“谁被选中”。
2. gridFocused 只表示“PropertyGrid 是否拥有键盘焦点”。
3. armedFieldId 只表示“谁接收对应的抬起事件”。
4. activeEditFieldId 只表示“谁接收文本编辑和编辑提交”。
5. popupFieldId 只表示“谁拥有弹出层”。

任何字段逻辑都不应再拿 selected == true 或 focused == true 推断“这次点击就是我的”。

5.3 统一字段交互类别

后续要把字段分成两类，而不是继续按“字段类型代码文件”来决定输入语义。

A. Action Control

适用字段：

1. Color
2. Enum
3. Bool
4. Asset

统一规则：

1. 点击命中当前控件时由路由层设置 armedFieldId。
2. 抬起时若仍满足激活条件，则执行动作。
3. 动作可能是：
   • 打开/关闭 popup
   • 请求外部 picker
   • toggle bool
   • activate asset picker
4. 动作执行前由路由层统一决定是否提交其他活动编辑。

B. Inline Editor

适用字段：

1. Number
2. Text
3. Vector2
4. Vector3
5. Vector4

统一规则：

1. 点击命中值域时由路由层激活编辑或拖拽。
2. 所有文本编辑态都只通过 activeEditFieldId 进入。
3. 提交、取消、切换字段时由路由层统一协调。
4. 不再通过 hadFocus 来“补判定”当前事件属于哪个字段。

6. State Refactor Plan

6.1 UIEditorPropertyGridState

需要把当前定义从“渲染态和交互 owner 混在一起”改成“路由态 + 视觉态”分离。

建议修改方向：

1. 保留：
   • hoveredSectionId
   • hoveredFieldId
   • hoveredHitTarget
   • popupHighlightedIndex
2. 替换：
   • focused -> gridFocused
   • pressedFieldId -> armedFieldId
3. 新增：
   • capturedFieldId
   • activeEditFieldId
   • 视情况新增 activeFieldPart
4. 明确 popupFieldId 是 owner，而不是顺手存一份状态。

6.2 UIEditorPropertyGridInteractionState

当前 editableFieldSession 仍然是核心污染源之一。需要改成：

1. 全局状态只保留 owner id 和必要的共享编辑资源。
2. 局部字段会话只在 owner 命中时构造和更新。
3. 非 owner 字段不再拿到一份复制出来的共享编辑会话。

也就是说，后续不应继续存在“给所有字段都 BuildInteractionState，然后再把共享 session 混进去”的流程。

7. Routing Refactor Plan

Phase A. 建立统一命中解析和 owner 解析

目标：

1. 在 UpdateUIEditorPropertyGridInteraction(...) 入口统一解析当前命中的 section / field / field part。
2. 明确当前事件是发给：
   • hover target
   • armed target
   • captured target
   • popup owner
   • active editor

实施内容：

1. 抽出 ResolveCurrentFieldTarget(...)。
2. 抽出 ResolveEventOwner(...)。
3. 明确 PointerButtonDown 和 PointerButtonUp 的路由优先级。

完成标准：

1. 一个事件最多只进入一个字段 owner 的处理逻辑。
2. 非 owner 字段不会因为 hadFocus 或视觉状态变化而被视为“参与了这次交互”。

Phase B. 把 Action Control 从共享广播链路中剥离

目标：

1. 让 Color、Enum、Bool、Asset 都走统一的 action-control owner 路由。
2. 消除 Color 与 Enum 当前“看起来都像按钮，但输入模型完全不同”的问题。

实施内容：

1. 新建统一的 action-control dispatch 层。
2. Color 不再依赖“先被别的字段处理器放过、再轮到我”的顺序偶然性。
3. Enum 的 popup 打开逻辑保留语义，但改为经由统一 owner 路由触发。
4. Bool、Asset 也并入相同的 click activation 契约。

完成标准：

1. Color 和 Enum 首击都依赖同一套 armed/release 判定语义。
2. Action Control 的 popup / picker / toggle 行为不再受其他字段旧焦点状态影响。

Phase C. 把 Inline Editor 改成 owner-exclusive 编辑模型

目标：

1. Number/Text/Vector 只处理当前活动编辑字段。
2. 去掉 hadFocus、focused 参与当前事件归属判定。

实施内容：

1. 删掉共享模板处理中“旧焦点也算有意义事件”的判定。
2. CommitActiveEdit(...) 改为只在 owner 切换或路由层明确要求时触发。
3. StoreInteractionState(...) 不再承担全局 owner 切换职责。
4. 拖拽、文本输入、提交/取消都改成围绕 activeEditFieldId 运行。

完成标准：

1. 点 Color 时不会因为前一个 Number/Vector 字段曾经 focused 而被抢走首击。
2. 各内联编辑字段只在自己是 active owner 时接收编辑事件。

Phase D. 统一 focus lost / popup close / picker return 的清理顺序

目标：

1. 让 FocusLost、utility window 关闭、popup 关闭后的首击行为稳定。

实施内容：

1. 路由层统一清理：
   • armedFieldId
   • capturedFieldId
   • activeEditFieldId
   • popup owner
2. 明确“关闭外部 picker”不会自动把旧字段恢复成 armed 状态。
3. 明确“返回 Inspector 后的第一下点击”必须重新从命中解析开始。

完成标准：

1. 关闭 ColorPicker 后直接单击 color swatch 即可再次打开。
2. 不需要先额外点一下面板来恢复交互。

8. File-Level Execution Plan

8.1 必改文件

1. new_editor/include/XCEditor/Fields/UIEditorPropertyGrid.h
2. new_editor/include/XCEditor/Fields/UIEditorPropertyGridInteraction.h
3. new_editor/src/Fields/PropertyGridInteractionInternal.h
4. new_editor/src/Fields/UIEditorPropertyGridInteraction.cpp
5. new_editor/src/Fields/UIEditorPropertyGrid.cpp

8.2 可能需要同步调整的字段交互文件

1. new_editor/src/Fields/UIEditorColorFieldInteraction.cpp
2. new_editor/src/Fields/UIEditorNumberFieldInteraction.cpp
3. new_editor/src/Fields/UIEditorTextFieldInteraction.cpp
4. new_editor/src/Fields/UIEditorVectorFieldInteractionShared.h
5. new_editor/src/Fields/UIEditorAssetFieldInteraction.cpp

8.3 原则上不该成为主战场的文件

1. new_editor/app/Features/Inspector/InspectorPanel.cpp
2. new_editor/app/Platform/Win32/Windowing/EditorUtilityWindowCoordinator.cpp
3. new_editor/app/Platform/Win32/Chrome/EditorWindowChromeController.cpp

这些文件最多做接口适配，不应该再承担修 PropertyGrid 首击丢失问题的核心逻辑。

9. Detailed Execution Steps

Step 1. 先改状态模型，不碰行为

1. 在头文件里引入新的 owner 状态字段。
2. 保持现有逻辑先能编译，通过适配层把旧字段名映射到新字段名。
3. 明确哪些状态属于路由层，哪些属于视觉层。

交付物：

1. 新的状态结构。
2. 路由状态注释和使用约束。

Step 2. 抽出统一命中和 owner 决策

1. 先把当前 scattered hit test 收拢到路由入口。
2. 让 PointerDown / PointerUp 都走同一套 owner 解析。
3. 暂时保留旧字段处理器，但只让 owner 字段收到事件。

交付物：

1. ResolveCurrentFieldTarget(...)
2. ResolveEventOwner(...)

Step 3. 重写 Action Control 路由

1. 让 Color 和 Enum 共用 action-control 激活契约。
2. 再纳入 Bool 和 Asset。
3. 把“是否需要提交已有编辑”提升到路由层统一决定。

交付物：

1. Action Control 输入约束。
2. Color / Enum / Bool / Asset 的统一 owner 生命周期。

Step 4. 重写 Inline Editor 路由

1. 删除基于 hadFocus 的事件归属判定。
2. 只在 owner 切换时提交旧编辑。
3. 把 vector 组件拖拽和文本输入纳入统一 owner-exclusive 逻辑。

交付物：

1. 无 hadFocus 兜底判定的 Inline Editor 路由。
2. 统一的 commit / cancel / drag 生命周期。

Step 5. 统一外部 popup / picker 返回后的恢复行为

1. 把 FocusLost 和 popup close 的清理顺序固定下来。
2. 做 color picker 返回、enum popup 切换、asset picker 返回等场景的首击验证。

交付物：

1. 稳定的失焦恢复行为。
2. 不依赖“双击补救”的交互语义。

Step 6. 清理旧状态分支和垃圾代码

1. 删除只为旧架构兜底的 hadFocus、共享 pressed reset、补丁式焦点同步逻辑。
2. 清理无主状态变量和死分支。
3. 补充必要注释，说明 owner 规则。

交付物：

1. 干净的主线逻辑。
2. 可维护的输入架构。

10. Red Lines

这次重构不能做下面这些事：

1. 不能通过在 InspectorPanel 外层加 reset 或“返回时强制清状态”来掩盖问题。
2. 不能依赖日志、延迟、双击判定、窗口 reopen、焦点强抢来修症状。
3. 不能在 Color 专门加一堆例外分支，而不处理共享输入路由本身。
4. 不能回退成“所有字段都当普通按钮”而破坏现有数值拖拽、文本编辑、键盘导航。
5. 不能继续把 selected、focused、pressed、editing 当成同一种状态使用。

11. Validation Matrix

11.1 Color

1. 点击 Color 首次打开 picker。
2. 关闭 picker 后直接再次点击同一 Color 首次打开。
3. 先编辑 Number，再点 Color，首击打开。
4. 先拖 Vector，再点 Color，首击打开。
5. 切换不同组件中的 Color 字段，首击打开。

11.2 Enum

1. 点击 Enum 首次打开下拉。
2. Enum 打开后切到 Color，首击打开颜色选择器。
3. Color 返回后切回 Enum，首击打开下拉。

11.3 Inline Editor

1. Number 点击进入编辑、提交、切换字段正常。
2. Text 点击进入编辑、提交、取消正常。
3. Vector2/3/4 组件拖拽和文本编辑不回退。

11.4 Focus / Popup / External Window

1. Inspector 失焦再获焦后，首击目标字段正常。
2. ColorPicker 关闭后，首击 Color 正常。
3. Enum popup 关闭后，首击任意 action-control 正常。

12. Risks and Mitigations

Risk A. 影响面大

原因：

1. PropertyGrid 是多个字段类型的共同入口。

应对：

1. 按 Action Control 和 Inline Editor 分阶段切换。
2. 每阶段都以行为矩阵回归验证。

Risk B. 向后兼容旧视觉状态

原因：

1. UIEditorPropertyGrid.cpp 目前从共享状态推导很多视觉态。

应对：

1. 先把 visual state 和 route state 分离。
2. 保证绘制代码只消费稳定 owner 状态，不直接猜测交互过程。

Risk C. Vector/Drag 回归

原因：

1. Vector 拖拽目前和共享 session 深度耦合。

应对：

1. 把拖拽先当作 captured owner 行为处理。
2. 不在 action-control 重构阶段动 vector 细节。

13. Completion Criteria

只有同时满足下面几条，这次重构才算真正完成：

1. Color 首击打开问题在所有已知场景下消失。
2. Enum、Bool、Asset、Color 共享统一 action-control 输入模型。
3. Number/Text/Vector 不再依赖 hadFocus / focused 判定当前事件归属。
4. pressedFieldId 这类共享按下态不再被多个字段处理器在一次事件里交叉清理。
5. PropertyGrid 的输入所有权模型能够被清晰描述为：
   • 路由层决定 owner
   • 字段层只处理 owner 事件
   • 路由层统一提交/取消/关闭 popup/切换 owner
6. 修复后不需要保留任何针对 Color 首击失效的临时补丁。

14. Recommended Implementation Order

实际开工时建议严格按下面顺序推进：

1. 改 UIEditorPropertyGrid.h
2. 改 UIEditorPropertyGridInteraction.h
3. 在 UIEditorPropertyGridInteraction.cpp 建立统一路由入口
4. 先重构 Color + Enum + Bool + Asset
5. 再重构 Number + Text + Vector
6. 最后清理旧模板分发和无用状态

如果顺序反过来，尤其是先在 Color 上局部修补，后面还会再次引入状态污染。