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 中处理列表类数据的核心控件之一。