syncfusion-winforms-combobox

实现组合框

本技能介绍如何实现和自定义 Syncfusion Windows Forms SfComboBox 控件。

何时使用本技能

• 用户需要在 Windows Forms 应用程序中使用组合框／下拉框控件时
• 实现 Suggest、Append 或 SuggestAppend 模式的自动完成时
• 启用复选框多选或基于标记的选择时
• 将组合框绑定到数据源（列表、数据库、LINQ to SQL）时
• 实现下拉列表筛选或排序时
• 自定义下拉框外观、水印或主题时
• 向下拉框标题或页脚添加自定义控件时
• 实现基于标记的多选（标签样式输入框）时

导航指南

按照以下链接打开各项任务对应的参考页面。

入门

📄 阅读： references/getting-started.md

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

概述

📄 阅读： references/overview.md

• 组件功能和特性
• 与 ComboBoxAdv、MultiSelectionComboBox、ComboBoxAutoComplete 的比较
• API 比较表
• 何时选择 SfComboBox 而非其他控件

数据绑定

📄 阅读： references/data-binding.md

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

自动完成

📄 阅读： references/autocomplete.md

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

选择

📄 阅读： references/selection.md

• 单选（SelectedIndex、SelectedValue、SelectedItem）
• SelectedIndexChanged 和 SelectedValueChanged 事件
• 使用复选框进行多选
• 全选功能
• 自定义分隔符
• 所选项的工具提示
• 自定义清除按钮

标记支持

📄 阅读： references/token.md

• 使用 EnableToken 属性启用标签样式选择
• 自定义标记外观（TokenStyle）
• 添加和移除标记
• 标记的键盘导航
• 使用 SelectedValueChanged 事件跟踪标记

筛选

📄 阅读： references/filtering.md

• 使用自定义谓词设置 Filter 属性
• RefreshFilter 方法
• 完整筛选示例
• 自定义筛选条件

排序

📄 阅读： references/sorting.md

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

下拉框自定义

📄 阅读： references/dropdown.md

• 使用 MaxDropDownItems 限制可见项
• 使用 AllowDropDownResize 启用调整大小的拖动柄
• DropDownOpening 和 DropDownClosing 事件
• 自定义 DropDownPosition
• 自定义 DropDownWidth
• 加载自定义标题／页脚控件
• 完整的自定义控件示例

水印

📄 阅读： references/watermark.md

• 使用 AllowNull 属性支持空值
• 自定义水印文本
• 设置 WatermarkForeColor 样式

外观与样式

📄 阅读： references/appearance.md

• 视觉样式和主题
• 自定义 BackColor、ForeColor
• 自定义边框和字体
• Office 2016 主题

编辑

📄 阅读： references/editing.md

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

项高度

📄 阅读： references/item-height.md

• ItemHeight 属性
• 自定义下拉框项的高度

本地化

📄 阅读： references/localization.md

• 特定文化格式
• 资源文件集成

UI 自动化

📄 阅读： references/ui-automation.md

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

快速入门

最简 SfComboBox 示例（C#）：

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

启用自动完成：

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

启用多选：

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

常见模式

模式 1：使用自定义对象进行数据绑定

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

模式 2：使用令牌进行多选

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

模式 3：自定义下拉列表标题

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

模式 4：使用谓词进行筛选

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

关键属性

属性	类型	描述
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	应用视觉主题

常见用例

用例 1：国家/州选择器

在地址表单中实现带自动完成的国家或州下拉列表，以便快速选择。

用例 2：标签/类别选择

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

用例 3：可搜索下拉列表

在下拉列表标题中添加搜索文本框，以动态筛选大型列表。

用例 4：级联下拉列表

实现级联下拉列表，让第二个下拉列表根据第一个列表中的选择进行筛选。

用例 5：自定义项目模板

为下拉列表中的项目创建自定义视觉呈现，可包含图像或多行文本。

故障排除

问题： 自动完成不起作用

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

问题： 未显示多选复选框

• 解决方案： 设置 ComboBoxMode = ComboBoxMode.MultiSelection

问题： DataSource 未显示项目

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

问题： 未显示令牌

• 解决方案： 设置 EnableToken = true，并从下拉列表中选择项目

问题： 下拉列表无法调整大小

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

问题： SelectedValue 返回 null

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

问题： 筛选不起作用

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