syncfusion-winforms-combobox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing ComboBoxes

组合框实现

This skill explains how to implement and customize the Syncfusion Windows Forms

SfComboBox

control.

本技能教程将讲解如何实现和自定义Syncfusion Windows Forms

SfComboBox

控件。

When to Use This Skill

何时使用本技能

Use when the user needs a combobox/dropdown control in Windows Forms applications
Use when implementing autocomplete functionality with Suggest, Append, or SuggestAppend modes
Use when enabling multi-selection with checkboxes or token-based selection
Use when binding combobox to data sources (lists, databases, LINQ to SQL)
Use when implementing filtering or sorting in dropdown lists
Use when customizing dropdown appearance, watermarks, or themes
Use when adding custom controls to dropdown headers/footers
Use when implementing token-based multi-selection (chip-style inputs)

当你需要在Windows Forms应用中使用组合框/下拉框控件时使用
当你需要实现支持Suggest、Append或SuggestAppend模式的自动补全功能时使用
当你需要启用带复选框或令牌式选择的多选功能时使用
当你需要将组合框绑定到数据源（列表、数据库、LINQ to SQL）时使用
当你需要在下拉列表中实现过滤或排序功能时使用
当你需要自定义下拉框外观、水印或主题时使用
当你需要向下拉框头部/底部添加自定义控件时使用
当你需要实现令牌式多选（芯片样式输入）时使用

Navigation Guide

导航指南

Follow the links below to open focused reference pages for each task.

点击下方链接打开各个任务的专用参考页面。

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly deployment and dependencies
Creating SfComboBox via designer or code
Basic data binding setup
Quick autocomplete example
Quick multi-selection example

📄 阅读： references/getting-started.md

程序集部署和依赖项
通过设计器或代码创建SfComboBox
基础数据绑定设置
快速自动补全示例
快速多选示例

Overview

概述

📄 Read: references/overview.md

Component features and capabilities
Comparison with ComboBoxAdv, MultiSelectionComboBox, ComboBoxAutoComplete
API comparison table
When to use SfComboBox vs alternatives

📄 阅读： references/overview.md

组件特性和能力
与ComboBoxAdv、MultiSelectionComboBox、ComboBoxAutoComplete的对比
API对比表
何时选择SfComboBox而非替代方案

Data Binding

数据绑定

📄 Read: references/data-binding.md

DataSource, DisplayMember, ValueMember properties
Binding to custom objects and collections
Binding from Microsoft Access database
Binding from LINQ to SQL classes
Complex data binding scenarios

📄 阅读： references/data-binding.md

DataSource、DisplayMember、ValueMember属性
绑定到自定义对象和集合
绑定Microsoft Access数据库
绑定LINQ to SQL类
复杂数据绑定场景

AutoComplete

自动补全

📄 Read: references/autocomplete.md

AutoCompleteMode: Suggest, Append, SuggestAppend
Case-sensitive autocomplete
AutoCompleteSuggestMode: StartsWith, Contains
Setting autocomplete delay
Complete code examples

📄 阅读： references/autocomplete.md

AutoCompleteMode：Suggest、Append、SuggestAppend
区分大小写的自动补全
AutoCompleteSuggestMode：StartsWith、Contains
设置自动补全延迟
完整代码示例

Selection

选择功能

📄 Read: references/selection.md

Single selection (SelectedIndex, SelectedValue, SelectedItem)
SelectedIndexChanged and SelectedValueChanged events
Multi-selection mode with checkboxes
Select all feature
Delimiter character customization
Tooltip for selected items
Clear button customization

📄 阅读： references/selection.md

单选（SelectedIndex、SelectedValue、SelectedItem）
SelectedIndexChanged和SelectedValueChanged事件
带复选框的多选模式
全选功能
分隔符自定义
选中项的提示框
清除按钮自定义

Token Support

令牌支持

📄 Read: references/token.md

EnableToken property for chip-style selection
Token appearance customization (TokenStyle)
Adding and removing tokens
Keyboard navigation for tokens
SelectedValueChanged event for token tracking

📄 阅读： references/token.md

用于芯片式选择的EnableToken属性
令牌外观自定义（TokenStyle）
添加和移除令牌
令牌的键盘导航
用于令牌跟踪的SelectedValueChanged事件

