syncfusion-wpf-splitbutton

实现 Syncfusion WPF SplitButton

Syncfusion WPF SplitButton（SplitButtonAdv）是按钮和菜单控件的组合。按钮提供默认操作，单击箭头则会显示下拉列表，供用户选择其他选项。此控件适用于需要同时提供主要操作和替代选项的场景。

何时使用此技能

在以下情况下使用此技能：

• 实现 WPF 分离按钮控件，并配置默认操作和下拉菜单
• 创建按钮与下拉菜单的组合，以供选择多个操作
• 构建数据绑定下拉菜单，并绑定 ItemsSource
• 实现命令模式，使用 ICommand 和 MVVM 架构
• 配置下拉菜单项，并添加图标、复选框和自定义项
• 处理分离按钮事件，例如下拉菜单的打开、关闭和菜单项单击
• 应用尺寸模式（Small、Normal、Large），并使用自定义图标
• 使用主题和模板自定义分离按钮的外观
• 在大尺寸按钮模式下支持多行文本
• 使用 CanExecute 命令逻辑启用或禁用操作

组件概述

主要功能

• 双重操作：主要按钮操作 + 提供替代选项的下拉菜单
• 数据绑定：全面支持 ItemsSource 和 DataTemplate，适用于 MVVM
• 命令绑定：按钮和菜单项支持 ICommand 和 CanExecute
• 尺寸模式：Small（仅图标）、Normal（图标 + 文本）、Large（大图标 + 文本）
• 图标模板：支持路径数据、字体图标和自定义模板
• 可自定义菜单项：图标、复选框、滚动条和自定义内容
• 下拉方向：控制弹出窗口的位置（Left、Right、BottomLeft 等）
• 事件：Opening、Opened、Closing、Closed、Click、IsCheckedChanged
• 主题：通过 SfSkinManager 使用内置主题，并支持自定义主题
• 多行文本：在 Large 尺寸模式下显示多行标签

控件结构

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)

文档与导航指南

此技能采用渐进式披露。根据实现需求阅读相应的参考文件：

入门

📄 阅读： references/getting-started.md

适合阅读的场景：设置新的分离按钮，或需要进行基本配置

涵盖主题：

• 安装和程序集部署（Syncfusion.Shared.WPF）
• 通过设计器、XAML 或 C# 代码添加控件
• 设置标签文本和基本属性
• 尺寸模式：Small（仅图标）、Normal（图标 + 文本）、Large（大图标 + 文本）
• 用于自定义图标的图标模板和图标模板选择器
• 使用 SmallIcon 和 LargeIcon 属性设置图像
• 配置图标宽度和高度
• 使用 IsDefault 模式通过 Enter 键激活
• 向 DropDownMenuGroup 添加菜单项

下拉菜单项配置

📄 阅读： references/dropdown-menu-items.md

适合阅读的场景：配置菜单项外观、添加自定义项或启用滚动条

涵盖主题：

• 为下拉菜单项设置图标
• 图标栏可见性（IconBarEnabled 属性）
• 大型菜单列表的滚动条可见性
• 可勾选的下拉菜单项（IsCheckable/IsChecked）
• 使用拖动柄调整下拉菜单大小（IsResizable）
• 通过 MoreItems 属性添加自定义下拉菜单项
• 自定义项的图标栏可见性（IsMoreItemsIconTrayEnabled）

数据绑定

📄 阅读： references/data-binding.md

适合阅读的场景：实现 MVVM 模式，或将集合绑定到下拉菜单项

涵盖主题：

• 为菜单项数据创建模型类
• 创建包含可观察集合的视图模型
• 将 ItemsSource 绑定到 DropDownMenuGroup
• 使用 ItemTemplate 和 DataTemplate 设置菜单项
• 为数据绑定设置 DataContext
• 将视图模型中的命令绑定到菜单项
• 完整的 MVVM 实现示例
• 用于 ICommand 的 DelegateCommand 模式

命令绑定

📄 阅读： references/command-binding.md

阅读时机：实现命令模式、处理按钮／菜单项操作

涵盖主题：

• Command 属性概述和 ICommand 接口
• 用于向命令处理程序传递数据的 CommandParameter
• DelegateCommand 实现模式
• 将命令绑定到 SplitButtonAdv 主按钮
• 将命令绑定到下拉菜单项
• 用于启用／禁用操作的 CanExecute 逻辑
• 使用 RaiseCanExecuteChanged 动态更新命令状态
• 使用 NotificationObject 的完整命令绑定示例

下拉菜单配置和事件

