syncfusion-wpf-toolbar

实现 Syncfusion WPF ToolBarAdv

何时使用此技能

在以下情况下，用户需要：

• 在 WPF 应用程序中实现 ToolBarAdv 控件，并使用 Syncfusion.Shared.WPF 程序集
• 创建命令工具栏，其中包含按钮、分隔符和自定义控件
• 处理溢出项，以应对工具栏内容超出可用空间的情况
• 实现浮动工具栏，使其可以脱离并停靠到不同位置
• 使用 ToolBarManager 将工具栏组织在顶部、底部、左侧或右侧
• 配置带区位置，以控制工具栏在 ToolBarTrayAdv 中的布局
• 添加/移除按钮功能，允许用户显示/隐藏工具栏项
• 使用主题、图标模板和样式自定义工具栏外观
• 动态管理工具栏状态（Docked、Floating、Hidden）
• 实现抓手控件，以支持工具栏拖放和重新定位

组件概览

ToolBarAdv 是一种用于分组相关命令或控件的容器控件，通常由可触发操作的按钮组成。它提供：

• 使用 Band 和 BandIndex 属性进行灵活定位
• 溢出面板，用于容纳无法在可见空间内显示的项
• 多种状态：Docked、Floating 或 Hidden
• 用于多位置停靠的 ToolBarManager 集成
• 用于用户重新定位的抓手控件
• 支持路径数据和字体图标的图标模板
• 用于自定义项可见性的添加/移除按钮
• 通过 SfSkinManager 支持主题

关键控件：

• ToolBarAdv - 主工具栏容器
• ToolBarTrayAdv - 用于在带区中组织多个工具栏的容器
• ToolBarManager - 用于将工具栏定位到顶部/底部/左侧/右侧的布局管理器
• ToolBarItemSeparator - 工具栏项之间的视觉分隔符

程序集： Syncfusion.Shared.WPF
命名空间： Syncfusion.Windows.Tools.Controls

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集和 NuGet 包安装
• 通过 XAML 和 C# 创建 ToolBarAdv
• 基本结构（抓手、溢出按钮）
• 向工具栏添加按钮和控件
• 使用路径数据设置图标模板
• 初始外观和样式
• 注册许可证密钥（v16.2.0.x+）

定位和布局

📄 阅读： references/positioning-and-layout.md

• 用于工具栏定位的 Band 和 BandIndex 属性
• 溢出处理（OverflowMode.Always、Never、AsNeeded）
• 抓手可见性控制
• ToolBarTrayAdv 方向（Horizontal/Vertical）
• 在带区中排列多个工具栏
• 溢出面板行为

添加/移除按钮功能

📄 阅读： references/add-remove-buttons.md

• EnableAddRemoveButton 功能
• 使用 Icon 和 Label 属性添加项
• 使用 IsAvailable 附加属性隐藏工具栏项
• ToolBarItemInfoCollection 管理
• 用户自定义项可见性

工具栏状态和行为

📄 阅读： references/toolbar-states.md

• ToolBarState 属性（Docked、Floating、Hidden）
• FloatingBarLocation 配置
• 停靠限制（CanDockAtTop/Bottom/Left/Right）
• ToolBarStateChanged 事件处理
• 浮动工具栏生命周期
• 状态转换和管理

ToolBarManager 集成

📄 阅读： references/toolbar-manager.md

• TopToolBarTray、BottomToolBarTray、LeftToolBarTray、RightToolBarTray
• 多位置工具栏布局
• 在剩余空间中放置内容
• 用于防止重新定位的 IsLocked 属性
• 浮动工具栏要求

自定义与主题

📄 阅读： references/customization-theming.md

• FloatingToolBarStyle 属性
• 前景色自定义
• 用于 FrameworkElement 样式的 ControlsResourceDictionary
• 应用 SfSkinManager 主题
• 使用 ThemeStudio 创建自定义主题
• 内置主题选项

快速入门示例

带按钮的基本 ToolBarAdv