Filtering

过滤

📄 Read: references/filtering.md

Filter property with custom predicates
RefreshFilter method
Complete filtering example
Custom filter conditions

📄 阅读： references/filtering.md

支持自定义谓词的Filter属性
RefreshFilter方法
完整过滤示例
自定义过滤条件

Sorting

排序

📄 Read: references/sorting.md

SortDescriptors property
Ascending and descending sort
Custom comparer support

📄 阅读： references/sorting.md

SortDescriptors属性
升序和降序排序
自定义比较器支持

Dropdown Customization

下拉框自定义

📄 Read: references/dropdown.md

MaxDropDownItems for limiting visible items
AllowDropDownResize for resize gripper
DropDownOpening and DropDownClosing events
DropDownPosition customization
DropDownWidth customization
Loading custom header/footer controls
Complete custom control example

📄 阅读： references/dropdown.md

用于限制可见项数量的MaxDropDownItems
支持调整大小的AllowDropDownResize
DropDownOpening和DropDownClosing事件
DropDownPosition自定义
DropDownWidth自定义
加载自定义头部/底部控件
完整自定义控件示例

Watermark

水印

📄 Read: references/watermark.md

AllowNull property for null value support
Watermark text customization
WatermarkForeColor styling

📄 阅读： references/watermark.md

支持空值的AllowNull属性
水印文本自定义
水印文字颜色样式设置

Appearance & Styling

外观与样式

📄 Read: references/appearance.md

Visual styles and theming
BackColor, ForeColor customization
Border and font customization
Office 2016 themes

📄 阅读： references/appearance.md

视觉样式和主题
背景色、前景色自定义
边框和字体自定义
Office 2016主题

Editing

编辑功能

📄 Read: references/editing.md

DropDownStyle property
Edit behavior customization
Read-only mode

📄 阅读： references/editing.md

DropDownStyle属性
编辑行为自定义
只读模式

Item Height

选项高度

📄 Read: references/item-height.md

ItemHeight property
Customizing dropdown item heights

📄 阅读： references/item-height.md

ItemHeight属性
自定义下拉选项高度

Localization

本地化

📄 Read: references/localization.md

Culture-specific formatting
Resource file integration

📄 阅读： references/localization.md

特定文化格式适配
资源文件集成

UI Automation

UI自动化

📄 Read: references/ui-automation.md

Accessibility features
Screen reader support
Keyboard navigation

📄 阅读： references/ui-automation.md

无障碍功能
屏幕阅读器支持
键盘导航

Quick Start

快速入门

Minimal

SfComboBox

example (C#):

csharp

using Syncfusion.WinForms.ListView;

namespace WindowsFormsApp
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            
            // Create SfComboBox
            SfComboBox sfComboBox1 = new SfComboBox();
            sfComboBox1.Location = new Point(20, 20);
            sfComboBox1.Size = new Size(200, 28);
            
            // Bind data
            List<string> states = new List<string> { "Alaska", "Arizona", "California", "Colorado", "Delaware" };
            sfComboBox1.DataSource = states;
            
            this.Controls.Add(sfComboBox1);
        }
    }
}

With autocomplete:

csharp

sfComboBox1.AutoCompleteMode = AutoCompleteMode.SuggestAppend;
sfComboBox1.AutoCompleteSuggestMode = AutoCompleteSuggestMode.Contains;

With multi-selection:

csharp

sfComboBox1.ComboBoxMode = ComboBoxMode.MultiSelection;
sfComboBox1.AllowSelectAll = true;

最简

SfComboBox

示例（C#）：

csharp

using Syncfusion.WinForms.ListView;

namespace WindowsFormsApp
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            
            // Create SfComboBox
            SfComboBox sfComboBox1 = new SfComboBox();
            sfComboBox1.Location = new Point(20, 20);
            sfComboBox1.Size = new Size(200, 28);
            
            // Bind data
            List<string> states = new List<string> { "Alaska", "Arizona", "California", "Colorado", "Delaware" };
            sfComboBox1.DataSource = states;
            
            this.Controls.Add(sfComboBox1);
        }
    }
}

启用自动补全：

csharp

