登录 注册
下拉框控件ComboBoxEx 公开 发布于 2026-09-11 阅读 29

下拉框控件ComboBoxEx

ComboBoxEx 是一个功能丰富的下拉框控件，支持多种样式、圆角边框、自定义颜色、前缀文本等功能。适用于选项选择、数据筛选等场景。

ComboBoxEx 下拉框控件

控件名称

ComboBoxEx

中文名称

下拉框控件

控件优点

ComboBoxEx 是一个功能丰富的下拉框控件，支持多种样式、圆角边框、自定义颜色、前缀文本等功能。适用于选项选择、数据筛选等场景。

主要特性

  • 多种样式：支持下拉框、下拉列表、简单模式三种样式
  • 圆角边框：支持自定义圆角半径
  • 自定义颜色：支持自定义边框、背景、悬停等颜色
  • 前缀文本：支持在选择框左侧显示前缀文本
  • 自动调整：支持自动调整下拉列表宽度
  • 占位符：支持显示占位符文本
  • 搜索过滤：支持下拉面板搜索过滤功能

重要参数说明

基本属性

属性名 类型 默认值 说明
DropDownStyle ComboBoxExStyle DropDownList 下拉框样式
SelectedIndex int -1 选中项索引
SelectedItem object null 选中项（对象类型）
SelectedValue string null 选中项的字符串值
Items ObjectCollection - 下拉项集合

下拉框样式（ComboBoxExStyle）

样式值 说明 占位符支持 前缀文本支持
DropDown 下拉框 - 可编辑，文本可输入 ✓ 显示在文本框内 ✓ 显示在文本框左侧
DropDownList 下拉列表 - 不可编辑，只能选择 ✓ 显示在控件中央 ✓ 显示在控件左侧
Simple 简单模式 - 下拉列表始终显示 ✓ 显示在控件中央 ✓ 显示在控件左侧

外观属性

属性名 类型 默认值 说明
BorderRadius int 5 边框圆角
BorderColor Color Gray 边框颜色
DropDownBackColor Color White 下拉背景色
ItemHoverColor Color 230, 240, 250 项悬停颜色
ItemSelectedColor Color 200, 220, 240 项选中颜色
ItemHeight int 25 项高度
ListBoxHeight int 150 下拉列表高度

前缀文本属性

属性名 类型 默认值 说明
PrefixText string "" 前缀文本，显示在选择框左侧
PrefixTextColor Color Gray 前缀文本颜色

其他属性

属性名 类型 默认值 说明
ShowDropDownArrow bool true 是否显示下拉箭头
Placeholder string "" 占位符文本
PlaceholderColor Color Gray 占位符颜色
AutoSelectFirstItem bool true 是否自动选中第一项
AutoSizeDropDownWidth bool false 是否自动调整下拉列表宽度
EnableSearch bool false 是否启用下拉面板搜索过滤功能

重要事件

事件名 说明
SelectedIndexChanged 选中项改变时触发
DropDown 下拉列表打开时触发
DropDownClosed 下拉列表关闭时触发

使用示例

基本使用

// 创建下拉框
ComboBoxEx comboBox = new ComboBoxEx();
comboBox.Size = new Size(200, 32);
this.Controls.Add(comboBox);

// 添加项
comboBox.Items.Add("选项1");
comboBox.Items.Add("选项2");
comboBox.Items.Add("选项3");

// 选中项改变事件
comboBox.SelectedIndexChanged += (sender, e) =>
{
    Console.WriteLine($"选中：{comboBox.SelectedItem}");
};

不同样式

// 下拉列表（默认）
comboBox1.DropDownStyle = ComboBoxEx.ComboBoxExStyle.DropDownList;

// 下拉框（可编辑）
comboBox2.DropDownStyle = ComboBoxEx.ComboBoxExStyle.DropDown;

// 简单模式
comboBox3.DropDownStyle = ComboBoxEx.ComboBoxExStyle.Simple;

圆角边框

// 设置圆角
comboBox.BorderRadius = 8;

// 直角
comboBox.BorderRadius = 0;

颜色自定义

// 设置颜色
comboBox.BorderColor = Color.Blue;
comboBox.DropDownBackColor = Color.White;
comboBox.ItemHoverColor = Color.LightBlue;
comboBox.ItemSelectedColor = Color.Blue;

前缀文本

// 设置前缀文本（显示在选择框左侧）
comboBox.PrefixText = "位置";
comboBox.PrefixTextColor = Color.Gray;

// 前缀文本会自动挤压右侧内容区域
// 适用于需要标注下拉框含义的场景

说明：

  • 所有三种样式（DropDown、DropDownList、Simple）都支持前缀文本显示
  • 前缀文本显示在控件左侧，右侧面板用于显示选中项或占位符
  • 前缀文本宽度会根据内容自动计算，确保完整显示
  • 设置前缀文本后，右侧内容区域会自动调整位置

