C# CheckedListBox使用方法-马育民老师

# 介绍

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

# 一、基本功能

### 1. 添加 `CheckedListBox` 控件

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

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

### 2. 添加列表项

可以通过设计器的 `Items` 属性添加项，或通过代码添加：
```csharp
// 方法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. 设置选择模式

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

[![](https://www.malaoshi.top/upload/0/0/1GW2CB10MdQb.png)](https://www.malaoshi.top/upload/0/0/1GW2CB10MdQb.png)

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

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

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

# 二、获取选中的项

`CheckedListBox` 中 **选中** 有两种含义：

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

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

通常关注**复选框勾选的项**

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

```csharp
// 按钮点击事件：获取所有勾选的项
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`）

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

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

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

# 三、设置项的勾选状态

通过代码勾选或取消勾选项：
```csharp
// 方法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` 事件
```csharp
// 注册事件（设计器或代码中）
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}");
}
```

# 五、关键属性
| 属性               | 说明                                  |
|--------------------|---------------------------------------|
| `Items`            | 列表中的所有项（`ObjectCollection`）  |
| `CheckedItems`     | 所有被勾选的项（`CheckedItemCollection`） |
| `CheckOnClick`     | 设为 `true` 时，点击项直接切换勾选状态（默认需点击复选框） |
| `SelectionMode`    | 选择模式（控制高亮选中行为）          |
| `CheckedIndices`   | 所有被勾选项的索引（`CheckedIndexCollection`） |

# 总结
`CheckedListBox` 适合需要用户从列表中选择多个选项的场景，核心操作包括：
- 添加项（支持字符串或自定义对象）。
- 通过 `CheckedItems` 或 `GetItemChecked` 获取勾选项。
- 通过 `SetItemChecked` 设置勾选状态。
- 响应 `ItemCheck` 事件处理状态变化。

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

原文出处：http://www.malaoshi.top/show_1GW2CBe2ARWd.html