syncfusion-wpf-multi-column-dropdown

实现 Syncfusion WPF 多列下拉控件

SfMultiColumnDropDownControl 将 TextBox 编辑器与功能强大的 SfDataGrid 相结合，提供一个可搜索、可筛选且显示多列的下拉控件。它支持自动完成、增量筛选、单选和多选模式，以及丰富的自定义选项。

组件概述

SfMultiColumnDropDownControl 是一个复合控件，它在下拉弹出窗口中嵌入 SfDataGrid，使用户能够：

• 搜索和筛选 在编辑器中输入的项目
• 在下拉列表中查看多列数据
• 从网格中选择单个或多个项目
• 根据 DisplayMember 自动完成文本
• 自定义弹出窗口外观、列和行为

主要功能：

• 绑定到任意 IEnumerable 源
• 自动或手动生成列
• 区分大小写和变音符号的筛选
• 复杂属性和索引器属性绑定
• 键盘导航和无障碍支持
• 可调整大小且外观可自定义的弹出窗口

何时使用此技能

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

• 创建显示多列数据的 WPF 下拉控件
• 实现带网格视图的可搜索、可筛选下拉列表
• 构建支持自动完成和增量筛选的下拉控件
• 允许用户从多列数据网格中选择项目
• 创建支持复杂数据绑定的可编辑下拉列表
• 实现支持单选或多选的下拉列表
• 自定义下拉弹出窗口的外观和行为
• 为下拉控件添加键盘导航

文档和导航指南

入门

📄 阅读： references/getting-started.md

在以下情况下使用：

• 首次设置控件
• 了解程序集要求
• 通过 Designer、XAML 或 C# 添加控件
• 创建基本数据模型
• 绑定初始 ItemsSource
• 定义 DisplayMember 和 ValueMember

涵盖主题：

• 程序集部署（Syncfusion.Data.WPF、Syncfusion.SfGrid.WPF）
• 使用 SfMultiColumnDropDownControl 创建 WPF 应用程序
• 通过 Designer、XAML 和代码隐藏添加控件
• 基本 ItemsSource 绑定
• DisplayMember 和 ValueMember 配置
• 主题支持

数据绑定

📄 阅读： references/data-binding.md

在以下情况下使用：

• 将数据绑定到下拉控件
• 了解 DisplayMember 与 ValueMember 的区别
• 使用复杂属性
• 使用索引器属性
• 访问 SelectedItem 和 SelectedValue

涵盖主题：

• ItemsSource 属性的用法
• DisplayMember（在编辑器中的视觉呈现）
• ValueMember（SelectedValue 属性的值）
• 在 XAML 和代码隐藏中绑定集合
• 复杂属性绑定（例如，customerDetails.Name）
• 索引器属性绑定（例如，Country[0]）

列配置

📄 阅读： references/columns.md

在以下情况下使用：

• 配置下拉网格列
• 自动生成或手动定义列
• 自定义列类型和模板
• 处理 AutoGeneratingColumn 事件
• 设置列大小和宽度

涵盖主题：

• AutoGenerateColumns 属性
• AutoGenerateColumnMode（Reset、RetainOld、ResetAll、None）
• 手动定义列集合
• 列类型（GridTextColumn、GridCurrencyColumn 等）
• 用于自定义的 AutoGeneratingColumn 事件
• 列模板（HeaderTemplate、CellTemplate）
• 用于宽度管理的 GridColumnSizer

编辑和筛选

📄 阅读： references/editing-autocomplete.md

适用于：

• 启用自动补全功能
• 实现增量筛选
• 配置搜索条件
• 基于多列进行筛选
• 自定义编辑器行为

涵盖主题：

• 用于文本建议的 AllowAutoComplete
• 用于实时筛选的 AllowIncrementalFiltering
• SearchCondition（StartsWith、Contains、Equals）
• AllowCaseSensitiveFiltering 选项
• AllowDiacriticSensitiveFiltering 选项
• 编辑器属性（ReadOnly、AllowNullInput、AllowSpinOnMouseWheel）
• 重写 FilterRecord 方法以实现自定义筛选
• 用于多列筛选的 SearchText 属性

选择

📄 阅读： references/selection.md

适用于：

• 实现单选或多选
• 以编程方式访问所选项
• 处理选择更改
• 自定义多选分隔符
• 使用选择事件

涵盖主题：

• SelectionMode（Single、Multiple）
• SelectedItem、SelectedIndex、SelectedValue 属性
• 用于多选的 SelectedItems 集合
• SelectionChanged 事件
• 用于多选显示的 SeparatorString
• TextSelectionOnFocus 属性
• 以编程方式选择
• 带复选框的选择器列

弹出窗口自定义

📄 阅读： references/popup-customization.md

适用于：