XAML：

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <syncfusion:ToolBarTrayAdv>
        <syncfusion:ToolBarAdv ToolBarName="Standard" Height="40">
            
            <Button Width="22" Height="22" ToolTip="New">
                <Image Source="Images/NewDocumentHS.png" Width="16" Height="16"/>
            </Button>
            
            
            <Button Width="22" Height="22" ToolTip="Open">
                <Image Source="Images/openHS.png" Width="16" Height="16"/>
            </Button>
            
            
            <syncfusion:ToolBarItemSeparator />
            
            
            <Button Width="22" Height="22" ToolTip="Save">
                <Image Source="Images/saveHS.png" Width="16" Height="16"/>
            </Button>
        </syncfusion:ToolBarAdv>
    </syncfusion:ToolBarTrayAdv>
</Window>

C#：

using Syncfusion.Windows.Tools.Controls;

// Create toolbar
ToolBarAdv toolBar = new ToolBarAdv();
toolBar.ToolBarName = "Standard";
toolBar.Height = 40;

// Add New button
Button newButton = new Button
{
    Width = 22,
    Height = 22,
    ToolTip = "New",
    Content = new Image 
    { 
        Source = new BitmapImage(new Uri("Images/NewDocumentHS.png", UriKind.Relative)),
        Width = 16,
        Height = 16
    }
};
toolBar.Items.Add(newButton);

// Add to ToolBarTray
ToolBarTrayAdv tray = new ToolBarTrayAdv();
tray.ToolBars.Add(toolBar);

// Add to window
this.Content = tray;

带多个位置的 ToolBarManager

XAML：

<syncfusion:ToolBarManager x:Name="toolBarManager">
    
    <syncfusion:ToolBarManager.TopToolBarTray>
        <syncfusion:ToolBarTrayAdv>
            <syncfusion:ToolBarAdv ToolBarName="File">
                <Button Width="22" Height="22" ToolTip="New">
                    <Image Source="Images/NewDocumentHS.png" Width="16" Height="16"/>
                </Button>
            </syncfusion:ToolBarAdv>
        </syncfusion:ToolBarTrayAdv>
    </syncfusion:ToolBarManager.TopToolBarTray>
    
    
    <syncfusion:ToolBarManager.LeftToolBarTray>
        <syncfusion:ToolBarTrayAdv Orientation="Vertical">
            <syncfusion:ToolBarAdv ToolBarName="Tools">
                <Button Width="22" Height="22" ToolTip="Cut">
                    <Image Source="Images/CutHS.png" Width="16" Height="16"/>
                </Button>
            </syncfusion:ToolBarAdv>
        </syncfusion:ToolBarTrayAdv>
    </syncfusion:ToolBarManager.LeftToolBarTray>
    
    
    <syncfusion:ToolBarManager.Content>
        <TextBox Text="Your application content here"/>
    </syncfusion:ToolBarManager.Content>
</syncfusion:ToolBarManager>

常见模式

模式 1：为多个工具栏设置带区位置

<syncfusion:ToolBarTrayAdv>
    
    <syncfusion:ToolBarAdv Band="0" BandIndex="0" ToolBarName="Standard">
        <Button Content="New"/>
        <Button Content="Open"/>
    </syncfusion:ToolBarAdv>
    
    
    <syncfusion:ToolBarAdv Band="0" BandIndex="1" ToolBarName="Extras">
        <Button Content="Cut"/>
        <Button Content="Copy"/>
    </syncfusion:ToolBarAdv>
    
    
    <syncfusion:ToolBarAdv Band="1" BandIndex="0" ToolBarName="Format">
        <Button Content="Bold"/>
        <Button Content="Italic"/>
    </syncfusion:ToolBarAdv>
</syncfusion:ToolBarTrayAdv>

模式 2：控制溢出模式

<syncfusion:ToolBarAdv>
    
    <Button syncfusion:ToolBarAdv.OverflowMode="Never"
            Content="Important"/>
    
    
    <Button syncfusion:ToolBarAdv.OverflowMode="AsNeeded"
            Content="Normal"/>
    
    
    <Button syncfusion:ToolBarAdv.OverflowMode="Always"
            Content="Advanced"/>
</syncfusion:ToolBarAdv>

模式 3：添加／移除带标签的按钮

<syncfusion:ToolBarAdv EnableAddRemoveButton="True">
    <Button syncfusion:ToolBarAdv.Label="New Document"
            syncfusion:ToolBarAdv.Icon="Images/NewDocumentHS.png">
        <Image Source="Images/NewDocumentHS.png" Width="16" Height="16"/>
    </Button>
    
    <Button syncfusion:ToolBarAdv.Label="Open Document"
            syncfusion:ToolBarAdv.Icon="Images/openHS.png">
        <Image Source="Images/openHS.png" Width="16" Height="16"/>
    </Button>
