XCEngine/docs/api/XCEngine/Editor/panels/panels.md

# panels

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

**类型**: `submodule`

**描述**: 编辑器工作面板子模块，覆盖通用 `Panel` 生命周期、面板集合调度，以及 `Hierarchy`、`Project`、`Inspector`、`Scene/Game View`、`Console`、`MenuBar` 等主要工作窗口。

## 概览

`editor/src/panels` 是当前 Editor 工作区的直接承载层。
这些类型共同决定：
- 用户能看到哪些窗口
- 每个窗口如何接收 `IEditorContext`
- 哪些窗口只是展示层，哪些窗口还会参与动作路由
- Scene / Game 视口内容如何嵌入到普通面板生命周期里

按当前实现，这一层已经不是简单的“几个松散 ImGui 窗口”，而是统一挂在 `PanelCollection` 和 `EditorLayer` 之下的工作区系统。

## 当前面板集合

活跃文档当前覆盖：
- [Panel](Panel/Panel.md)
- [PanelCollection](PanelCollection/PanelCollection.md)
- [MenuBar](MenuBar/MenuBar.md)
- [HierarchyPanel](HierarchyPanel/HierarchyPanel.md)
- [ProjectPanel](ProjectPanel/ProjectPanel.md)
- [InspectorPanel](InspectorPanel/InspectorPanel.md)
- [ConsolePanel](ConsolePanel/ConsolePanel.md)
- [SceneViewPanel](SceneViewPanel/SceneViewPanel.md)
- [GameViewPanel](GameViewPanel/GameViewPanel.md)
- [ViewportPanelContent](ViewportPanelContent/ViewportPanelContent.md)
- [MaterialInspectorMaterialState](MaterialInspectorMaterialState/MaterialInspectorMaterialState.md)
- [MaterialInspectorMaterialStateIO](MaterialInspectorMaterialStateIO/MaterialInspectorMaterialStateIO.md)

## 分层关系

当前面板层可以粗分成三类。

### 工作区容器
- `Panel`
- `PanelCollection`

它们负责统一生命周期和上下文注入，不承担具体编辑业务。

### 资源 / 场景编辑面板

- `HierarchyPanel`
- `ProjectPanel`
- `InspectorPanel`
- `ConsolePanel`

这些面板主要负责采样用户交互、组织内容区和上下文菜单，再把动作导向 `Actions` / `Commands`。

### 视口面板

- `SceneViewPanel`
- `GameViewPanel`
- `ViewportPanelContent`

这几页则更多承担“把视口请求嵌入面板”的职责，真正的渲染仍由 `ViewportHostService` 管理。

### Inspector 材质状态 helper

- `MaterialInspectorMaterialState`
- `MaterialInspectorMaterialStateIO`

这两页不是 panel 本体，而是挂在 `editor/src/panels` 目录下、服务 `InspectorPanel` 材质 authoring 流程的状态与 I/O helper。

## 当前实现特点

### 上下文统一注入

当前每个面板都通过 `IEditorContext*` 获取：
- 选择状态
- 场景状态
- 项目状态
- undo
- active action route

所以面板层没有自己 new 一套 manager，而是共享同一个 editor context。

### 各面板职责

这轮源码和文档对齐后，几个关键面板的职责边界已经比较清晰：
- `HierarchyPanel` 主要负责树渲染，交互语义下沉到 `HierarchyActionRouter`
- `ProjectPanel` 主要负责目录树 / 面包屑 / 网格布局，编辑动作下沉到 `ProjectCommands`
- `InspectorPanel` 主要负责 subject 决策与 section 组织，具体字段 UI 下沉到 `ComponentEditors`

这说明当前 panel 层已经明显走向“薄面板 + 富命令 / 路由层”的结构。

### 视口面板不是 renderer

`SceneViewPanel` 和 `GameViewPanel` 不再应被理解成“自己持有独立渲染逻辑”的窗口。
更准确的描述是：

- 它们是普通面板
- 通过 `ViewportPanelContent` 和 `ViewportHostService` 请求并展示视口结果

## 设计说明

当前 panel 子模块的作用，是把编辑器工作区稳定成一组可组合窗口，而不是把所有逻辑都堆进 `EditorLayer`。
这样做的收益很直接：

- 工作区增删窗口成本更低
- 不同窗口可以共享统一 chrome 和布局协议
- 动作路由和命令层可以围绕窗口上下文形成清晰边界

## 当前限制

- 当前工作区仍然围绕单主窗口 editor 组织
- panel 层没有独立多文档系统
- 某些窗口间协作仍依赖显式 route 和共享上下文，没有更复杂的 pane-level focus manager

## 相关文档

- [Editor](../Editor.md)
- [Layout](../Layout/Layout.md)
- [UI](../UI/UI.md)
- [Actions](../Actions/Actions.md)
- [Commands](../Commands/Commands.md)