AlicizaX/Client/Assets/Books/EditorExtension/ToolbarExtender.md

EditorExtension Toolbar 扩展框架手册

模块概述

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

适用场景

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

快速上手

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() 中做依赖判空。