Back to Details

syncfusion-wpf-multi-column-dropdown

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion WPF Multi Column Dropdown

实现Syncfusion WPF多列下拉控件

The SfMultiColumnDropDownControl combines a TextBox editor with a powerful SfDataGrid to provide a searchable, filterable dropdown control that displays multiple columns. It supports autocomplete, incremental filtering, single and multi-selection modes, and extensive customization options.
SfMultiColumnDropDownControl 将文本框编辑器与功能强大的SfDataGrid相结合，提供了一个可搜索、可筛选的下拉控件，能够显示多列数据。它支持自动完成、增量筛选、单选和多选模式，以及丰富的自定义选项。

Component Overview

组件概述

SfMultiColumnDropDownControl is a composite control that embeds a SfDataGrid within a dropdown popup, enabling users to:
  • Search and filter items by typing in the editor
  • View multiple columns of data in the dropdown
  • Select single or multiple items from the grid
  • Autocomplete text based on DisplayMember
  • Customize popup appearance, columns, and behavior
Key capabilities:
  • Data binding to any IEnumerable source
  • Automatic or manual column generation
  • Case-sensitive and diacritic-sensitive filtering
  • Complex and indexer property binding
  • Keyboard navigation and accessibility support
  • Resizable popup with customizable appearance
SfMultiColumnDropDownControl是一个复合控件，在下拉弹出窗口中嵌入了SfDataGrid，允许用户：
  • 搜索和筛选：在编辑器中输入内容即可筛选项目
  • 查看多列数据：在下拉窗口中展示多列信息
  • 选择单个或多个项目：从网格中选择所需条目
  • 自动完成：基于DisplayMember自动补全文本
  • 自定义：自定义弹出窗口外观、列和行为
核心功能：
  • 可绑定到任何IEnumerable数据源
  • 自动或手动生成列
  • 区分大小写和区分变音符号的筛选
  • 复杂属性和索引器属性绑定
  • 键盘导航和辅助功能支持
  • 可调整大小的弹出窗口，支持自定义外观

When to Use This Skill

何时使用此技能

Use this skill when you need to:
  • Create a WPF dropdown that displays multiple columns of data
  • Implement searchable/filterable dropdown lists with grid view
  • Build dropdown controls with autocomplete and incremental filtering
  • Allow users to select items from a multi-column data grid
  • Create editable dropdowns with complex data binding
  • Implement dropdowns with single or multi-selection support
  • Customize dropdown popup appearance and behavior
  • Add keyboard navigation to dropdown controls
在以下场景中可使用此技能：
  • 创建可显示多列数据的WPF下拉控件
  • 实现带网格视图的可搜索/可筛选下拉列表
  • 构建带自动完成和增量筛选功能的下拉控件
  • 允许用户从多列数据网格中选择项目
  • 创建支持复杂数据绑定的可编辑下拉菜单
  • 实现支持单选或多选的下拉控件
  • 自定义下拉弹出窗口的外观和行为
  • 为下拉控件添加键盘导航

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
Use this when:
  • Setting up the control for the first time
  • Understanding assembly requirements
  • Adding control via Designer, XAML, or C#
  • Creating basic data models
  • Binding initial ItemsSource
  • Defining DisplayMember and ValueMember
Topics covered:
  • Assembly deployment (Syncfusion.Data.WPF, Syncfusion.SfGrid.WPF)
  • Creating WPF application with SfMultiColumnDropDownControl
  • Adding control via Designer, XAML, and code-behind
  • Basic ItemsSource binding
  • DisplayMember and ValueMember configuration
  • Theme support
📄 阅读： references/getting-started.md
适用于以下场景：
  • 首次设置控件
  • 了解程序集要求
  • 通过设计器、XAML或C#添加控件
  • 创建基础数据模型
  • 绑定初始ItemsSource
  • 定义DisplayMember和ValueMember
涵盖主题：
  • 程序集部署（Syncfusion.Data.WPF、Syncfusion.SfGrid.WPF）
  • 使用SfMultiColumnDropDownControl创建WPF应用
  • 通过设计器、XAML和代码后台添加控件
  • 基础ItemsSource绑定
  • DisplayMember和ValueMember配置
  • 主题支持

Data Binding

数据绑定

📄 Read: references/data-binding.md
Use this when:
  • Binding data to the dropdown control
  • Understanding DisplayMember vs ValueMember
  • Working with complex properties
  • Using indexer properties
  • Accessing SelectedItem and SelectedValue
