syncfusion-wpf-checkedlistbox

实现 Syncfusion WPF CheckedListBox

Syncfusion® WPF CheckedListBox（CheckListBox）控件的实现指南——这是一款功能强大的列表控件，可显示带复选框的项目，以支持多项选择。本技能可帮助你在 WPF 应用程序中集成、配置和自定义 CheckListBox 控件，并正确设置数据绑定、样式和性能优化。

何时使用此技能

在以下情况下使用此技能：

• 实现多选列表，并在 WPF 中使用复选框控件
• 显示可勾选的项目，并使用自定义内容和模板
• 将数据集合绑定到 CheckListBox，并采用 MVVM 模式
• 处理项目勾选/取消勾选事件和选择状态
• 对列表中的项目分组和排序
• 自定义外观，包括主题、颜色和复选框位置
• 通过虚拟化优化性能，以处理大型数据集
• 实现全选/取消全选功能
• 配置布局选项，例如方向和换行
• 排查与 CheckListBox 相关的问题

组件概述

CheckListBox 控件实现了经典的列表框，并带有复选框项目，可通过复选框进行多选。每个项目都可以独立勾选或取消勾选；该控件还支持丰富的自定义选项、数据绑定、分组、排序，以及适用于高性能场景的虚拟化。

主要功能：

• 单击或双击选择项目
• 复选框对齐方式（左侧或右侧）
• 完整的数据绑定和 MVVM 支持
• 使用 CollectionView 进行分组
• 排序功能
• 全选/取消全选功能
• 内置主题和视觉样式
• 支持大型项目集合的虚拟化
• 自定义模板和样式
• 勾选状态更改事件通知

所需程序集：

• Syncfusion.Shared.WPF
• Syncfusion.Tools.WPF

命名空间： Syncfusion.Windows.Tools.Controls

文档和导航指南

入门

📄 阅读： references/getting-started.md

适合阅读的情形：开始实现新的 CheckListBox、设置程序集，或创建基本列表。

涵盖主题：

• 程序集部署和 NuGet 包
• 创建包含 CheckListBox 的 WPF 项目
• 通过设计器和 XAML 添加控件
• 在 C# 中手动添加控件
• 使用 CheckListBoxItem 填充项目
• 通过 ItemsSource 数据绑定填充项目
• DisplayMemberPath 配置
• 基本示例和最简设置

数据绑定

📄 阅读： references/data-binding.md

适合阅读的情形：实现 MVVM 模式、绑定集合，或通过数据绑定管理勾选状态。

涵盖主题：

• ItemsSource 属性配置
• 用于显示值的 DisplayMemberPath
• 将 IsSelected 属性绑定到模型
• 模型和 ViewModel 实现
• ObservableCollection 设置
• 用于勾选状态的 TwoWay 绑定
• INotifyPropertyChanged 模式
• 用于绑定 IsSelected 的 ItemContainerStyle

项目勾选和选择

📄 阅读： references/checking-and-selection.md

适合阅读的情形：管理项目选择行为、处理勾选事件，或实现全选功能。

涵盖主题：

• 以编程方式勾选/取消勾选项目
• IsCheckOnFirstClick 属性（单击或双击）
• SelectedItems 集合管理
• 用于当前选择项的 SelectedItem 属性
• 初始化时勾选项目
• SelectAll 和 UnselectAll 的实现
• ItemChecked 事件处理
• ItemCheckedEventArgs 的使用
• 键盘导航（空格键）
• 获取已勾选项目的列表

分组和排序

📄 阅读： references/grouping-and-sorting.md

适用场景：将项目整理到不同组中、按字母或数字顺序排序，或实现分层视图。

涵盖主题：

• 使用 CollectionView.GroupDescriptions 进行分组
• 配置 PropertyGroupDescription
• 分组标题的选择状态
• 展开和折叠分组
• 使用 CollectionView.SortDescriptions 排序
• SortDescription 属性（PropertyName、Direction）
• 升序和降序
• 多个排序条件
• 组合使用分组和排序

外观和自定义

📄 阅读： references/appearance-customization.md

适用场景：设置控件样式、自定义颜色或字体、更改复选框位置，或应用主题。

涵盖主题：

• Foreground 和 Background 属性
• 用于悬停效果的 MouseOverBackground
• SelectedItemBackground 样式
• CheckBox 对齐方式（左侧/右侧）
• CheckBoxPlacement 属性
• 内置视觉样式和主题
• 自定义模板和样式
• 边框和内边距自定义
• 字体样式和文本外观
• ItemContainerStyle 自定义

布局功能

📄 阅读： references/layout-features.md

适用场景：配置控件布局、调整尺寸，或管理滚动行为。

涵盖主题：

• 布局相关属性概览
• 方向设置（垂直/水平）
• 项目换行行为
• 滚动配置
• 高度和宽度管理
• ScrollViewer 设置
• 项目间距和内边距
• 容器尺寸设置

虚拟化和性能

📄 阅读： references/virtualization.md

适用场景：优化大型数据集的性能、降低内存使用量，或处理性能问题。

涵盖主题：

• 使用 VirtualizingStackPanel
• 启用 UI 虚拟化
• 性能优化技巧
• ScrollUnit 配置
• 内存管理优势
• 大型集合的最佳实践
• 虚拟化的限制
• 何时使用虚拟化