使用场景：

  • 标注下拉框用途：位置、状态、类型等
  • 表单中需要明确标识字段含义
  • 与输入框的标签风格保持一致

占位符（水印）

// 设置占位符
comboBox.Placeholder = "请选择...";
comboBox.PlaceholderColor = Color.Gray;

说明：

  • 所有三种样式（DropDown、DropDownList、Simple）都支持占位符显示
  • DropDown 样式下，占位符显示在可编辑文本框内
  • DropDownList 和 Simple 样式下，占位符显示在控件中央
  • 当控件获得焦点或选择项后，占位符自动隐藏

自动选中

// 自动选中第一项（默认）
comboBox.AutoSelectFirstItem = true;

// 不自动选中
comboBox.AutoSelectFirstItem = false;

绑定数据

// 绑定到数据源
comboBox.DataSource = dataSource;
comboBox.DisplayMember = "Name";
comboBox.ValueMember = "Id";

获取选中值（字符串）

// 获取选中项的字符串值
string value = comboBox.SelectedValue;

// 根据字符串值设置选中项
comboBox.SelectedValue = "选项1";

获取选中值（类型转换）

// 获取 float 类型的值（转换失败返回默认值 0）
float angle = comboBox.GetSelectedValue(0f);

// 获取 int 类型的值
int num = comboBox.GetSelectedValue(0);

// 获取 double 类型的值
double d = comboBox.GetSelectedValue(0.0);

// 获取 decimal 类型的值
decimal m = comboBox.GetSelectedValue(0m);

搜索过滤功能

// 启用搜索过滤功能
comboBox.EnableSearch = true;

// 添加数据
comboBox.AddRange(new object[] { "苹果", "香蕉", "橙子", "葡萄", "西瓜", "草莓", "蓝莓", "芒果" });

// 下拉时会显示搜索框，输入关键字可快速过滤

搜索功能说明：

  • 启用 EnableSearch 后，下拉面板顶部会显示搜索文本框
  • 输入关键字时，列表会实时过滤显示匹配的项
  • 支持键盘操作：
    • ↑/↓ 方向键移动选择
    • Enter 确认选择
    • ESC 关闭下拉面板

组合使用示例

// 创建带前缀的下拉框
ComboBoxEx comboBox = new ComboBoxEx
{
    Size = new Size(150, 32),
    DropDownStyle = ComboBoxEx.ComboBoxExStyle.DropDownList,
    PrefixText = "位置",
    PrefixTextColor = Color.Gray,
    BorderRadius = 4
};

// 添加选项
comboBox.Items.AddRange(new object[] { "左上", "上中", "右上", "左下", "下中", "右下" });
comboBox.SelectedIndex = 0;

this.Controls.Add(comboBox);

主题支持

ComboBoxEx 支持亮暗主题切换，通过实现 IThemeable 接口提供主题适配功能。

跟随全局主题

// 默认开启，自动跟随全局主题变化
comboBox.FollowGlobalTheme = true;

// 手动应用主题
comboBox.ApplyTheme(ThemeMode.Dark);  // 切换到暗色主题
comboBox.ApplyTheme(ThemeMode.Light); // 切换到亮色主题

主题效果

主题模式 背景色 边框色 项悬停色 项选中色
Light White Gray 230, 240, 250 200, 220, 240
Dark 30, 30, 30 60, 60, 60 50, 50, 50 70, 70, 70

禁用主题跟随

// 禁用主题跟随，保持自定义颜色
comboBox.FollowGlobalTheme = false;
comboBox.DropDownBackColor = Color.LightYellow;
comboBox.ItemHoverColor = Color.LightGreen;

注意事项

  1. 样式选择：DropDownStyle 为 DropDownList 时只能选择不能编辑
  2. 圆角半径：BorderRadius 为 0 时为直角
  3. 自动调整：AutoSizeDropDownWidth 为 true 时下拉列表宽度会自动调整
  4. 项高度：ItemHeight 影响下拉列表中每项的高度
  5. 搜索功能：EnableSearch 为 true 时，下拉面板会显示搜索框，支持实时过滤
  6. 搜索键盘：搜索框支持下方向键、上方向键、回车键、ESC 键操作
  7. 前缀文本：PrefixText 设置后会自动计算宽度，确保文本完整显示
  8. 字体变化：控件字体改变时，前缀文本宽度会自动重新计算

公共方法

方法名 说明
AddItem(object item) 添加单个选项
AddRange(object[] items) 批量添加选项
ClearItems() 清空所有选项
RemoveItem(object item) 移除指定选项
RemoveItemAt(int index) 移除指定索引的选项
SelectItem(object item) 选中指定选项
GetSelectedValue<T>(T defaultValue) 获取选中值的类型转换结果

版本历史

版本 日期 更新内容
1.0 2025-04-20 初始版本
1.1 2025-04-23 添加SelectedValue 属性和 GetSelectedValue<T> 方法
1.2 2025-04-24 添加PrefixText 和 PrefixTextColor 前缀文本功能