Topics covered:
  • ItemsSource property usage
  • DisplayMember (visual presentation in editor)
  • ValueMember (value for SelectedValue property)
  • Binding collections in XAML and code-behind
  • Complex property binding (e.g., 
    customerDetails.Name
    )
  • Indexer property binding (e.g., 
    Country[0]
    )
📄 阅读： references/data-binding.md
适用于以下场景：
  • 为下拉控件绑定数据
  • 理解DisplayMember与ValueMember的区别
  • 处理复杂属性
  • 使用索引器属性
  • 访问SelectedItem和SelectedValue
涵盖主题：
  • ItemsSource属性的使用
  • DisplayMember（编辑器中的可视化展示）
  • ValueMember（SelectedValue属性对应的值）
  • 在XAML和代码后台中绑定集合
  • 复杂属性绑定（例如：
    customerDetails.Name
    ）
  • 索引器属性绑定（例如：
    Country[0]
    ）

Columns Configuration

列配置

📄 Read: references/columns.md
Use this when:
  • Configuring dropdown grid columns
  • Auto-generating or manually defining columns
  • Customizing column types and templates
  • Handling AutoGeneratingColumn event
  • Setting column sizing and width
Topics covered:
  • AutoGenerateColumns property
  • AutoGenerateColumnMode (Reset, RetainOld, ResetAll, None)
  • Manually defining columns collection
  • Column types (GridTextColumn, GridCurrencyColumn, etc.)
  • AutoGeneratingColumn event for customization
  • Column templates (HeaderTemplate, CellTemplate)
  • GridColumnSizer for width management
📄 阅读： references/columns.md
适用于以下场景：
  • 配置下拉网格的列
  • 自动生成或手动定义列
  • 自定义列类型和模板
  • 处理AutoGeneratingColumn事件
  • 设置列的大小和宽度
涵盖主题：
  • AutoGenerateColumns属性
  • AutoGenerateColumnMode（Reset、RetainOld、ResetAll、None）
  • 手动定义列集合
  • 列类型（GridTextColumn、GridCurrencyColumn等）
  • 用于自定义的AutoGeneratingColumn事件
  • 列模板（HeaderTemplate、CellTemplate）
  • 用于宽度管理的GridColumnSizer

Editing and Filtering

编辑与筛选

📄 Read: references/editing-autocomplete.md
Use this when:
  • Enabling autocomplete functionality
  • Implementing incremental filtering
  • Configuring search conditions
  • Filtering based on multiple columns
  • Customizing editor behavior
Topics covered:
  • AllowAutoComplete for text suggestions
  • AllowIncrementalFiltering for live filtering
  • SearchCondition (StartsWith, Contains, Equals)
  • AllowCaseSensitiveFiltering option
  • AllowDiacriticSensitiveFiltering option
  • Editor properties (ReadOnly, AllowNullInput, AllowSpinOnMouseWheel)
  • FilterRecord method override for custom filtering
  • SearchText property for multi-column filtering
📄 阅读： references/editing-autocomplete.md
适用于以下场景：
  • 启用自动完成功能
  • 实现增量筛选
  • 配置搜索条件
  • 基于多列进行筛选
  • 自定义编辑器行为
涵盖主题：
  • 用于文本建议的AllowAutoComplete
  • 用于实时筛选的AllowIncrementalFiltering
  • SearchCondition（StartsWith、Contains、Equals）
  • AllowCaseSensitiveFiltering选项
  • AllowDiacriticSensitiveFiltering选项
  • 编辑器属性（ReadOnly、AllowNullInput、AllowSpinOnMouseWheel）
  • 用于自定义筛选的FilterRecord方法重写
  • 用于多列筛选的SearchText属性

Selection

选择功能

📄 Read: references/selection.md
Use this when:
  • Implementing single or multi-selection
  • Accessing selected items programmatically
  • Handling selection changes
  • Customizing multi-select separator
  • Working with selection events
Topics covered:
  • SelectionMode (Single, Multiple)
  • SelectedItem, SelectedIndex, SelectedValue properties
  • SelectedItems collection for multi-select
  • SelectionChanged event
  • SeparatorString for multi-select display
  • TextSelectionOnFocus property
  • Programmatic selection
  • Selector column with checkboxes
📄 阅读： references/selection.md
适用于以下场景：
  • 实现单选或多选
  • 以编程方式访问选中项目
  • 处理选择变更
  • 自定义多选分隔符
  • 处理选择事件
