syncfusion-wpf-splitbutton（同步融合 wpf splitbutton）

Implementing Syncfusion WPF SplitButton

The Syncfusion WPF SplitButton (SplitButtonAdv) is a combination of a button and a menu control. The button provides a default action, while clicking the arrow displays a dropdown list for additional selections. This control is ideal for scenarios where you need both a primary action and alternative options.

When to Use This Skill

Use this skill when you need to:

• Implement WPF splitbutton controls with default actions and dropdown menus
• Create button-dropdown combinations for multiple action selections
• Build data-bound dropdown menus with ItemsSource binding
• Implement command patterns with ICommand and MVVM architecture
• Configure dropdown menu items with icons, checkboxes, and custom items
• Handle splitbutton events like dropdown opening/closing and item clicks
• Apply size modes (Small, Normal, Large) with custom icons
• Customize splitbutton appearance with themes and templates
• Support multiline text in large button modes
• Enable/disable actions using CanExecute command logic

Component Overview

Key Features

• Dual Action: Primary button action + dropdown menu for alternatives
• Data Binding: Full ItemsSource and DataTemplate support for MVVM
• Command Binding: ICommand support for button and menu items with CanExecute
• Size Modes: Small (icon only), Normal (icon + text), Large (large icon + text)
• Icon Templates: Support for path data, font icons, and custom templates
• Customizable Menu Items: Icons, checkboxes, scrollbars, and custom content
• Dropdown Direction: Control popup position (Left, Right, BottomLeft, etc.)
• Events: Opening, Opened, Closing, Closed, Click, IsCheckedChanged
• Theming: Built-in themes via SfSkinManager and custom theme support
• Multiline Text: Display multi-line labels in large size mode

Control Structure

SplitButtonAdv
├── Primary Button (default action)
│   ├── Label (text)
│   ├── Icon (SmallIcon/LargeIcon/IconTemplate)
│   └── Command (ICommand binding)
└── Dropdown Arrow (opens menu)
    └── DropDownMenuGroup (container)
        ├── DropDownMenuItem (standard items)
        │   ├── Header (text)
        │   ├── Icon (image)
        │   ├── IsCheckable (checkbox support)
        │   └── Command (ICommand binding)
        └── MoreItems (custom UIElement items)

Documentation and Navigation Guide

This skill uses progressive disclosure. Read the appropriate reference file based on your implementation needs:

Getting Started

📄 Read: references/getting-started.md

When to read: Setting up a new splitbutton, need basic configuration

Topics covered:

• Installation and assembly deployment (Syncfusion.Shared.WPF)
• Adding control via designer, XAML, or C# code
• Setting label text and basic properties
• Size modes: Small (icon only), Normal (icon + text), Large (large icon + text)
• Icon templates and icon template selectors for custom icons
• Setting images using SmallIcon and LargeIcon properties
• Configuring icon width and height
• IsDefault mode for Enter key activation
• Adding menu items to DropDownMenuGroup

Dropdown Menu Items Configuration

📄 Read: references/dropdown-menu-items.md

When to read: Configuring menu item appearance, adding custom items, enabling scrollbars

Topics covered:

• Setting icons for dropdown menu items
• Icon bar visibility (IconBarEnabled property)
• Scrollbar visibility for large menu lists
• Checkable dropdown menu items (IsCheckable/IsChecked)
• Resizing dropdown menu with gripper (IsResizable)
• Adding custom dropdown menu items via MoreItems property
• Icon bar visibility for custom items (IsMoreItemsIconTrayEnabled)

Data Binding

📄 Read: references/data-binding.md

When to read: Implementing MVVM patterns, binding collections to dropdown items

Topics covered:

• Creating model classes for menu item data
• Creating view models with observable collections
• Binding ItemsSource to DropDownMenuGroup
• Using ItemTemplate and DataTemplate for menu items
• Setting DataContext for data binding
• Binding commands from view model to menu items
• Complete MVVM implementation examples
• DelegateCommand pattern for ICommand

Command Binding

📄 Read: references/command-binding.md

When to read: Implementing command patterns, handling button/menu item actions

Topics covered:

• Command property overview and ICommand interface
• CommandParameter for passing data to command handlers
• DelegateCommand implementation pattern
• Binding commands to SplitButtonAdv primary button
• Binding commands to dropdown menu items
• CanExecute logic for enabling/disabling actions
• RaiseCanExecuteChanged for dynamic command state
• Complete command binding examples with NotificationObject

Dropdown Configuration and Events

📄 Read: references/dropdown-configuration.md

When to read: Controlling dropdown position, handling events, enabling multiline text

Topics covered:

• Dropdown direction options (Left, Right, BottomLeft, BottomRight, TopLeft, TopRight)
• DropDownOpening and DropDownOpened events
• DropDownClosing and DropDownClosed events
• Click event for button and menu items
• IsCheckedChanged event for checkable items
• Multiline text support (IsMultiLine property)
• Event handler implementation patterns

Customization and Theming

📄 Read: references/customization.md

When to read: Applying themes, customizing appearance, creating templates

Topics covered:

• WPF styles and templates overview
• Editing appearance in Expression Blend
• Editing appearance in Visual Studio
• Creating ControlTemplate resources
• Applying built-in themes with SfSkinManager
• Creating custom themes using ThemeStudio
• Template resource location options

Quick Start Example

