# EditorExtension Toolbar 扩展框架手册

## 模块概述
`Toolbar` 模块用于向 Unity 主工具栏动态注入自定义 `VisualElement` / `IMGUIContainer`，支持自动发现、排序、对齐、推荐样式、分组与用户覆盖配置。

## 适用场景
- 给 Unity 顶部工具栏挂项目级入口。
- 统一管理开发、调试、资源、场景、构建工具。
- 让工具栏元素支持分组、显隐与个性化排序。

## 快速上手
```csharp
using Paps.UnityToolbarExtenderUIToolkit;
using UnityEngine.UIElements;

[MainToolbarElement("DemoToolbar", ToolbarAlign.Right, 100)]
public class DemoToolbarElement : IMGUIContainer
{
    public void InitializeElement()
    {
        onGUIHandler = () => UnityEngine.GUILayout.Label("Demo");
    }
}
```

## 工作机制
1. `MainToolbar` 定位 Unity 原生 Toolbar 容器。
2. `MainToolbarAutomaticExtender` 负责刷新与注入。
3. 特性仓储扫描带 `MainToolbarElementAttribute` 的类型。
4. 元素实例化后包装为 `MainToolbarElement`。
5. 控制面板和覆盖配置负责用户态管理。

## 可调用 API
### 类型：`MainToolbarElementAttribute`
源码：`Packages/com.alicizax.unity.editor.extension/Editor/Toolbar/MainToolbarElementAttribute.cs`

- `MainToolbarElementAttribute(string id, ToolbarAlign alignment = ToolbarAlign.Left, int order = 0, bool useRecommendedStyles = true)`
- `Id`
- `Alignment`
- `Order`
- `UseRecommendedStyles`

### 类型：`MainToolbarElement`
源码：`Packages/com.alicizax.unity.editor.extension/Editor/Toolbar/MainToolbarElement.cs`

- `Id`
- `VisualElement`
- `Alignment`
- `Order`
- `UseRecommendedStyles`
- 构造函数 `MainToolbarElement(...)`

### 类型：`MainToolbar`
源码：`Packages/com.alicizax.unity.editor.extension/Editor/Toolbar/MainToolbar.cs`

- `OnInitialized`
- `OnRefresh`
- `UnityToolbarRoot`
- `LeftContainer`
- `CenterContainer`
- `RightContainer`
- `PlayModeButtonsContainer`
- `IsAvailable`

### 类型：`MainToolbarAutomaticExtender`
源码：`Packages/com.alicizax.unity.editor.extension/Editor/Toolbar/MainToolbarAutomaticExtender.cs`

- `OnRefresh`
- `OnAddedCustomContainersToToolbar`

### 类型：`MainToolbarControlPanelWindow`
源码：`Packages/com.alicizax.unity.editor.extension/Editor/Toolbar/ControlPanelWindow/MainToolbarControlPanelWindow.cs`

- `OpenWindow()`

### 类型：`MainToolbarElementController`
- `Id`
- `ControlledVisualElement`
- `HoldsAGroup`
- `HoldsANativeElement`

### 其他重要公开类型
- `ToolbarAlign`
- `GroupDefinition`
- `GroupElement`
- `ScriptableGroupDefinition`
- `MainToolbarElementDropdownAttribute`
- `MainToolbarElementOverride`
- `RecommendedStyle` 及派生类
- `Variable` / `SerializableVariable` 等变量序列化类型

## 打开控制面板
- 菜单：`Tools/Extension/Toolbar/Main Toolbar Control Panel`
- 代码：`MainToolbarControlPanelWindow.OpenWindow();`

## 注意事项
- `Id` 应稳定且全局唯一。
- 自定义元素建议在 `InitializeElement()` 中做依赖判空。