syncfusion-wpf-toolbar（同步融合 WPF 工具栏）

Implementing 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

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

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

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

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

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

ToolBarManager Integration

📄 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

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

Quick Start Example

Basic ToolBarAdv with Buttons

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

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

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

<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

<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

<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

<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

ToolBarManager Properties

Common Use Cases

Use Case 1: Application Menu Bar

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

Use Case 2: Contextual Toolbars

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

Use Case 3: Floating Tool Palettes

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

Use Case 4: User-Customizable Toolbars

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

Best Practices

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