📄 阅读： references/dropdown-configuration.md

阅读时机：控制下拉菜单位置、处理事件、启用多行文本

涵盖主题：

• 下拉方向选项（Left、Right、BottomLeft、BottomRight、TopLeft、TopRight）
• DropDownOpening 和 DropDownOpened 事件
• DropDownClosing 和 DropDownClosed 事件
• 按钮和菜单项的 Click 事件
• 可勾选项的 IsCheckedChanged 事件
• 多行文本支持（IsMultiLine 属性）
• 事件处理程序实现模式

自定义和主题

📄 阅读： references/customization.md

阅读时机：应用主题、自定义外观、创建模板

涵盖主题：

• WPF 样式和模板概述
• 在 Expression Blend 中编辑外观
• 在 Visual Studio 中编辑外观
• 创建 ControlTemplate 资源
• 使用 SfSkinManager 应用内置主题
• 使用 ThemeStudio 创建自定义主题
• 模板资源位置选项

快速入门示例

带下拉菜单的基本 SplitButton

<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}");
}

常见模式

模式 1：使用 MVVM 的数据绑定 SplitButton

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

模式 2：使用 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">
    
</syncfusion:SplitButtonAdv>

模式 3：带图标模板的大型按钮

<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}">
    
</syncfusion:SplitButtonAdv>

模式 4：带可勾选项的可滚动下拉菜单

<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"/>
        
    </syncfusion:DropDownMenuGroup>
</syncfusion:SplitButtonAdv>

关键属性

SplitButtonAdv 属性

属性	类型	说明
Label	string	按钮上显示的文本
SizeMode	SizeMode	尺寸模式：Small、Normal 或 Large
SmallIcon	ImageSource	Small／Normal 模式下的图标
LargeIcon	ImageSource	Large 模式下的图标
IconTemplate	DataTemplate	自定义图标模板（覆盖 SmallIcon／LargeIcon）
IconTemplateSelector	DataTemplateSelector	动态选择图标模板
IconWidth	double	图标宽度
IconHeight	double	图标高度
Command	ICommand	主按钮单击命令
CommandParameter	object	传递给 Command 的参数
DropDirection	DropDirection	弹出窗口位置：Left、Right、BottomLeft 等
IsMultiLine	bool	在 Large 模式下启用多行文本
IsDefault	bool	按 Enter 键激活按钮

DropDownMenuGroup 属性

属性	类型	说明
ItemsSource	IEnumerable	菜单项的数据源
ItemTemplate	DataTemplate	菜单项的呈现模板
IconBarEnabled	bool	显示／隐藏垂直图标栏
ScrollBarVisibility	ScrollBarVisibility	长列表的滚动条可见性
IsResizable	bool	启用用于调整弹出窗口大小的拖柄
MaxHeight	double	下拉弹出窗口的最大高度
MoreItems	ObservableCollection	菜单底部的自定义项
IsMoreItemsIconTrayEnabled	bool	自定义项的图标栏

DropDownMenuItem 属性

Property	Type	Description
Header	object	菜单项的文本或内容
Icon	object	显示在标题前的图标
IsCheckable	bool	启用菜单项的复选框
IsChecked	bool	菜单项的选中状态
Command	ICommand	菜单项单击时执行的命令
CommandParameter	object	传递给 Command 的参数

常见用例

用例 1：带格式选项的保存按钮

主要操作以默认格式保存，下拉菜单提供其他格式（PDF、Excel、CSV）。

用例 2：带收件人选项的发送按钮

主要操作发送给默认收件人，下拉菜单列出其他收件人。

用例 3：带预设筛选器的筛选按钮

主要操作应用上次使用的筛选器，下拉菜单显示可用的预设筛选器。

用例 4：带导出类型的导出按钮

主要操作导出为默认类型，下拉菜单提供各种导出格式。

故障排除提示

问题： 图标显示不正确
解决方案： 检查图标优先级：IconTemplate > LargeIcon > SmallIcon。确保设置了正确的尺寸模式。

问题： 命令未执行
解决方案： 确认 CanExecute 返回 true。检查 RelativeSource 的 DataContext 绑定。

问题： 下拉菜单项未显示
解决方案： 确保 DropDownMenuGroup 包含 DropDownMenuItem 元素。检查 ItemTemplate 绑定。

问题： 事件未触发
解决方案： 确认事件处理程序名称与代码隐藏文件中的名称一致。检查 Opening/Closing 事件是否被取消。

其他资源

• GitHub 示例
• Syncfusion WPF 文档
• 控件依赖项