sfComboBox1.AutoCompleteMode = AutoCompleteMode.SuggestAppend;
sfComboBox1.AutoCompleteSuggestMode = AutoCompleteSuggestMode.Contains;

启用多选：

csharp

sfComboBox1.ComboBoxMode = ComboBoxMode.MultiSelection;
sfComboBox1.AllowSelectAll = true;

Common Patterns

常用模式

Pattern 1: Data Binding with Custom Objects

模式1：自定义对象的数据绑定

csharp

public class USState
{
    public string LongName { get; set; }
    public string ShortName { get; set; }
}

List<USState> states = new List<USState>
{
    new USState { LongName = "California", ShortName = "CA" },
    new USState { LongName = "Texas", ShortName = "TX" }
};

sfComboBox1.DataSource = states;
sfComboBox1.DisplayMember = "LongName";
sfComboBox1.ValueMember = "ShortName";

csharp

public class USState
{
    public string LongName { get; set; }
    public string ShortName { get; set; }
}

List<USState> states = new List<USState>
{
    new USState { LongName = "California", ShortName = "CA" },
    new USState { LongName = "Texas", ShortName = "TX" }
};

sfComboBox1.DataSource = states;
sfComboBox1.DisplayMember = "LongName";
sfComboBox1.ValueMember = "ShortName";

Pattern 2: Multi-Selection with Tokens

模式2：令牌式多选

csharp

sfComboBox1.EnableToken = true;
sfComboBox1.Style.TokenStyle.BackColor = Color.LightBlue;
sfComboBox1.Style.TokenStyle.BorderColor = Color.Blue;

csharp

sfComboBox1.EnableToken = true;
sfComboBox1.Style.TokenStyle.BackColor = Color.LightBlue;
sfComboBox1.Style.TokenStyle.BorderColor = Color.Blue;

Pattern 3: Custom Dropdown Header

模式3：自定义下拉框头部

csharp

sfComboBox1.DropDownListView.ShowHeader = true;
TextBox searchBox = new TextBox { Height = 25 };
sfComboBox1.DropDownListView.HeaderControl = searchBox;

csharp

sfComboBox1.DropDownListView.ShowHeader = true;
TextBox searchBox = new TextBox { Height = 25 };
sfComboBox1.DropDownListView.HeaderControl = searchBox;

Pattern 4: Filtering with Predicate

模式4：谓词过滤

csharp

sfComboBox1.DropDownListView.View.Filter = (data) =>
{
    return ((USState)data).LongName.StartsWith("C");
};
sfComboBox1.DropDownListView.View.RefreshFilter();

csharp

sfComboBox1.DropDownListView.View.Filter = (data) =>
{
    return ((USState)data).LongName.StartsWith("C");
};
sfComboBox1.DropDownListView.View.RefreshFilter();

Key Properties

核心属性

Property	Type	Description
DataSource	object	Bind to IEnumerable data source
DisplayMember	string	Property name to display
ValueMember	string	Property name for value
AutoCompleteMode	enum	Suggest, Append, SuggestAppend, None
ComboBoxMode	enum	SingleSelection, MultiSelection
EnableToken	bool	Enable token-based selection
AllowSelectAll	bool	Show "Select All" in multi-select
Watermark	string	Placeholder text when empty
MaxDropDownItems	int	Max visible items in dropdown
ShowClearButton	bool	Show clear button when selected
ThemeName	string	Apply visual theme

属性	类型	描述
DataSource	object	绑定到IEnumerable数据源
DisplayMember	string	要显示的属性名称
ValueMember	string	对应值的属性名称
AutoCompleteMode	enum	Suggest、Append、SuggestAppend、None
ComboBoxMode	enum	SingleSelection、MultiSelection
EnableToken	bool	启用令牌式选择
AllowSelectAll	bool	多选模式下显示“全选”选项
Watermark	string	控件为空时的占位文本
MaxDropDownItems	int	下拉框中最多可见的选项数量
ShowClearButton	bool	选中内容时显示清除按钮
ThemeName	string	应用视觉主题

Common Use Cases

常见使用场景

Use Case 1: Country/State Selector

场景1：国家/州选择器

Implement a country or state dropdown with autocomplete for quick selection in address forms.

在地址表单中实现带自动补全的国家/州下拉框，方便快速选择。