• 自定义弹出窗口外观
• 配置弹出窗口大小和调整方式
• 设置弹出窗口背景和边框
• 处理弹出窗口事件
• 在下拉列表中添加自定义标题

涵盖主题：

• 弹出窗口外观（Background、BorderBrush、BorderThickness）
• 弹出窗口大小（PopupHeight、PopupWidth、Min/Max 值）
• 用于自动调整大小的 IsAutoPopupSize
• 使用调整大小手柄调整大小
• PopupContentTemplate 和 HeaderTemplate
• 弹出窗口事件（Opening、Opened、Closing、Closed）
• StaysOpen 属性
• 下拉列表标题中的自定义控件

键盘和无障碍功能

📄 阅读： references/keyboard-accessibility.md

适用于：

• 实现键盘导航
• 确保符合无障碍要求
• 设置 UI 自动化
• 配置编码 UI 测试
• 了解键盘快捷键

涵盖主题：

• 键盘快捷键（Enter、Esc、F4、Alt+Arrows、Up/Down）
• 键盘导航模式
• UI 自动化支持
• 编码 UI 测试的属性和方法
• QTP（Quick Test Professional）支持
• 无障碍功能

快速入门

基本实现

<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"
        xmlns:local="clr-namespace:YourNamespace">
    <Window.DataContext>
        <local:ViewModel/>
    </Window.DataContext>
    
    <Grid>
        <syncfusion:SfMultiColumnDropDownControl 
            x:Name="sfMultiColumn"
            Width="200"
            Height="30"
            ItemsSource="{Binding Orders}"
            DisplayMember="CustomerName"
            ValueMember="OrderID"
            SelectedIndex="0"/>
    </Grid>
</Window>

代码隐藏设置

using Syncfusion.UI.Xaml.Grid;
using System.Collections.ObjectModel;

namespace YourNamespace
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            
            // Create control programmatically
            SfMultiColumnDropDownControl sfMultiColumn = new SfMultiColumnDropDownControl();
            sfMultiColumn.Width = 200;
            sfMultiColumn.Height = 30;
            sfMultiColumn.ItemsSource = viewModel.Orders;
            sfMultiColumn.DisplayMember = "CustomerName";
            sfMultiColumn.ValueMember = "OrderID";
            
            // Add to layout
            Root_Grid.Children.Add(sfMultiColumn);
        }
    }
    
    // Data Model
    public class OrderInfo
    {
        public int OrderID { get; set; }
        public string CustomerName { get; set; }
        public string CustomerID { get; set; }
        public string Country { get; set; }
        
        public OrderInfo(int orderId, string customerName, string customerId, string country)
        {
            OrderID = orderId;
            CustomerName = customerName;
            CustomerID = customerId;
            Country = country;
        }
    }
    
    // ViewModel
    public class ViewModel
    {
        public ObservableCollection<OrderInfo> Orders { get; set; }
        
        public ViewModel()
        {
            Orders = new ObservableCollection<OrderInfo>
            {
                new OrderInfo(1001, "Maria Anders", "ALFKI", "Germany"),
                new OrderInfo(1002, "Ana Trujilo", "ANATR", "Mexico"),
                new OrderInfo(1003, "Thomas Hardy", "AROUT", "UK")
            };
        }
    }
}

常见模式

模式 1：带自动补全的可筛选下拉列表

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    AllowAutoComplete="True"
    AllowIncrementalFiltering="True"
    SearchCondition="Contains"
    SelectedIndex="0"/>

模式 2：多选下拉列表

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    SelectionMode="Multiple"
    SeparatorString=", "/>

访问所选项：

// Get all selected items
var selectedItems = sfMultiColumn.SelectedItems;

// Programmatically add selections
sfMultiColumn.SelectedItems.Add(orderItem);

模式 3：手动定义的自定义列

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="OrderID"
    ValueMember="OrderID"
    AutoGenerateColumns="False">
    <syncfusion:SfMultiColumnDropDownControl.Columns>
        <syncfusion:GridTextColumn MappingName="OrderID" HeaderText="Order ID" Width="100"/>
        <syncfusion:GridTextColumn MappingName="CustomerName" HeaderText="Customer" Width="150"/>
        <syncfusion:GridCurrencyColumn MappingName="Amount" HeaderText="Amount" Width="120"/>
        <syncfusion:GridTextColumn MappingName="Country" Width="100"/>
    </syncfusion:SfMultiColumnDropDownControl.Columns>
</syncfusion:SfMultiColumnDropDownControl>

模式 4：自定义弹出窗口外观

<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    PopupHeight="300"
    PopupWidth="500"
    PopupBackground="WhiteSmoke"
    PopupBorderBrush="SteelBlue"
    PopupBorderThickness="2"
    PopupDropDownGridBackground="White"
    IsAutoPopupSize="False"/>

关键属性

核心数据属性

