XCEngine/docs/api/XCEditor/Foundation/UIEditorCommandDispatcher/UIEditorCommandDispatcher.md

# UIEditorCommandDispatcher

**命名空间**: `XCEngine::UI::Editor`

**类型**: `class`

**头文件**: `XCEditor/Foundation/UIEditorCommandDispatcher.h`

**描述**: editor 命令执行入口，负责把 `commandId` 解析为 workspace command 或 host command，并执行 preview / dispatch。

## 概览

`UIEditorCommandDispatcher` 位于命令描述层和 shell 工作区控制器之间。它当前做两步：

1. `Evaluate(...)`
   - 校验注册表，查找 `commandId`，把 `ActivePanel` / `FixedPanelId` 等静态描述解析成当前可执行的具体命令。
2. `Dispatch(...)`
   - 在 `Evaluate(...)` 成功后，把 workspace 命令交给 `UIEditorWorkspaceController`，或者把 host 命令交给 `UIEditorHostCommandHandler`。

这让 menu、shortcut 和 shell interaction 都可以共享同一套命令求值与分发逻辑。

## 主要声明

| 声明 | 角色 |
|------|------|
| `UIEditorHostCommandHandler` | 宿主命令执行抽象，允许 shell 外部接管 host 命令。 |
| `UIEditorCommandEvaluationCode` | 命令求值失败或成功的细分原因。 |
| `UIEditorCommandEvaluationResult` | `Evaluate(...)` 的结果，包含解析出的 workspace command 与 preview 结果。 |
| `UIEditorCommandDispatchStatus` | 最终 dispatch 状态。 |
| `UIEditorCommandDispatchResult` | `Dispatch(...)` 的结果。 |
| `UIEditorCommandDispatcher` | 命令求值与分发器本体。 |

## 当前实现行为

- `ValidateConfiguration()` 直接复用 `ValidateUIEditorCommandRegistry(...)`。
- `Evaluate(...)` 当前会：
  - 在注册表无效时返回 `InvalidCommandRegistry`
  - 在命令不存在时返回 `UnknownCommandId`
  - 对 `Host` 命令转发给 `UIEditorHostCommandHandler::EvaluateHostCommand(...)`
  - 对 `Workspace` 命令解析 `panelSource`
  - 在 `ActivePanel` 但当前 workspace 没有 active panel 时返回 `MissingActivePanel`
  - 复制一份 controller 做 preview dispatch，用 `previewResult` 预测命令是否会被拒绝
- `Dispatch(...)` 当前先调用 `Evaluate(...)`，只有可执行时才真正分发。
- host 命令和 workspace 命令共享统一结果结构，但最终执行路径不同。

## 测试与调用链

- `tests/UI/Editor/unit/test_ui_editor_command_dispatcher.cpp`
  - 当前覆盖 active panel 解析、缺少 active panel 的拒绝路径，以及 dispatch 后 workspace 状态变更。
- `tests/UI/Editor/unit/test_ui_editor_shell_interaction.cpp`
  - 当前通过 shell interaction 间接消费命令派发器。
- `tests/UI/Editor/integration/shell/menu_bar_basic/main.cpp`
  - 当前把命令派发器挂进 menu bar / context menu 的真实交互路径。

## 相关文档

- [Foundation](../Foundation.md)
- [UIEditorCommandRegistry](../UIEditorCommandRegistry/UIEditorCommandRegistry.md)
- [UIEditorShortcutManager](../UIEditorShortcutManager/UIEditorShortcutManager.md)
- [UIEditorWorkspaceController](../../Shell/UIEditorWorkspaceController/UIEditorWorkspaceController.md)