涵盖主题：
  • SelectionMode（Single、Multiple）
  • SelectedItem、SelectedIndex、SelectedValue属性
  • 用于多选的SelectedItems集合
  • SelectionChanged事件
  • 用于多选显示的SeparatorString
  • TextSelectionOnFocus属性
  • 编程式选择
  • 带复选框的选择器列

Popup Customization

弹出窗口自定义

📄 Read: references/popup-customization.md
Use this when:
  • Customizing popup appearance
  • Configuring popup size and resizing
  • Setting popup background and borders
  • Handling popup events
  • Adding custom headers to dropdown
Topics covered:
  • Popup appearance (Background, BorderBrush, BorderThickness)
  • Popup sizing (PopupHeight, PopupWidth, Min/Max values)
  • IsAutoPopupSize for automatic sizing
  • Resizing with resize thumb
  • PopupContentTemplate and HeaderTemplate
  • Popup events (Opening, Opened, Closing, Closed)
  • StaysOpen property
  • Custom control in dropdown header
📄 阅读： references/popup-customization.md
适用于以下场景：
  • 自定义弹出窗口外观
  • 配置弹出窗口大小和调整功能
  • 设置弹出窗口背景和边框
  • 处理弹出窗口事件
  • 向下拉菜单添加自定义标题
涵盖主题：
  • 弹出窗口外观（Background、BorderBrush、BorderThickness）
  • 弹出窗口大小（PopupHeight、PopupWidth、最小/最大值）
  • 用于自动调整大小的IsAutoPopupSize
  • 使用调整手柄调整大小
  • PopupContentTemplate和HeaderTemplate
  • 弹出窗口事件（Opening、Opened、Closing、Closed）
  • StaysOpen属性
  • 下拉菜单标题中的自定义控件

Keyboard and Accessibility

键盘与辅助功能

📄 Read: references/keyboard-accessibility.md
Use this when:
  • Implementing keyboard navigation
  • Ensuring accessibility compliance
  • Setting up UI automation
  • Configuring coded UI tests
  • Understanding keyboard shortcuts
Topics covered:
  • Keyboard shortcuts (Enter, Esc, F4, Alt+Arrows, Up/Down)
  • Keyboard navigation patterns
  • UI Automation support
  • Coded UI Test properties and methods
  • QTP (Quick Test Professional) support
  • Accessibility features
📄 阅读： references/keyboard-accessibility.md
适用于以下场景：
  • 实现键盘导航
  • 确保辅助功能合规
  • 设置UI自动化
  • 配置编码UI测试
  • 了解键盘快捷键
涵盖主题：
  • 键盘快捷键（Enter、Esc、F4、Alt+方向键、上下键）
  • 键盘导航模式
  • UI自动化支持
  • 编码UI测试属性和方法
  • QTP（Quick Test Professional）支持
  • 辅助功能特性

Quick Start

快速开始

Basic Implementation

基础实现

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

Code-Behind Setup

代码后台设置

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

Common Patterns

常见模式

Pattern 1: Filterable Dropdown with Autocomplete

模式1：带自动完成的可筛选下拉框

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

Pattern 2: Multi-Selection Dropdown

模式2：多选下拉框

xml
<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    SelectionMode="Multiple"
    SeparatorString=", "/>
Access selected items:
csharp
// Get all selected items
var selectedItems = sfMultiColumn.SelectedItems;

// Programmatically add selections
sfMultiColumn.SelectedItems.Add(orderItem);
xml
<syncfusion:SfMultiColumnDropDownControl 
    x:Name="sfMultiColumn"
    ItemsSource="{Binding Orders}"
    DisplayMember="CustomerName"
    ValueMember="OrderID"
    SelectionMode="Multiple"
    SeparatorString=", "/>
访问选中项目：
csharp
// Get all selected items
var selectedItems = sfMultiColumn.SelectedItems;

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

Pattern 3: Custom Columns with Manual Definition

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

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

Pattern 4: Customized Popup Appearance

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

xml
<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"/>
xml
<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"/>

Key Properties

核心属性

Core Data Properties