• ItemsSource：下拉列表的数据源（IEnumerable）
• DisplayMember：编辑器中显示的属性路径
• ValueMember：SelectedValue 的属性路径
• SelectedItem：当前选中的数据对象
• SelectedIndex：所选项的索引（若未选择则为 -1）
• SelectedValue：根据 ValueMember 从 SelectedItem 获取的值
• SelectedItems：所选项的集合（多选模式）

筛选和编辑

• AllowAutoComplete：启用文本自动补全（默认值：false）
• AllowIncrementalFiltering：根据输入的文本筛选项（默认值：false）
• SearchCondition：筛选条件（StartsWith、Contains、Equals）
• AllowCaseSensitiveFiltering：区分大小写进行筛选（默认值：false）
• AllowDiacriticSensitiveFiltering：区分附加符号进行筛选（默认值：true）
• ReadOnly：将编辑器设为只读（默认值：false）
• AllowNullInput：允许空值（默认值：false）
• SearchText：编辑器中的当前文本（只读）

列配置

• AutoGenerateColumns：根据数据自动生成列（默认：true）
• AutoGenerateColumnMode：列生成模式（Reset、RetainOld、ResetAll、None）
• Columns：手动定义的列集合
• GridColumnSizer：列宽调整策略（Auto、Star、None）

选择

• SelectionMode：单选或多选
• SeparatorString：多选显示时使用的分隔符（默认：";"）
• TextSelectionOnFocus：获得焦点时自动选择文本（默认：false）

弹出窗口

• IsDropDownOpen：弹出窗口的打开/关闭状态
• PopupHeight/PopupWidth：弹出窗口尺寸
• PopupMinHeight/PopupMaxHeight：尺寸限制
• PopupMinWidth/PopupMaxWidth：尺寸限制
• IsAutoPopupSize：根据网格自动调整尺寸（默认：false）
• PopupBackground：弹出窗口背景画刷
• PopupBorderBrush：弹出窗口边框画刷
• PopupBorderThickness：弹出窗口边框粗细

行为

• AllowImmediatePopup：编辑时找到匹配项后打开弹出窗口
• AllowSpinOnMouseWheel：使用鼠标滚轮更改选择项（默认：true）

常见用例

1. 通过搜索选择产品

通过多列（ID、名称、类别、价格）显示产品目录，并允许用户通过产品名称搜索，支持自动补全。

2. 查找客户

在下拉列表中显示客户信息（名称、电子邮件、电话、城市），随着用户输入逐步筛选，并在编辑器中显示所选客户名称。

3. 分配多个项目

允许用户从列表中选择多个项目，列表显示项目代码、名称、状态和截止日期，并提供复选框。

4. 选择发票项目

下拉列表显示项目代码、描述、单价和库存水平等列，并支持按项目代码或描述筛选。

5. 员工目录

提供可搜索的员工列表，包含姓名、部门、电子邮件和电话号码等列，并支持根据员工姓名自动补全。

6. 选择报表参数

通过名称、类别和描述列显示可用报表，并允许用户筛选和选择报表以生成报表。

相关技能

• 实现 WPF 数据网格 - 了解下拉列表中使用的高级 SfDataGrid 功能
• WPF 数据绑定 - 通用 WPF 数据绑定模式
• WPF 主题 - 为组件应用主题

最佳实践

1. 恰当使用 ValueMember：将 ValueMember 设置为唯一标识符属性，以便可靠地跟踪选择项
2. 为大型数据集启用筛选：使用 AllowIncrementalFiltering 提高包含大量项目时的易用性
3. 手动定义列以便控制布局：设置 AutoGenerateColumns="False" 并定义列，确保布局可预测
4. 处理 SelectionChanged 事件：响应选择项变更，以更新依赖的 UI
5. 设置合理的弹出窗口尺寸：配置 PopupHeight/PopupWidth，或使用 IsAutoPopupSize 以优化显示效果
6. 考虑性能：对于非常大的数据集（>1000 个项目），实现虚拟化或服务器端筛选
7. 测试键盘导航：确保用户可以使用键盘快捷键高效导航
8. 提供清晰的 DisplayMember：选择能够让用户清楚识别项目的属性

故障排除

• 未显示列：确认 ItemsSource 已绑定且包含数据；检查 AutoGenerateColumns 设置
• 筛选不起作用：确保 AllowIncrementalFiltering="True"，并正确设置 DisplayMember
• 未显示自动补全：设置 AllowAutoComplete="True"，并确认数据中存在 DisplayMember 属性
• 未显示多选结果：设置 SelectionMode="Multiple"，并检查 SelectedItems 集合
• 弹出窗口尺寸不正确：调整 PopupHeight/PopupWidth，或启用 IsAutoPopupSize
• 大型数据导致性能问题：考虑使用数据虚拟化或限制显示的列