syncfusion-wpf-toolbar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF ToolBarAdv

实现Syncfusion WPF ToolBarAdv

When to Use This Skill

适用场景

Reference this skill when users need to:

Implement ToolBarAdv controls in WPF applications with Syncfusion.Shared.WPF assembly
Create command toolbars with buttons, separators, and custom controls
Handle overflow items when toolbar content exceeds available space
Implement floating toolbars that can detach and dock at different positions
Use ToolBarManager to organize toolbars at top, bottom, left, or right positions
Configure band positioning to control toolbar layout within ToolBarTrayAdv
Add/remove button functionality allowing users to show/hide toolbar items
Customize toolbar appearance with themes, icon templates, and styling
Manage toolbar states (Docked, Floating, Hidden) dynamically
Implement gripper controls for toolbar drag-and-drop repositioning

当用户需要以下功能时，可参考本技能：

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

Component Overview

组件概述

ToolBarAdv is a container control for grouping related commands or controls, typically consisting of buttons that invoke actions. It provides:

Flexible positioning with Band and BandIndex properties
Overflow panel for items that don't fit in visible space
Multiple states: Docked, Floating, or Hidden
ToolBarManager integration for multi-position docking
Gripper control for user-driven repositioning
Icon templates supporting path data and font icons
Add/Remove buttons for user-customizable item visibility
Theme support via SfSkinManager

Key Controls:

```
ToolBarAdv
```
- Main toolbar container
```
ToolBarTrayAdv
```
- Container for organizing multiple toolbars in bands
```
ToolBarManager
```
- Layout manager for positioning toolbars at Top/Bottom/Left/Right
```
ToolBarItemSeparator
```
- Visual separator between toolbar items

Assembly: Syncfusion.Shared.WPF
Namespace:

Syncfusion.Windows.Tools.Controls

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

借助Band和BandIndex属性实现灵活定位
为无法在可见空间中显示的项提供溢出面板
多种状态：停靠、浮动或隐藏
ToolBarManager集成，支持多位置停靠
抓手控件，支持用户驱动的重定位
支持路径数据和字体图标图标模板
添加/移除按钮，支持用户自定义项可见性
通过SfSkinManager实现主题支持

核心控件：

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

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

Syncfusion.Windows.Tools.Controls

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Assembly and NuGet package installation
Creating ToolBarAdv via XAML and C#
Basic structure (Gripper, Overflow button)
Adding buttons and controls to toolbar
Icon template setup with path data
Initial appearance and styling
License key registration (v16.2.0.x+)

📄 阅读： references/getting-started.md

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

Positioning and Layout

定位与布局

📄 Read: references/positioning-and-layout.md

Band and BandIndex properties for toolbar placement
Overflow handling (OverflowMode.Always, Never, AsNeeded)
Gripper visibility control
ToolBarTrayAdv orientation (Horizontal/Vertical)
Multiple toolbar arrangement in bands
Overflow panel behavior

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

用于工具栏放置的Band和BandIndex属性
溢出处理（OverflowMode.Always、Never、AsNeeded）
抓手可见性控制
ToolBarTrayAdv方向（水平/垂直）
多个工具栏的波段排列
溢出面板行为

Add/Remove Button Functionality

添加/移除按钮功能

📄 Read: references/add-remove-buttons.md

EnableAddRemoveButton feature
Adding items with Icon and Label properties
Hiding toolbar items with IsAvailable attached property
ToolBarItemInfoCollection management
User-driven item visibility customization

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

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

Toolbar States and Behavior

工具栏状态与行为

📄 Read: references/toolbar-states.md

ToolBarState property (Docked, Floating, Hidden)
FloatingBarLocation configuration
Docking restrictions (CanDockAtTop/Bottom/Left/Right)
ToolBarStateChanged event handling
Floating toolbar lifecycle
State transitions and management

📄 阅读： references/toolbar-states.md

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

ToolBarManager Integration

ToolBarManager集成

📄 Read: references/toolbar-manager.md

TopToolBarTray, BottomToolBarTray, LeftToolBarTray, RightToolBarTray
Multi-position toolbar layout
Content placement in remaining space
IsLocked property to prevent repositioning
Floating toolbar requirements

📄 阅读： references/toolbar-manager.md

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

Customization and Theming

自定义与主题

📄 Read: references/customization-theming.md

