syncfusion-wpf-dropdownbuttonadv

实现 WPF DropDownButtonAdv

DropDownButtonAdv 是一个 WPF 下拉按钮控件，点击箭头时会显示弹出菜单。它支持带图标的菜单项、数据绑定、命令绑定、可配置的弹出方向、调整大小、多行文本和完整的主题支持。

程序集： Syncfusion.Shared.WPF
命名空间： Syncfusion.Windows.Tools.Controls
XAML 架构： xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

何时使用此技能

• 用户需要一个可以打开选项下拉列表的按钮
• 用户需要带图标、可勾选项或分组项的 WPF 下拉按钮
• 用户询问 DropDownButtonAdv、DropDownMenuGroup、DropDownMenuItem
• 用户需要为下拉菜单项使用 MVVM 绑定或命令绑定
• 用户需要控制弹出方向、调整大小或多行标签
• 用户询问如何处理下拉菜单打开/关闭事件或菜单项点击事件

快速开始

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

<syncfusion:DropDownButtonAdv Label="Country" SizeMode="Normal" SmallIcon="Images/flag.png">
    <syncfusion:DropDownMenuGroup>
        <syncfusion:DropDownMenuItem HorizontalAlignment="Left" Header="India">
            <syncfusion:DropDownMenuItem.Icon>
                <Image Source="Images/india.png"/>
            </syncfusion:DropDownMenuItem.Icon>
        </syncfusion:DropDownMenuItem>
        <syncfusion:DropDownMenuItem HorizontalAlignment="Left" Header="France"/>
        <syncfusion:DropDownMenuItem HorizontalAlignment="Left" Header="Germany"/>
    </syncfusion:DropDownMenuGroup>
</syncfusion:DropDownButtonAdv>

// C# equivalent
DropDownButtonAdv button = new DropDownButtonAdv();
button.Label = "Country";
button.SizeMode = SizeMode.Normal;
button.SmallIcon = new BitmapImage(new Uri("Images/flag.png", UriKind.RelativeOrAbsolute));
DropDownMenuGroup menu = new DropDownMenuGroup();
menu.Items.Add(new DropDownMenuItem { Header = "India", HorizontalAlignment = HorizontalAlignment.Left });
button.Content = menu;

常见模式

目标	方法
静态菜单项	直接在 DropDownMenuGroup 内声明 DropDownMenuItem
来自数据的动态项	绑定 DropDownMenuGroup.ItemsSource，并使用 ItemTemplate
菜单项点击时执行 MVVM 命令	在 DropDownMenuItem 上设置 Command 和 CommandParameter
弹出菜单在左下方打开	DropDirection="BottomLeft"（默认值）
带标签换行的大按钮	SizeMode="Large" + IsMultiLine="True"
可勾选项	在 DropDownMenuItem 上设置 IsCheckable="True"
菜单中的自定义 UIElement	使用 DropDownMenuGroup.MoreItems 属性
可滚动的长列表	在组上设置 MaxHeight + ScrollBarVisibility="Visible"
可调整大小的弹出菜单	在 DropDownMenuGroup 上设置 IsResizable="True"

关键属性

属性	类型	说明
Label	string	按钮文本标签
SizeMode	SizeMode	小 / 普通 / 大
SmallIcon	ImageSource	小和普通模式下的图标
LargeIcon	ImageSource	大模式下的图标
IconTemplate	DataTemplate	矢量/路径图标模板（优先于图像图标）
IconTemplateSelector	DataTemplateSelector	有条件地选择图标模板
IconWidth / IconHeight	double	图标尺寸
DropDirection	DropDirection	弹出位置（默认值：BottomLeft）
IsMultiLine	bool	多行标签（仅限大模式）
DropDownMenuGroup.ItemsSource	IEnumerable	数据绑定的菜单项
DropDownMenuGroup.IconBarEnabled	bool	显示垂直图标栏
DropDownMenuGroup.ScrollBarVisibility	ScrollBarVisibility	弹出菜单中的滚动条
DropDownMenuGroup.IsResizable	bool	弹出菜单上的调整大小手柄
DropDownMenuGroup.MoreItems	ObservableCollection<UIElement>	自定义底部项
DropDownMenuItem.IsCheckable	bool	允许勾选/取消勾选
DropDownMenuItem.Command	ICommand	MVVM 命令
DropDownMenuItem.CommandParameter	object	命令参数

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集引用（Syncfusion.Shared.WPF）
• 通过设计器、XAML 或 C# 添加
• 设置 Label、SizeMode（小/普通/大）
• SmallIcon、LargeIcon、IconWidth/IconHeight
• IconTemplate 和 IconTemplateSelector
• 内联定义基本菜单项
• 使用 SfSkinManager 应用主题

下拉菜单项

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

• 将 DropDownMenuGroup 用作容器元素
• 以声明方式定义带 Header 和 Icon 的 DropDownMenuItem
• IconBarEnabled（垂直图标栏）
• 使用 ScrollBarVisibility 处理长菜单项列表
• 使用 IsResizable 手柄调整弹出菜单大小
• 使用 IsCheckable / IsChecked 创建可勾选项
• 使用 MoreItems 添加自定义 UIElement
• IsMoreItemsIconTrayEnabled

数据绑定

📄 阅读： references/data-binding.md

• Model 和 ViewModel 模式
• 绑定 DropDownMenuGroup.ItemsSource
• 使用 DataTemplate 的 ItemTemplate
• 通过 x:Reference 从 ViewModel 绑定 DropDownMenuItem.Command
• 使用 DelegateCommand<T> 的完整 MVVM 示例
• 何时使用数据绑定，何时使用声明式项

命令绑定

📄 阅读： references/command-binding.md

• DropDownMenuItem 上的 Command 和 CommandParameter
• DelegateCommand<T> 实现
• CanExecute 和 CanPerformAction 切换模式
• 在声明式 XAML 中绑定 ViewModel 命令
• 注意事项：在 DataTemplate 中限定命令的作用域

下拉行为

📄 阅读： references/dropdown-behavior.md

• DropDirection 枚举：Left、Right、BottomLeft、BottomRight、TopLeft、TopRight
• 默认方向为 BottomLeft
• 使用 IsMultiLine 换行显示较长标签（仅限 Large 模式）
• 使用 FlowDirection 支持从右向左的布局

事件和外观

📄 阅读： references/events-and-appearance.md

• DropDownOpening / DropDownOpened 事件（支持取消）
• DropDownClosing / DropDownClosed 事件
• DropDownMenuItem.Click 事件
• DropDownMenuItem.IsCheckedChanged 事件
• 在 Expression Blend 或 Visual Studio 中编辑控件模板
• SfSkinManager 主题 + ThemeStudio 自定义主题