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

# UIEditorCommandRegistry

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

**类型**: `enums + structs + functions`

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

**描述**: editor 命令描述协议与注册表校验入口，负责定义 workspace/host 命令的静态声明格式。

## 概览

`UIEditorCommandRegistry.h` 是 `XCEditor` 命令系统的静态描述层。它不执行命令，而是先回答这些问题：

- 一个 editor 命令的 `commandId`、`displayName` 和命令种类是什么。
- 这个命令对应的是 workspace command 还是 host command。
- 如果是 workspace command，它的 panel 路由来自固定 panel、当前 active panel，还是根本不需要 panel。
- 当前整张命令表是否合法，是否存在重复 id、空 displayName 或错误的 panel source 组合。

## 主要声明

| 声明 | 角色 |
|------|------|
| `UIEditorCommandKind` | 区分 `Workspace` 与 `Host` 命令。 |
| `UIEditorCommandPanelSource` | 描述 panel 路由来自 `None / FixedPanelId / ActivePanel`。 |
| `UIEditorWorkspaceCommandDescriptor` | 把高层命令映射到 `UIEditorWorkspaceCommandKind + panel routing`。 |
| `UIEditorCommandDescriptor` | 单个 editor 命令的完整静态描述。 |
| `UIEditorCommandRegistry` | 命令描述表。 |
| `UIEditorCommandRegistryValidationCode` | 注册表校验失败原因。 |
| `FindUIEditorCommandDescriptor(...)` | 通过 `commandId` 查找描述。 |
| `ValidateUIEditorCommandRegistry(...)` | 校验命令表的完整性与路由合法性。 |

## 当前实现行为

- `ValidateUIEditorCommandRegistry(...)` 会拒绝：
  - 空 `commandId`
  - 空 `displayName`
  - 重复 `commandId`
  - host 命令错误携带 workspace panel routing
  - 需要 panel 的 workspace 命令却没有 panel source
  - 不需要 panel 的命令却错误携带 `FixedPanelId` / `ActivePanel`
- `FindUIEditorCommandDescriptor(...)` 当前按线性遍历 `registry.commands` 查找。
- `CommandKindRequiresPanelId(...)` 当前把 `OpenPanel / ClosePanel / ShowPanel / HidePanel / ActivatePanel` 视为需要 panel 路由；`ResetWorkspace` 不需要。

## 测试与调用链

- `tests/UI/Editor/unit/test_ui_editor_command_registry.cpp`
  - 当前覆盖 descriptor 查找、重复 id、空 displayName 和 panel source 校验。
- `new_editor/src/Foundation/UIEditorCommandDispatcher.cpp`
  - 直接依赖这份注册表做命令解析和配置校验。
- `new_editor/src/Shell/UIEditorMenuModel.cpp`
  - 当前用它决定 menu item 的 command 元数据与启用态来源。

## 相关文档

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