WinForm之ListBox 控件

ListBox 控件是 WinForm 中用于展示一组选项列表的控件，支持用户选择一个或多个项（根据选择模式设置），适用于需要同时显示多个选项的场景（如文件列表、用户列表、权限选项等）。与 ComboBox 相比，ListBox 始终展示部分或全部选项（而非下拉展开），更适合选项数量适中且需要直观展示的场景。

ListBox 控件的核心属性

ListBox 的核心特性是 “列表展示” 和 “多选择支持”，其常用属性如下：

属性名	作用描述
Items	列表中的项集合，可通过 Add() 方法添加项，Remove() 移除项，Clear() 清空（核心属性）。
SelectionMode	选择模式（核心属性），枚举值： - None：不可选择 - One：只能选择一项（默认） - MultiSimple：可选择多项（点击即可切换） - MultiExtended：可选择多项（配合 Ctrl/Shift 键）
SelectedItems	获取当前所有选中的项（集合，适用于多选模式）。
SelectedItem	获取当前选中的第一项（适用于单选模式）。
SelectedIndex	获取当前选中项的索引（单选模式下，未选中为 -1；多选模式下返回第一个选中项的索引）。
SelectedIndices	获取所有选中项的索引集合（适用于多选模式）。
MultiColumn	布尔值，控制是否支持多列显示（True 时项按列排列，需配合 ColumnWidth 设置列宽）。
ColumnWidth	多列模式下每列的宽度（像素），MultiColumn = True 时有效。
HorizontalScrollbar	布尔值，控制是否显示水平滚动条（项宽度超出控件时）。
ScrollAlwaysVisible	布尔值，控制是否始终显示垂直滚动条（即使项未超出控件高度）。
Sorted	布尔值，控制项是否自动按字母排序（True 时自动排序，添加项后生效）。
Items.Count	获取列表中的项总数（常用属性，用于判断是否有项）。
Enabled/Visible	控制控件是否启用 / 可见（同其他控件）。

ListBox 控件的常用事件

ListBox 的事件主要用于响应选择变化和交互操作，常用事件如下：

事件名	触发时机
SelectedIndexChanged	选中项的索引发生变化时触发（核心事件），常用于处理选择后的逻辑（如显示详情、更新状态）。
DoubleClick	双击列表中的项时触发（可用于快速操作，如打开选中项、编辑内容）。
MouseClick	鼠标点击列表时触发（可结合 IndexFromPoint 方法获取点击位置的项索引）。
SelectedValueChanged	选中项的值改变时触发（常用于数据绑定场景）。

ListBox 控件的典型用法

ListBox 适用于需要展示可选择列表的场景，常见用法如下：

1. 单选列表 默认模式（SelectionMode = One），用户从列表中选择唯一一项（如选择单个文件、单个用户）。

2. 多选列表 设置 SelectionMode = MultiSimple 或 MultiExtended，允许选择多项（如选择多个权限、多个待处理项）。

3. 多列列表 设置 MultiColumn = True 并指定 ColumnWidth，实现项的多列排列（如联系人列表按多列显示）。

4. 动态更新列表 实时添加、移除项（如动态加载搜索结果、刷新在线用户列表）。

5. 数据绑定 绑定到数据源（如 List<T>、DataTable），自动同步数据与列表项。

单选ListBox示例

选择属性框中的，items属性或者最下面的编辑项

多选ListBox示例

多列ListBox示例

使用示例：多样化的 ListBox 效果

以下代码演示了 ListBox 的核心用法，包括单选、多选、多列显示、动态更新及双击事件等场景：

