syncfusion-wpf-checkedlistbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF CheckedListBox

实现Syncfusion WPF CheckedListBox控件

Guide for implementing the Syncfusion® WPF CheckedListBox (CheckListBox) control - a powerful list control that displays items with checkboxes for multi-item selection. This skill helps you integrate, configure, and customize the CheckListBox control in WPF applications with proper data binding, styling, and performance optimization.

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

When to Use This Skill

何时使用本内容

Use this skill when you need to:

Implement multi-select lists with checkbox controls in WPF
Display checkable items with custom content and templates
Bind data collections to CheckListBox with MVVM pattern
Handle item checking/unchecking events and selection states
Group and sort items within the list
Customize appearance including themes, colors, and checkbox placement
Optimize performance with virtualization for large datasets
Implement SelectAll/UnselectAll functionality
Configure layout options like orientation and wrapping
Troubleshoot CheckListBox-related issues

在以下场景中可使用本内容：

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

Component Overview

组件概述

The CheckListBox control implements a classic list box with checkbox items, enabling multiple selection through checkboxes. Each item can be checked or unchecked independently, and the control supports rich customization, data binding, grouping, sorting, and virtualization for high-performance scenarios.

Key Features:

Single-click or double-click item selection
Checkbox alignment (left or right)
Full data binding and MVVM support
Grouping with CollectionView
Sorting capabilities
SelectAll/UnselectAll functionality
Built-in themes and visual styles
Virtualization for large item collections
Custom templates and styling
Event notifications for checked state changes

Assemblies Required:

```
Syncfusion.Shared.WPF
```
```
Syncfusion.Tools.WPF
```

Namespace:

Syncfusion.Windows.Tools.Controls

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

核心功能：

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

所需程序集：

```
Syncfusion.Shared.WPF
```
```
Syncfusion.Tools.WPF
```

命名空间：

Syncfusion.Windows.Tools.Controls

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

When to read: Starting a new CheckListBox implementation, setting up assemblies, or creating basic lists.

Topics covered:

Assembly deployment and NuGet packages
Creating WPF project with CheckListBox
Adding control via designer and XAML
Adding control manually in C#
Populating items using CheckListBoxItem
Populating items via data binding with ItemsSource
DisplayMemberPath configuration
Basic examples and minimal setup

📄 阅读： references/getting-started.md

阅读时机：开始新的CheckListBox实现、设置程序集或创建基础列表时。

涵盖主题：

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

Data Binding

数据绑定

📄 Read: references/data-binding.md

When to read: Implementing MVVM pattern, binding collections, or managing checked state through data binding.

Topics covered:

ItemsSource property configuration
DisplayMemberPath for display values
IsSelected property binding to model
Model and ViewModel implementation
ObservableCollection setup
TwoWay binding for checked state
INotifyPropertyChanged pattern
ItemContainerStyle for binding IsSelected

📄 阅读： references/data-binding.md

阅读时机：实现MVVM模式、绑定集合或通过数据绑定管理勾选状态时。

涵盖主题：

ItemsSource属性配置
用于显示文本的DisplayMemberPath
IsSelected属性与模型绑定
模型和ViewModel实现
ObservableCollection设置
勾选状态的双向绑定
INotifyPropertyChanged模式
用于绑定IsSelected的ItemContainerStyle

Item Checking and Selection

项目勾选与选择

📄 Read: references/checking-and-selection.md

When to read: Managing item selection behavior, handling checked events, or implementing SelectAll functionality.

Topics covered:

Checking/unchecking items programmatically
IsCheckOnFirstClick property (single vs double-click)
SelectedItems collection management
SelectedItem property for current selection
Checking items on initialization
SelectAll and UnselectAll implementation
ItemChecked event handling
ItemCheckedEventArgs usage
Keyboard navigation (Space key)
Getting list of checked items

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

阅读时机：管理项目选择行为、处理勾选事件或实现全选功能时。

涵盖主题：

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

Grouping and Sorting

分组与排序

📄 Read: references/grouping-and-sorting.md

When to read: Organizing items into groups, sorting items alphabetically/numerically, or implementing hierarchical views.

Topics covered:

Grouping with CollectionView.GroupDescriptions
PropertyGroupDescription configuration
Group header selection state
Expanding/collapsing groups
Sorting with CollectionView.SortDescriptions
SortDescription properties (PropertyName, Direction)
Ascending and descending order
Multiple sort criteria
Combining grouping and sorting

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

阅读时机：将项目组织为分组、按字母/数字排序或实现分层视图时。

涵盖主题：

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

Appearance and Customization

外观与自定义

📄 Read: references/appearance-customization.md

When to read: Styling the control, customizing colors/fonts, changing checkbox placement, or applying themes.

Topics covered:

Foreground and Background properties
MouseOverBackground for hover effects
SelectedItemBackground styling
CheckBox alignment (left/right side)
CheckBoxPlacement property
Built-in visual styles and themes
Custom templates and styles
Border and padding customization
Font styling and text appearance
ItemContainerStyle customization

📄 阅读： references/appearance-customization.md

阅读时机：设置控件样式、自定义颜色/字体、更改复选框位置或应用主题时。

涵盖主题：

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

Layout Features

布局功能

📄 Read: references/layout-features.md

When to read: Configuring control layout, adjusting dimensions, or managing scrolling behavior.

Topics covered:

Layout-related properties overview
Orientation settings (vertical/horizontal)
Item wrapping behavior
Scrolling configuration
Height and Width management
ScrollViewer settings
Item spacing and padding
Container sizing