FloatingToolBarStyle property
Foreground color customization
ControlsResourceDictionary for FrameworkElement styles
SfSkinManager theme application
ThemeStudio for custom themes
Built-in theme options

📄 阅读： references/customization-theming.md

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

Quick Start Example

快速入门示例

Basic ToolBarAdv with Buttons

带按钮的基础ToolBarAdv

XAML:

xaml

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

C#:

csharp

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;

XAML：

xaml

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

C#：

csharp

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 with Multiple Positions

多位置布局的ToolBarManager

XAML:

xaml

<syncfusion:ToolBarManager x:Name="toolBarManager">
    <!-- Top Toolbar -->
    <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>
    
    <!-- Left Toolbar -->
    <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>
    
    <!-- Main Content -->
    <syncfusion:ToolBarManager.Content>
        <TextBox Text="Your application content here"/>
    </syncfusion:ToolBarManager.Content>
</syncfusion:ToolBarManager>

XAML：

xaml

<syncfusion:ToolBarManager x:Name="toolBarManager">
    <!-- Top Toolbar -->
    <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>
    
    <!-- Left Toolbar -->
    <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>
    
    <!-- Main Content -->
    <syncfusion:ToolBarManager.Content>
        <TextBox Text="Your application content here"/>
    </syncfusion:ToolBarManager.Content>
</syncfusion:ToolBarManager>

Common Patterns

常见模式

Pattern 1: Band Positioning for Multiple Toolbars

模式1：多工具栏的波段定位

xaml

<syncfusion:ToolBarTrayAdv>
    <!-- First toolbar on Band 0 -->
    <syncfusion:ToolBarAdv Band="0" BandIndex="0" ToolBarName="Standard">
        <Button Content="New"/>
        <Button Content="Open"/>
    </syncfusion:ToolBarAdv>
    
    <!-- Second toolbar on same band -->
    <syncfusion:ToolBarAdv Band="0" BandIndex="1" ToolBarName="Extras">
        <Button Content="Cut"/>
        <Button Content="Copy"/>
    </syncfusion:ToolBarAdv>
    
    <!-- Third toolbar on different band -->
    <syncfusion:ToolBarAdv Band="1" BandIndex="0" ToolBarName="Format">
        <Button Content="Bold"/>
        <Button Content="Italic"/>
    </syncfusion:ToolBarAdv>
</syncfusion:ToolBarTrayAdv>

xaml

<syncfusion:ToolBarTrayAdv>
    <!-- First toolbar on Band 0 -->
    <syncfusion:ToolBarAdv Band="0" BandIndex="0" ToolBarName="Standard">
        <Button Content="New"/>
        <Button Content="Open"/>
    </syncfusion:ToolBarAdv>
    
    <!-- Second toolbar on same band -->
    <syncfusion:ToolBarAdv Band="0" BandIndex="1" ToolBarName="Extras">
        <Button Content="Cut"/>
        <Button Content="Copy"/>
    </syncfusion:ToolBarAdv>
    
    <!-- Third toolbar on different band -->
    <syncfusion:ToolBarAdv Band="1" BandIndex="0" ToolBarName="Format">
        <Button Content="Bold"/>
        <Button Content="Italic"/>
    </syncfusion:ToolBarAdv>
</syncfusion:ToolBarTrayAdv>

Pattern 2: Overflow Mode Control

模式2：溢出模式控制

xaml

<syncfusion:ToolBarAdv>
    <!-- Always visible -->
    <Button syncfusion:ToolBarAdv.OverflowMode="Never"
            Content="Important"/>
    
    <!-- Can overflow when needed -->
    <Button syncfusion:ToolBarAdv.OverflowMode="AsNeeded"
            Content="Normal"/>
    
    <!-- Always in overflow -->
    <Button syncfusion:ToolBarAdv.OverflowMode="Always"
            Content="Advanced"/>
</syncfusion:ToolBarAdv>

xaml

<syncfusion:ToolBarAdv>
    <!-- Always visible -->
    <Button syncfusion:ToolBarAdv.OverflowMode="Never"
            Content="Important"/>
    
    <!-- Can overflow when needed -->
    <Button syncfusion:ToolBarAdv.OverflowMode="AsNeeded"
            Content="Normal"/>
    
    <!-- Always in overflow -->
    <Button syncfusion:ToolBarAdv.OverflowMode="Always"
            Content="Advanced"/>
</syncfusion:ToolBarAdv>