核心数据属性

  • ItemsSource: Data source for the dropdown (IEnumerable)
  • DisplayMember: Property path displayed in the editor
  • ValueMember: Property path for SelectedValue
  • SelectedItem: Currently selected data object
  • SelectedIndex: Index of selected item (-1 if none)
  • SelectedValue: Value from SelectedItem based on ValueMember
  • SelectedItems: Collection of selected items (multi-select mode)
  • ItemsSource：下拉框的数据源（IEnumerable类型）
  • DisplayMember：编辑器中显示的属性路径
  • ValueMember：SelectedValue对应的属性路径
  • SelectedItem：当前选中的数据对象
  • SelectedIndex：选中项目的索引（无选中项时为-1）
  • SelectedValue：基于ValueMember从SelectedItem中获取的值
  • SelectedItems：选中项目的集合（多选模式下）

Filtering & Editing

筛选与编辑

  • AllowAutoComplete: Enable text auto-completion (default: false)
  • AllowIncrementalFiltering: Filter items based on typed text (default: false)
  • SearchCondition: Filter condition (StartsWith, Contains, Equals)
  • AllowCaseSensitiveFiltering: Case-sensitive filtering (default: false)
  • AllowDiacriticSensitiveFiltering: Diacritic-sensitive filtering (default: true)
  • ReadOnly: Make editor read-only (default: false)
  • AllowNullInput: Allow null values (default: false)
  • SearchText: Current text in editor (read-only)
  • AllowAutoComplete：启用文本自动完成（默认值：false）
  • AllowIncrementalFiltering：根据输入文本筛选项目（默认值：false）
  • SearchCondition：筛选条件（StartsWith、Contains、Equals）
  • AllowCaseSensitiveFiltering：区分大小写的筛选（默认值：false）
  • AllowDiacriticSensitiveFiltering：区分变音符号的筛选（默认值：true）
  • ReadOnly：设置编辑器为只读（默认值：false）
  • AllowNullInput：允许空值输入（默认值：false）
  • SearchText：编辑器中的当前文本（只读）

Column Configuration

列配置

  • AutoGenerateColumns: Auto-generate columns from data (default: true)
  • AutoGenerateColumnMode: Column generation mode (Reset, RetainOld, ResetAll, None)
  • Columns: Collection of manually defined columns
  • GridColumnSizer: Column width sizing strategy (Auto, Star, None)
  • AutoGenerateColumns：从数据中自动生成列（默认值：true）
  • AutoGenerateColumnMode：列生成模式（Reset、RetainOld、ResetAll、None）
  • Columns：手动定义的列集合
  • GridColumnSizer：列宽调整策略（Auto、Star、None）

Selection

选择功能

  • SelectionMode: Single or Multiple selection
  • SeparatorString: Separator for multi-select display (default: ";")
  • TextSelectionOnFocus: Auto-select text on focus (default: false)
  • SelectionMode：单选或多选模式
  • SeparatorString：多选显示的分隔符（默认值：";"）
  • TextSelectionOnFocus：获取焦点时自动选中文本（默认值：false）

Popup

弹出窗口

  • IsDropDownOpen: Popup open/closed state
  • PopupHeight/PopupWidth: Popup dimensions
  • PopupMinHeight/PopupMaxHeight: Size constraints
  • PopupMinWidth/PopupMaxWidth: Size constraints
  • IsAutoPopupSize: Auto-size based on grid (default: false)
  • PopupBackground: Popup background brush
  • PopupBorderBrush: Popup border brush
  • PopupBorderThickness: Popup border thickness
  • IsDropDownOpen：弹出窗口的打开/关闭状态
  • PopupHeight/PopupWidth：弹出窗口的尺寸
  • PopupMinHeight/PopupMaxHeight：尺寸限制
  • PopupMinWidth/PopupMaxWidth：尺寸限制
  • IsAutoPopupSize：基于网格自动调整大小（默认值：false）
  • PopupBackground：弹出窗口的背景画刷
  • PopupBorderBrush：弹出窗口的边框画刷
  • PopupBorderThickness：弹出窗口的边框厚度

Behavior

行为

  • AllowImmediatePopup: Open popup when match found during editing
  • AllowSpinOnMouseWheel: Change selection with mouse wheel (default: true)
  • AllowImmediatePopup：编辑过程中匹配到项目时立即打开弹出窗口
  • AllowSpinOnMouseWheel：使用鼠标滚轮切换选中项（默认值：true）

Common Use Cases

常见使用场景

1. Product Selection with Search

1. 带搜索功能的产品选择

Display product catalog with multiple columns (ID, Name, Category, Price), allow users to search by product name with autocomplete.
显示包含多列（ID、名称、分类、价格）的产品目录，允许用户通过产品名称进行搜索并自动完成。

2. Customer Lookup