Basic SplitButton with Dropdown Menu

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <syncfusion:SplitButtonAdv Label="Colors"
                                    SizeMode="Normal"
                                    Click="SplitButton_Click">
            <syncfusion:DropDownMenuGroup>
                <syncfusion:DropDownMenuItem Header="Red"
                                             Click="MenuItem_Click"/>
                <syncfusion:DropDownMenuItem Header="Green"
                                             Click="MenuItem_Click"/>
                <syncfusion:DropDownMenuItem Header="Blue"
                                             Click="MenuItem_Click"/>
            </syncfusion:DropDownMenuGroup>
        </syncfusion:SplitButtonAdv>
    </Grid>
</Window>

using Syncfusion.Windows.Tools.Controls;

private void SplitButton_Click(object sender, RoutedEventArgs e)
{
    MessageBox.Show("Primary action executed");
}

private void MenuItem_Click(object sender, RoutedEventArgs e)
{
    var menuItem = sender as DropDownMenuItem;
    MessageBox.Show($"Selected: {menuItem.Header}");
}

Common Patterns

Pattern 1: Data-Bound SplitButton with MVVM

<syncfusion:SplitButtonAdv Label="Country" SizeMode="Normal">
    <syncfusion:DropDownMenuGroup ItemsSource="{Binding Countries}">
        <syncfusion:DropDownMenuGroup.ItemTemplate>
            <DataTemplate>
                <syncfusion:DropDownMenuItem
                    Header="{Binding Name}"
                    Command="{Binding DataContext.SelectCountryCommand,
                             RelativeSource={RelativeSource AncestorType=syncfusion:SplitButtonAdv}}"
                    CommandParameter="{Binding}">
                    <syncfusion:DropDownMenuItem.Icon>
                        <Image Source="{Binding FlagIcon}"/>
                    </syncfusion:DropDownMenuItem.Icon>
                </syncfusion:DropDownMenuItem>
            </DataTemplate>
        </syncfusion:DropDownMenuGroup.ItemTemplate>
    </syncfusion:DropDownMenuGroup>
</syncfusion:SplitButtonAdv>

Pattern 2: Command Binding with CanExecute

public class ViewModel : NotificationObject
{
    private bool _canPerformAction = true;

    public DelegateCommand<object> ClickCommand { get; set; }

    public bool CanPerformAction
    {
        get => _canPerformAction;
        set
        {
            _canPerformAction = value;
            ClickCommand.RaiseCanExecuteChanged();
            RaisePropertyChanged(nameof(CanPerformAction));
        }
    }

    public ViewModel()
    {
        ClickCommand = new DelegateCommand<object>(
            ExecuteAction,
            CanExecuteAction);
    }

    private bool CanExecuteAction(object parameter) => CanPerformAction;

    private void ExecuteAction(object parameter)
    {
        MessageBox.Show($"Action executed: {parameter}");
    }
}

<syncfusion:SplitButtonAdv Label="Action"
                            Command="{Binding ClickCommand}"
                            CommandParameter="Primary Action">
    <!-- Dropdown items -->
</syncfusion:SplitButtonAdv>

Pattern 3: Large Button with Icon Template

<Window.Resources>
    <DataTemplate x:Key="customIconTemplate">
        <Grid Width="32" Height="32">
            <Path Data="M10,0 L20,10 L10,20 L0,10 Z"
                  Fill="#FF3A3A38"
                  Stretch="Fill"/>
        </Grid>
    </DataTemplate>
</Window.Resources>

<syncfusion:SplitButtonAdv Label="Custom Icon"
                            SizeMode="Large"
                            IconTemplate="{StaticResource customIconTemplate}">
    <!-- Dropdown items -->
</syncfusion:SplitButtonAdv>

Pattern 4: Scrollable Dropdown with Checkable Items

<syncfusion:SplitButtonAdv Label="Options" SizeMode="Normal">
    <syncfusion:DropDownMenuGroup MaxHeight="200"
                                    ScrollBarVisibility="Visible"
                                    IconBarEnabled="True">
        <syncfusion:DropDownMenuItem Header="Option 1"
                                     IsCheckable="True"
                                     IsChecked="True"/>
        <syncfusion:DropDownMenuItem Header="Option 2"
                                     IsCheckable="True"/>
        <syncfusion:DropDownMenuItem Header="Option 3"
                                     IsCheckable="True"/>
        <!-- More items... -->
    </syncfusion:DropDownMenuGroup>
</syncfusion:SplitButtonAdv>

Key Properties

SplitButtonAdv Properties

DropDownMenuGroup Properties

DropDownMenuItem Properties

Common Use Cases

Use Case 1: Save Button with Format Options

Primary action saves in default format, dropdown offers alternative formats (PDF, Excel, CSV).

Use Case 2: Send Button with Recipient Options

Primary action sends to default recipient, dropdown lists alternative recipients.

Use Case 3: Filter Button with Preset Filters

Primary action applies last filter, dropdown shows available filter presets.

Use Case 4: Export Button with Export Types

Primary action exports to default type, dropdown offers various export formats.

Troubleshooting Tips

Problem: Icons not displaying correctly Solution: Check icon priority: IconTemplate > LargeIcon > SmallIcon. Ensure correct size mode is set.

Problem: Commands not executing Solution: Verify CanExecute returns true. Check DataContext binding for RelativeSource.

Problem: Dropdown items not showing Solution: Ensure DropDownMenuGroup contains DropDownMenuItem elements. Check ItemTemplate binding.

Problem: Events not firing Solution: Verify event handler names match in code-behind. Check for cancellation in Opening/Closing events.

Additional Resources

• GitHub Samples
• Syncfusion WPF Documentation
• Control Dependencies