Use Case 2: Tag/Category Selection

场景2：标签/分类选择

Use multi-selection with tokens for selecting multiple tags or categories in content management systems.

在内容管理系统中使用带令牌的多选功能，选择多个标签或分类。

Use Case 3: Searchable Dropdown

场景3：可搜索下拉框

Add a search textbox in the dropdown header to filter large lists dynamically.

在下拉框头部添加搜索文本框，动态过滤大列表。

Use Case 4: Dependent Dropdowns

场景4：联动下拉框

Implement cascading dropdowns where the second dropdown filters based on the first selection.

实现级联下拉框，第二个下拉框的选项根据第一个下拉框的选择动态过滤。

Use Case 5: Custom Item Templates

场景5：自定义选项模板

Create custom visual representations for dropdown items with images or multiple text lines.

为下拉选项创建带图片或多行文本的自定义视觉展示效果。

Troubleshooting

故障排查

Issue: Autocomplete not working

Solution: Ensure

AutoCompleteMode

is set to

Suggest

Append

, or

SuggestAppend

(not

None

)

Issue: Multi-selection checkboxes not showing

Solution: Set

ComboBoxMode = ComboBoxMode.MultiSelection

Issue: DataSource not displaying items

Solution: Verify
```
DisplayMember
```
matches a public property name in your data objects

Issue: Tokens not appearing

Solution: Set
```
EnableToken = true
```
and select items from the dropdown

Issue: Dropdown not resizing

Solution: Check
```
AllowDropDownResize
```
property is
```
true
```
(default)

Issue: SelectedValue returns null

Solution: Ensure
```
ValueMember
```
is set correctly, or use
```
SelectedItem
```
directly

Issue: Filtering not working

Solution: Call
```
DropDownListView.View.RefreshFilter()
```
after setting the Filter predicate

问题： 自动补全不生效

解决方案： 确保
```
AutoCompleteMode
```
设置为
```
Suggest
```
、
```
Append
```
或
```
SuggestAppend
```
（而非
```
None
```
）

问题： 多选复选框不显示

解决方案： 设置

ComboBoxMode = ComboBoxMode.MultiSelection

问题： 数据源不显示选项

解决方案： 确认
```
DisplayMember
```
与数据对象中的公共属性名称匹配

问题： 令牌不显示

解决方案： 设置
```
EnableToken = true
```
并从下拉框中选择选项

问题： 下拉框无法调整大小

解决方案： 检查
```
AllowDropDownResize
```
属性是否为
```
true
```
（默认值）

问题： SelectedValue返回null

解决方案： 确保
```
ValueMember
```
设置正确，或直接使用
```
SelectedItem
```

问题： 过滤不生效

解决方案： 设置Filter谓词后调用
```
DropDownListView.View.RefreshFilter()
```

syncfusion-winforms-combobox

Original

Translation

Implementing ComboBoxes

组合框实现

When to Use This Skill

何时使用本技能

Navigation Guide

导航指南

Getting Started

入门指南

Overview

概述

Data Binding

数据绑定

AutoComplete

自动补全

Selection

选择功能

Token Support

令牌支持

Filtering

过滤

Sorting

排序

Dropdown Customization

下拉框自定义

Watermark

水印

Appearance & Styling

外观与样式

Editing

编辑功能

Item Height

选项高度

Localization

本地化

UI Automation

UI自动化

Quick Start

快速入门

Common Patterns

常用模式

Pattern 1: Data Binding with Custom Objects

模式1：自定义对象的数据绑定

Pattern 2: Multi-Selection with Tokens

模式2：令牌式多选

Pattern 3: Custom Dropdown Header

模式3：自定义下拉框头部

Pattern 4: Filtering with Predicate

模式4：谓词过滤

Key Properties

核心属性

Common Use Cases

常见使用场景

Use Case 1: Country/State Selector

场景1：国家/州选择器

Use Case 2: Tag/Category Selection

场景2：标签/分类选择

Use Case 3: Searchable Dropdown

场景3：可搜索下拉框

Use Case 4: Dependent Dropdowns

场景4：联动下拉框

Use Case 5: Custom Item Templates

场景5：自定义选项模板

Troubleshooting

故障排查

Related Skills

相关技能