2. 客户查找

Show customer information in dropdown (Name, Email, Phone, City), filter incrementally as user types, display selected customer name in editor.
在下拉框中显示客户信息（名称、邮箱、电话、城市），用户输入时进行增量筛选，编辑器中显示选中客户的名称。

3. Multi-Project Assignment

3. 多项目分配

Allow users to select multiple projects from a list showing project code, name, status, and deadline with checkboxes.
允许用户从显示项目代码、名称、状态和截止日期的列表中选择多个项目，支持复选框。

4. Invoice Item Selection

4. 发票项目选择

Dropdown showing items with columns for item code, description, unit price, and stock level, with filtering by item code or description.
下拉框中显示包含项目代码、描述、单价和库存水平的项目，支持按项目代码或描述进行筛选。

5. Employee Directory

5. 员工目录

Searchable employee list with columns for name, department, email, and phone number, with autocomplete on employee name.
可搜索的员工列表，包含姓名、部门、邮箱和电话号码列，支持按员工姓名自动完成。

6. Report Parameter Selection

6. 报表参数选择

Display available reports with name, category, and description columns, allow filtering and selection for report generation.
显示可用报表的名称、分类和描述列，允许筛选和选择以生成报表。

Related Skills

相关技能

  • Implementing WPF Data Grids - For advanced SfDataGrid features used in dropdown
  • WPF Data Binding - General WPF data binding patterns
  • WPF Theming - Applying themes to components
  • 实现WPF数据网格 - 了解下拉框中使用的高级SfDataGrid功能
  • WPF数据绑定 - 通用WPF数据绑定模式
  • WPF主题 - 为组件应用主题

Best Practices

最佳实践

  1. Use ValueMember appropriately: Set ValueMember to a unique identifier property for reliable selection tracking
  2. Enable filtering for large datasets: Use AllowIncrementalFiltering to improve usability with many items
  3. Define columns manually for control: Set AutoGenerateColumns="False" and define columns for predictable layout
  4. Handle SelectionChanged event: Respond to selection changes for dependent UI updates
  5. Set reasonable popup sizes: Configure PopupHeight/PopupWidth or use IsAutoPopupSize for optimal display
  6. Consider performance: For very large datasets (>1000 items), implement virtualization or server-side filtering
  7. Test keyboard navigation: Ensure users can navigate efficiently with keyboard shortcuts
  8. Provide clear DisplayMember: Choose a property that clearly identifies items to users
  1. 合理使用ValueMember：将ValueMember设置为唯一标识符属性，以确保可靠的选择跟踪
  2. 为大数据集启用筛选：使用AllowIncrementalFiltering提升大数据集的可用性
  3. 手动定义列以实现控制：设置AutoGenerateColumns="False"并手动定义列，以获得可预测的布局
  4. 处理SelectionChanged事件：响应选择变更以更新相关UI
  5. 设置合理的弹出窗口大小：配置PopupHeight/PopupWidth或启用IsAutoPopupSize以获得最佳显示效果
  6. 考虑性能：对于超大数据集（>1000条），实现虚拟化或服务器端筛选
  7. 测试键盘导航：确保用户可以通过键盘快捷键高效导航
  8. 提供清晰的DisplayMember：选择能让用户清晰识别项目的属性

Troubleshooting

故障排除

  • Columns not showing: Verify ItemsSource is bound and contains data; check AutoGenerateColumns setting
  • Filtering not working: Ensure AllowIncrementalFiltering="True" and DisplayMember is set correctly
  • Autocomplete not appearing: Set AllowAutoComplete="True" and verify DisplayMember property exists in data
  • Multi-select not visible: Set SelectionMode="Multiple" and check SelectedItems collection
  • Popup not sizing correctly: Adjust PopupHeight/PopupWidth or enable IsAutoPopupSize
  • Performance issues with large data: Consider data virtualization or limit displayed columns
  • 列未显示：验证ItemsSource已绑定且包含数据；检查AutoGenerateColumns设置
  • 筛选不生效：确保AllowIncrementalFiltering="True"且DisplayMember设置正确
  • 自动完成未出现：设置AllowAutoComplete="True"并验证数据中存在DisplayMember属性
  • 多选不可见：设置SelectionMode="Multiple"并检查SelectedItems集合
  • 弹出窗口大小不正确：调整PopupHeight/PopupWidth或启用IsAutoPopupSize
  • 大数据集性能问题：考虑数据虚拟化或限制显示的列数