📄 阅读： references/layout-features.md

阅读时机：配置控件布局、调整尺寸或管理滚动行为时。

涵盖主题：

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

Virtualization and Performance

虚拟化与性能

📄 Read: references/virtualization.md

When to read: Optimizing performance for large datasets, reducing memory usage, or experiencing performance issues.

Topics covered:

VirtualizingStackPanel usage
Enabling UI virtualization
Performance optimization techniques
ScrollUnit configuration
Memory management benefits
Best practices for large collections
Virtualization limitations
When to use virtualization

📄 阅读： references/virtualization.md

阅读时机：针对大型数据集优化性能、减少内存占用或遇到性能问题时。

涵盖主题：

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

Quick Start Example

快速入门示例

Basic CheckListBox with Static Items

带静态项目的基础CheckListBox

xml

<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>

xml

<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 with Data Binding

带数据绑定的CheckListBox

xml

<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>

csharp

// 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(); }
    }
}

xml

<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>

csharp

// 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(); }
    }
}

Common Patterns

常见模式

Pattern 1: Handle Item Checked Events

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

csharp

// 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")}");
}

csharp

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

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

Pattern 2: Get All Checked Items

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

csharp

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

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

csharp

// 从SelectedItems属性获取已勾选项目
var checkedItems = checkListBox.SelectedItems;

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

Pattern 3: Programmatically Check Items

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

csharp

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

csharp

// 向SelectedItems集合添加项目
checkListBox.SelectedItems.Add(countryModel1);
checkListBox.SelectedItems.Add(countryModel2);

Pattern 4: SelectAll Implementation

模式4：全选功能实现

csharp

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

csharp

// 勾选所有项目
foreach (var item in checkListBox.Items)
{
    if (!checkListBox.SelectedItems.Contains(item))
    {
        checkListBox.SelectedItems.Add(item);
    }
}

Key Properties

核心属性

Property	Type	Description	Default
`ItemsSource`	IEnumerable	Data source for items	null
`DisplayMemberPath`	string	Property path for display text	null
`SelectedItems`	IList	Collection of checked items	Empty
`SelectedItem`	object	Currently selected (focused) item	null
`IsCheckOnFirstClick`	bool	Check item on first click vs double-click	true
`CheckBoxPlacement`	CheckBoxPlacement	Checkbox position (Left/Right)	Left
`Foreground`	Brush	Text color	Black
`Background`	Brush	Background color	Transparent
`MouseOverBackground`	Brush	Hover background color	System default
`SelectedItemBackground`	Brush	Selected item background	System default

属性	类型	描述	默认值
`ItemsSource`	IEnumerable	项目的数据源	null
`DisplayMemberPath`	string	显示文本的属性路径	null
`SelectedItems`	IList	已勾选项目的集合	空
`SelectedItem`	object	当前选中（获焦）的项目	null
`IsCheckOnFirstClick`	bool	单击还是双击勾选项目	true
`CheckBoxPlacement`	CheckBoxPlacement	复选框位置（左/右）	Left
`Foreground`	Brush	文本颜色	Black
`Background`	Brush	背景颜色	Transparent
`MouseOverBackground`	Brush	悬停背景色	系统默认
`SelectedItemBackground`	Brush	选中项目背景色	系统默认

Key Events

核心事件

Event	EventArgs	Description
`ItemChecked`	ItemCheckedEventArgs	Raised when item checked state changes
`SelectionChanged`	SelectionChangedEventArgs	Raised when selection changes

事件	事件参数	描述
`ItemChecked`	ItemCheckedEventArgs	项目勾选状态变更时触发
`SelectionChanged`	SelectionChangedEventArgs	选择状态变更时触发

Common Use Cases

常见用例

Use Case 1: Multi-Select Filter List

用例1：多选筛选列表

Display filterable items with checkboxes for multi-selection in search filters, report options, or settings panels.

→ Read: getting-started.md + data-binding.md

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

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

Use Case 2: Settings Configuration Panel

用例2：设置配置面板

Create settings UI with multiple toggleable options, feature flags, or preference selections.

→ Read: checking-and-selection.md + appearance-customization.md

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

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

Use Case 3: Large Dataset with Grouping

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

Display thousands of checkable items organized by category with virtualization for performance.

→ Read: grouping-and-sorting.md + virtualization.md

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

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

Use Case 4: Permissions/Roles Manager

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

Implement role or permission selection UI with grouped capabilities and SelectAll per group.

→ Read: grouping-and-sorting.md + checking-and-selection.md

实现按分组功能的角色或权限选择UI，支持按组全选。

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

Use Case 5: Styled Checklist for Branding

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

Apply custom themes, colors, and checkbox positioning to match application branding.

→ Read: appearance-customization.md

应用自定义主题、颜色和复选框位置以匹配应用品牌。

→ 阅读： appearance-customization.md

Troubleshooting Quick Links

故障排查快速链接

Issue	Navigate To
Items not binding correctly	data-binding.md
Checked state not updating	checking-and-selection.md
Performance issues with many items	virtualization.md
Styling not applying	appearance-customization.md
Groups not displaying	grouping-and-sorting.md

Next Steps: Choose a reference guide above based on your implementation needs, or start with getting-started.md for initial setup.

问题	导航至
项目绑定失败	data-binding.md
勾选状态未更新	checking-and-selection.md
大量项目导致性能问题	virtualization.md
样式未生效	appearance-customization.md
分组未显示	grouping-and-sorting.md

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