</syncfusion:ToolBarAdv>

模式 4：配置浮动工具栏

<syncfusion:ToolBarManager>
    <syncfusion:ToolBarManager.TopToolBarTray>
        <syncfusion:ToolBarTrayAdv>
            <syncfusion:ToolBarAdv 
                ToolBarName="FloatingTools"
                syncfusion:ToolBarManager.ToolBarState="Floating"
                FloatingBarLocation="500,300">
                <Button Content="Tool 1"/>
                <Button Content="Tool 2"/>
            </syncfusion:ToolBarAdv>
        </syncfusion:ToolBarTrayAdv>
    </syncfusion:ToolBarManager.TopToolBarTray>
</syncfusion:ToolBarManager>

关键属性

ToolBarAdv 属性

属性	描述	类型	使用场景
Band	工具栏所在的带区索引	int	将工具栏放置在指定行／列
BandIndex	工具栏在带区中的位置	int	为同一带区中的多个工具栏排序
ToolBarName	工具栏的显示名称	string	帮助用户识别工具栏
GripperVisibility	显示／隐藏拖动手柄	Visibility	控制用户重新定位工具栏的能力
FloatingBarLocation	浮动状态下的位置	Point	设置自定义浮动位置
IsOverflowOpen	溢出弹出窗口的打开状态	bool	以编程方式打开／关闭溢出窗口
EnableAddRemoveButton	显示添加／移除菜单	bool	允许用户自定义可见项

ToolBarManager 属性

属性	描述	类型	使用场景
TopToolBarTray	顶部的工具栏托盘	ToolBarTrayAdv	将工具栏放置在顶部
BottomToolBarTray	底部的工具栏托盘	ToolBarTrayAdv	将工具栏放置在底部
LeftToolBarTray	左侧的工具栏托盘	ToolBarTrayAdv	将工具栏放置在左侧
RightToolBarTray	右侧的工具栏托盘	ToolBarTrayAdv	将工具栏放置在右侧
CanDockAtTop/Bottom/Left/Right	允许停靠的位置	bool	限制停靠位置
Content	应用程序的主要内容	UIElement	在剩余空间中显示的内容

常见用例

用例 1：应用程序菜单栏

创建包含“文件”“编辑”“格式”命令的标准应用程序工具栏，并将其放置在顶部。

适用场景： 构建文档编辑器、IDE 或效率应用程序
阅读： references/getting-started.md、references/toolbar-manager.md

用例 2：上下文工具栏

将多个工具栏组织在不同带区中，并根据当前上下文或所选内容显示／隐藏。

适用场景： 具有特定模式命令的复杂应用程序
阅读： references/positioning-and-layout.md、references/add-remove-buttons.md

用例 3：浮动工具面板

可分离的工具栏，用户可以将其放置在屏幕上的任意位置。

适用场景： 图形编辑器、设计工具或包含可分离面板的应用程序
阅读： references/toolbar-states.md、references/toolbar-manager.md

用例 4：用户可自定义的工具栏

允许用户根据偏好显示／隐藏工具栏项。

适用场景： 面向希望自定义工作区的高级用户的应用程序
阅读： references/add-remove-buttons.md

最佳实践

1. 在需要将工具栏放置在多个位置（顶部／底部／左侧／右侧）时，使用 ToolBarManager
2. 为所有工具栏设置 ToolBarName，帮助用户识别它们
3. 合理配置 OverflowMode：将关键按钮设为 Never，使其始终可见
4. 在包含许多可选命令的高级用户场景中，启用添加／移除按钮
5. 当 EnableAddRemoveButton 为 true 时，使用 Icon 和 Label 附加属性
6. 设置有意义的 FloatingBarLocation，确保浮动工具栏显示在合适的位置
7. 使用 SfSkinManager 统一应用主题，打造专业外观
8. 使用 IconTemplate 显示可缩放的矢量图标，而不是栅格图像
9. 使用分隔符将相关命令分组到同一工具栏中
10. 在不同窗口尺寸下测试工具栏行为，确保溢出功能正常