Pattern 3: Add/Remove Buttons with Labels

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

xaml

<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>

xaml

<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>

Pattern 4: Floating Toolbar Configuration

模式4：浮动工具栏配置

xaml

<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>

xaml

<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>

Key Properties

核心属性

ToolBarAdv Properties

ToolBarAdv属性

Property	Description	Type	When to Use
`Band`	Band index where toolbar should be placed	int	Position toolbar in specific row/column
`BandIndex`	Position within the band	int	Order multiple toolbars in same band
`ToolBarName`	Display name for toolbar	string	Identify toolbar to users
`GripperVisibility`	Show/hide gripper handle	Visibility	Control user repositioning ability
`FloatingBarLocation`	Position for floating state	Point	Set custom floating position
`IsOverflowOpen`	Overflow popup open state	bool	Programmatically open/close overflow
`EnableAddRemoveButton`	Show add/remove menu	bool	Allow users to customize visible items

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

ToolBarManager Properties

ToolBarManager属性

Property	Description	Type	When to Use
`TopToolBarTray`	Toolbar tray at top	ToolBarTrayAdv	Position toolbars at top
`BottomToolBarTray`	Toolbar tray at bottom	ToolBarTrayAdv	Position toolbars at bottom
`LeftToolBarTray`	Toolbar tray at left	ToolBarTrayAdv	Position toolbars at left
`RightToolBarTray`	Toolbar tray at right	ToolBarTrayAdv	Position toolbars at right
`CanDockAtTop/Bottom/Left/Right`	Allow docking at position	bool	Restrict docking positions
`Content`	Main application content	UIElement	Content displayed in remaining space

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

Common Use Cases

常见用例

Use Case 1: Application Menu Bar

用例1：应用菜单栏

Create standard application toolbar with File, Edit, Format commands positioned at top.

When: Building document editors, IDEs, or productivity applications
Read: references/getting-started.md, references/toolbar-manager.md

创建包含文件、编辑、格式命令的标准应用工具栏，定位在顶部。

适用场景： 构建文档编辑器、IDE或生产力应用
阅读： references/getting-started.md, references/toolbar-manager.md

Use Case 2: Contextual Toolbars

用例2：上下文工具栏

Multiple toolbars organized in bands, showing/hiding based on current context or selection.

When: Complex applications with mode-specific commands
Read: references/positioning-and-layout.md, references/add-remove-buttons.md

在波段中组织多个工具栏，根据当前上下文或选择显示/隐藏。

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

Use Case 3: Floating Tool Palettes

用例3：浮动工具面板

Detachable toolbars that users can position anywhere on screen.

When: Graphics editors, design tools, or applications with detachable panels
Read: references/toolbar-states.md, references/toolbar-manager.md

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

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

Use Case 4: User-Customizable Toolbars

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

Allow users to show/hide toolbar items based on their preferences.

When: Applications with power users who want to customize their workspace
Read: references/add-remove-buttons.md

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

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

Best Practices

最佳实践

Use ToolBarManager when you need toolbars at multiple positions (top/bottom/left/right)
Set ToolBarName for all toolbars to help users identify them
Configure OverflowMode strategically - keep critical buttons visible with
```
Never
```
Enable Add/Remove buttons for power user scenarios with many optional commands
Use Icon and Label attached properties when EnableAddRemoveButton is true
Set meaningful FloatingBarLocation to ensure floating toolbars appear in useful positions
Apply themes consistently using SfSkinManager for professional appearance
Use IconTemplate for scalable vector icons instead of raster images
Group related commands in the same toolbar with separators
Test toolbar behavior at different window sizes to ensure overflow works correctly

使用ToolBarManager：当你需要在多个位置（顶部/底部/左侧/右侧）放置工具栏时
为所有工具栏设置ToolBarName：帮助用户识别工具栏
合理配置OverflowMode：使用
```
Never
```
确保关键按钮始终可见
启用添加/移除按钮：适用于包含大量可选命令的高级用户场景
当EnableAddRemoveButton为true时，使用Icon和Label附加属性
设置有意义的FloatingBarLocation：确保浮动工具栏出现在实用位置
使用SfSkinManager一致应用主题：打造专业外观
使用IconTemplate获取可缩放矢量图标：替代光栅图像
使用分隔符将相关命令分组在同一工具栏中
在不同窗口尺寸下测试工具栏行为：确保溢出功能正常工作