using System;
using System.Collections.Generic;
using System.Drawing;
using System.Windows.Forms;
​
namespace ListBoxDemo
{public class ListBoxExampleForm : Form{// 用于演示动态添加项的输入框和按钮private TextBox itemInputTextBox;private Button addButton;private Button removeButton;
​public ListBoxExampleForm(){// 窗体基础设置Text = "ListBox 控件示例";Size = new Size(600, 500);StartPosition = FormStartPosition.CenterScreen;InitializeControls(); // 初始化控件}
​// 初始化所有控件private void InitializeControls(){// 1. 单选ListBox示例Label singleSelectLabel = new Label{Text = "1. 单选列表（选择一项）：",Location = new Point(30, 30),AutoSize = true};
​ListBox singleSelectListBox = new ListBox{Location = new Point(30, 60),Size = new Size(250, 120),SelectionMode = SelectionMode.One, // 单选模式（默认）Sorted = true // 自动排序};// 添加初始项singleSelectListBox.Items.AddRange(new object[] {"苹果", "香蕉", "橙子", "葡萄", "西瓜", "草莓", "蓝莓"});
​// 单选列表的选中项变化事件Label singleResultLabel = new Label{Text = "当前选中：无",Location = new Point(30, 190),AutoSize = true,ForeColor = Color.Blue};singleSelectListBox.SelectedIndexChanged += (sender, e) =>{if (singleSelectListBox.SelectedItem != null){singleResultLabel.Text = $"当前选中：{singleSelectListBox.SelectedItem}";}else{singleResultLabel.Text = "当前选中：无";}};
​// 2. 多选ListBox示例Label multiSelectLabel = new Label{Text = "2. 多选列表（可选择多项，配合Ctrl/Shift）：",Location = new Point(320, 30),AutoSize = true};
​ListBox multiSelectListBox = new ListBox{Location = new Point(320, 60),Size = new Size(250, 120),SelectionMode = SelectionMode.MultiExtended, // 扩展多选模式ScrollAlwaysVisible = true // 始终显示滚动条};// 添加初始项multiSelectListBox.Items.AddRange(new object[] {"足球", "篮球", "排球", "羽毛球", "乒乓球", "网球", "游泳", "跑步"});
​// 显示多选结果的按钮Button showMultiResultButton = new Button{Text = "显示选中项",Location = new Point(320, 190),Size = new Size(100, 30)};Label multiResultLabel = new Label{Text = "选中项：无",Location = new Point(430, 195),AutoSize = true,ForeColor = Color.Blue};showMultiResultButton.Click += (sender, e) =>{if (multiSelectListBox.SelectedItems.Count > 0){List<string> selectedItems = new List<string>();foreach (var item in multiSelectListBox.SelectedItems){selectedItems.Add(item.ToString());}multiResultLabel.Text = $"选中项：{string.Join("、", selectedItems)}";}else{multiResultLabel.Text = "选中项：无";}};
​// 3. 多列ListBox示例Label multiColumnLabel = new Label{Text = "3. 多列列表：",Location = new Point(30, 240),AutoSize = true};
​ListBox multiColumnListBox = new ListBox{Location = new Point(30, 270),Size = new Size(250, 120),MultiColumn = true, // 启用多列ColumnWidth = 100, // 每列宽度100像素HorizontalScrollbar = true // 显示水平滚动条};// 添加多列项（超过宽度会自动换行到下一列）for (int i = 1; i <= 20; i++){multiColumnListBox.Items.Add($"项目 {i}");}
​// 4. 可动态更新的ListBox示例（添加/删除项）Label dynamicLabel = new Label{Text = "4. 动态列表（添加/删除项）：",Location = new Point(320, 240),AutoSize = true};
​ListBox dynamicListBox = new ListBox{Location = new Point(320, 270),Size = new Size(250, 120)};
​// 输入框和按钮（用于添加项）itemInputTextBox = new TextBox{Location = new Point(320, 400),Size = new Size(150, 20),PlaceholderText = "输入项内容"};
​addButton = new Button{Text = "添加",Location = new Point(480, 400),Size = new Size(60, 20)};addButton.Click += (sender, e) =>{if (!string.IsNullOrEmpty(itemInputTextBox.Text)){dynamicListBox.Items.Add(itemInputTextBox.Text);itemInputTextBox.Clear(); // 清空输入框itemInputTextBox.Focus(); // 聚焦输入框}};
​// 删除选中项按钮removeButton = new Button{Text = "删除选中项",Location = new Point(320, 430),Size = new Size(100, 20)};removeButton.Click += (sender, e) =>{if (dynamicListBox.SelectedIndex != -1){dynamicListBox.Items.RemoveAt(dynamicListBox.SelectedIndex);}else{MessageBox.Show("请先选择要删除的项", "提示");}};
​// 5. 双击事件示例Label doubleClickLabel = new Label{Text = "双击项查看详情",Location = new Point(30, 400),AutoSize = true,ForeColor = Color.Gray};// 给单选列表添加双击事件singleSelectListBox.DoubleClick += (sender, e) =>{if (singleSelectListBox.SelectedItem != null){MessageBox.Show($"你双击了：{singleSelectListBox.SelectedItem}", "双击提示");}};
​// 将所有控件添加到窗体Controls.AddRange(new Control[] {singleSelectLabel, singleSelectListBox, singleResultLabel,multiSelectLabel, multiSelectListBox, showMultiResultButton, multiResultLabel,multiColumnLabel, multiColumnListBox,dynamicLabel, dynamicListBox, itemInputTextBox, addButton, removeButton,doubleClickLabel});}
​// 程序入口[STAThread]static void Main(){Application.EnableVisualStyles();Application.Run(new ListBoxExampleForm());}}
}
​

代码说明

这个示例展示了 ListBox 的核心用法，重点包括：

1. 单选列表：SelectionMode = One（默认），用户只能选择一项，通过 SelectedIndexChanged 事件实时显示选中项。设置 Sorted = true 实现项的自动排序。

2. 多选列表：SelectionMode = MultiExtended 允许配合 Ctrl/Shift 键选择多项（Ctrl 键选不连续项，Shift 键选连续项）；点击 “显示选中项” 按钮通过 SelectedItems 集合获取所有选中项并展示。

3. 多列列表：MultiColumn = true 启用多列模式，ColumnWidth = 100 设置列宽，项会按列排列（超出控件宽度时自动换行到下一列），配合 HorizontalScrollbar = true 显示水平滚动条。

4. 动态更新列表：通过输入框和 “添加” 按钮向 ListBox 中动态添加项（Items.Add()）；“删除选中项” 按钮通过 Items.RemoveAt(SelectedIndex) 移除选中项，演示列表项的动态维护。

5. 双击事件：给单选列表添加 DoubleClick 事件，双击选中项时显示详情弹窗，适用于快速操作场景（如打开文件、编辑内容）。

使用注意事项

1. 选择模式选择

   • 单选场景用 SelectionMode = One；

   • 简单多选（无需快捷键）用 MultiSimple；

   • 复杂多选（需选连续 / 不连续项）用 MultiExtended；

   • 禁止选择用 None。

2. 性能考量 当项数量庞大（如上万项）时，避免频繁调用 Items.Add()（逐个添加效率低），建议使用 Items.AddRange() 批量添加，或考虑虚拟列表（VirtualMode = true）优化性能。

3. 数据绑定 绑定数据源时，建议使用 DataSource 属性（如绑定 List<string> 或 DataTable），配合 DisplayMember 指定显示字段，修改数据源后需调用 Refresh() 更新列表。

4. 与 CheckedListBox 的区别 ListBox 通过选中状态区分选择，CheckedListBox 每个项带复选框（更直观的多选），需根据交互需求选择（ListBox 更简洁，CheckedListBox 多选状态更明确）。

5. 索引与项的关系 SelectedIndex 在多选模式下仅返回第一个选中项的索引，需获取所有选中项时应使用 SelectedItems 或 SelectedIndices。

ListBox 控件通过灵活的选择模式和列表展示能力，适合需要直观展示并选择多项的场景，是 WinForm 中处理列表类数据的核心控件之一。