快速入门示例

使用静态项目的基本 CheckListBox

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <syncfusion:CheckListBox x:Name="checkListBox" 
                                 Width="200" 
                                 Height="300">
            <syncfusion:CheckListBoxItem Content="Mexico" />
            <syncfusion:CheckListBoxItem Content="Canada" />
            <syncfusion:CheckListBoxItem Content="Bermuda" />
            <syncfusion:CheckListBoxItem Content="Belize" />
            <syncfusion:CheckListBoxItem Content="Panama" />
        </syncfusion:CheckListBox>
    </Grid>
</Window>

绑定数据的 CheckListBox

<syncfusion:CheckListBox ItemsSource="{Binding Countries}"
                         DisplayMemberPath="Name"
                         IsCheckOnFirstClick="True">
    <syncfusion:CheckListBox.ItemContainerStyle>
        <Style TargetType="syncfusion:CheckListBoxItem">
            <Setter Property="IsSelected" Value="{Binding IsChecked, Mode=TwoWay}" />
        </Style>
    </syncfusion:CheckListBox.ItemContainerStyle>
</syncfusion:CheckListBox>

// ViewModel
public class ViewModel : INotifyPropertyChanged
{
    public ObservableCollection<Country> Countries { get; set; }
    
    public ViewModel()
    {
        Countries = new ObservableCollection<Country>
        {
            new Country { Name = "Mexico", IsChecked = true },
            new Country { Name = "Canada", IsChecked = false },
            new Country { Name = "Bermuda", IsChecked = false }
        };
    }
}

// Model
public class Country : INotifyPropertyChanged
{
    private bool isChecked;
    public string Name { get; set; }
    public bool IsChecked 
    { 
        get => isChecked;
        set { isChecked = value; OnPropertyChanged(); }
    }
}

常见模式

模式 1：处理项目勾选事件

// XAML
<syncfusion:CheckListBox ItemChecked="CheckListBox_ItemChecked" />

// Code-behind
private void CheckListBox_ItemChecked(object sender, ItemCheckedEventArgs e)
{
    var item = e.Item as CheckListBoxItem;
    MessageBox.Show($"{item.Content} is {(e.IsChecked ? "checked" : "unchecked")}");
}

模式 2：获取所有已勾选项目

// Get checked items from SelectedItems property
var checkedItems = checkListBox.SelectedItems;

foreach (var item in checkedItems)
{
    var checkListBoxItem = item as CheckListBoxItem;
    Console.WriteLine(checkListBoxItem.Content);
}

模式 3：以编程方式勾选项目

// Add items to SelectedItems collection
checkListBox.SelectedItems.Add(countryModel1);
checkListBox.SelectedItems.Add(countryModel2);

模式 4：实现 SelectAll

// Check all items
foreach (var item in checkListBox.Items)
{
    if (!checkListBox.SelectedItems.Contains(item))
    {
        checkListBox.SelectedItems.Add(item);
    }
}

关键属性

属性	类型	说明	默认值
ItemsSource	IEnumerable	项目的数据源	null
DisplayMemberPath	string	用于显示文本的属性路径	null
SelectedItems	IList	已勾选项目的集合	Empty
SelectedItem	object	当前选中（获得焦点）的项目	null
IsCheckOnFirstClick	bool	首次单击时勾选项目，而非双击时勾选	true
CheckBoxPlacement	CheckBoxPlacement	复选框位置（Left/Right）	Left
Foreground	Brush	文本颜色	Black
Background	Brush	背景颜色	Transparent
MouseOverBackground	Brush	悬停时的背景颜色	System default
SelectedItemBackground	Brush	已选项目的背景	System default

关键事件

事件	EventArgs	说明
ItemChecked	ItemCheckedEventArgs	项目勾选状态改变时触发
SelectionChanged	SelectionChangedEventArgs	选择改变时触发

常见用例

用例 1：多选筛选列表

在搜索筛选器、报表选项或设置面板中，显示带复选框的可筛选项目以供多选。

→ 阅读： getting-started.md + data-binding.md

用例 2：设置配置面板

创建包含多个可切换选项、功能标志或偏好选择的设置 UI。

→ 阅读： checking-and-selection.md + appearance-customization.md

用例 3：带分组的大型数据集

显示按类别组织的数千个可勾选项，并通过虚拟化提升性能。

→ 阅读： grouping-and-sorting.md + virtualization.md

用例 4：权限/角色管理器

实现按组划分功能并支持按组 SelectAll 的角色或权限选择 UI。

→ 阅读： grouping-and-sorting.md + checking-and-selection.md

用例 5：符合品牌风格的样式化清单

应用自定义主题、颜色和复选框位置，使其符合应用品牌风格。

→ 阅读： appearance-customization.md

故障排除快速链接

问题	跳转至
项目未能正确绑定	data-binding.md
勾选状态未更新	checking-and-selection.md
项目过多导致性能问题	virtualization.md
样式未生效	appearance-customization.md
分组未显示	grouping-and-sorting.md

---

后续步骤： 根据实现需求选择上述参考指南，或从 getting-started.md 开始进行初始设置。