介绍

在 C# 中，CheckedListBox 是 Windows 窗体（WinForms）中的一个控件，它结合了列表框（ListBox）和复选框（CheckBox）的功能，允许用户从列表中选择一个或多个项（支持多选）。每个项旁边都有一个复选框，用户可以通过勾选/取消勾选来选择项。

一、基本功能

1. 添加 CheckedListBox 控件

在 WinForms 设计器中，从工具箱拖拽 CheckedListBox 到窗体上，或通过代码动态创建：

// 动态创建 CheckedListBox
CheckedListBox checkedListBox1 = new CheckedListBox();
checkedListBox1.Dock = DockStyle.Fill; // 填充窗体
this.Controls.Add(checkedListBox1); // 添加到窗体

2. 添加列表项

可以通过设计器的 Items 属性添加项，或通过代码添加：

// 方法1：直接添加字符串
checkedListBox1.Items.Add("选项1");
checkedListBox1.Items.Add("选项2");
checkedListBox1.Items.Add("选项3");

// 方法2：添加自定义对象（需重写 ToString() 显示文本）
checkedListBox1.Items.Add(new MyItem(1, "自定义选项1"));
checkedListBox1.Items.Add(new MyItem(2, "自定义选项2"));

// 自定义类示例
public class MyItem
{
    public int Id { get; set; }
    public string Name { get; set; }
    public MyItem(int id, string name)
    {
        Id = id;
        Name = name;
    }
    // 重写 ToString() 以在列表中显示文本
    public override string ToString() => Name;
}

3. 设置选择模式

此属性控制的是 高亮选中（选蓝），不是 复选状态，即：不是指勾选多个复选框

CheckedListBox 支持多种选择模式（通过 SelectionMode 属性），常用模式：

• SelectionMode.One：只能选蓝一项
• SelectionMode.MultiSimple：可通过点击或空格键选中多项（无快捷键）。
• SelectionMode.MultiExtended：支持 Ctrl/Shift 快捷键多选（默认值）。

checkedListBox1.SelectionMode = SelectionMode.MultiSimple; // 简单多选模式

二、获取选中的项

CheckedListBox 中 选中 有两种含义：

• 复选框勾选状态：通过 CheckedItems 或 GetItemChecked(index) 获取。

• 高亮选中状态（选蓝）：通过 SelectedItems 或 SelectedIndices 获取（类似 ListBox）。

通常关注复选框勾选的项

1. 遍历所有勾选的项（CheckedItems）

// 按钮点击事件：获取所有勾选的项
private void button1_Click(object sender, EventArgs e)
{
    // 遍历 CheckedItems（仅包含勾选的项）
    foreach (var item in checkedListBox1.CheckedItems)
    {
        // 若为字符串项
        if (item is string str)
        {
            Console.WriteLine("勾选项：" + str);
        }
        // 若为自定义对象
        else if (item is MyItem myItem)
        {
            Console.WriteLine($"勾选项：ID={myItem.Id}, Name={myItem.Name}");
        }
    }
}

1. 遍历所有勾选的项的索引（CheckedIndices）

// 按钮点击事件：获取所有勾选的项
private void button1_Click(object sender, EventArgs e)
{
    // 遍历 CheckedItems（仅包含勾选的项）
    foreach (var item in checkedListBox1.CheckedIndices)
    {

        Console.WriteLine("勾选项的索引：" + item);

    }
}

3. 通过索引判断是否勾选（GetItemChecked）

// 遍历所有项，判断是否勾选
for (int i = 0; i < checkedListBox1.Items.Count; i++)
{
    if (checkedListBox1.GetItemChecked(i)) // 判断第 i 项是否勾选
    {
        var item = checkedListBox1.Items[i];
        Console.WriteLine($"索引 {i} 的项被勾选：{item}");
    }
}

三、设置项的勾选状态

通过代码勾选或取消勾选项：

// 方法1：通过索引设置（第 0 项勾选，第 1 项取消勾选）
checkedListBox1.SetItemChecked(0, true);  // 勾选
checkedListBox1.SetItemChecked(1, false); // 取消勾选

// 方法2：通过项对象设置（需先找到索引）
int index = checkedListBox1.Items.IndexOf("选项3");
if (index != -1)
{
    checkedListBox1.SetItemChecked(index, true);
}

// 方法3：全选/全不选
for (int i = 0; i < checkedListBox1.Items.Count; i++)
{
    checkedListBox1.SetItemChecked(i, true); // 全选
    // checkedListBox1.SetItemChecked(i, false); // 全不选
}

四、事件响应

CheckedListBox 常用事件：

• ItemCheck：当项的勾选状态即将改变时触发（可在此时获取旧状态和新状态）。
• SelectedIndexChanged：当高亮选中的项变化时触发（类似 ListBox）。

示例：ItemCheck 事件

// 注册事件（设计器或代码中）
checkedListBox1.ItemCheck += CheckedListBox1_ItemCheck;

// 事件处理方法
private void CheckedListBox1_ItemCheck(object sender, ItemCheckEventArgs e)
{
    // e.Index：发生变化的项的索引
    // e.CurrentValue：当前状态（Checked/Unchecked/Indeterminate）
    // e.NewValue：即将设置的状态
    var item = checkedListBox1.Items[e.Index];
    Console.WriteLine($"项 {item} 的状态即将从 {e.CurrentValue} 变为 {e.NewValue}");
}

五、关键属性

总结

CheckedListBox 适合需要用户从列表中选择多个选项的场景，核心操作包括：

• 添加项（支持字符串或自定义对象）。
• 通过 CheckedItems 或 GetItemChecked 获取勾选项。
• 通过 SetItemChecked 设置勾选状态。
• 响应 ItemCheck 事件处理状态变化。

根据实际需求配置选择模式和事件，可实现灵活的多选功能。