syncfusion-winforms-listview

实现 ListView

Syncfusion® Windows Forms ListView（SfListView）实现指南——这是一款高性能列表控件，可用于创建丰富的基于列表的用户界面，支持数据绑定、分组、排序、筛选、选择模式、复选框选择以及丰富的自定义选项。

何时使用此技能

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

• 创建列表视图，在 Windows Forms 应用程序中将集合绑定为数据源
• 显示项目集合，并使用分组、排序和筛选功能
• 实现项目选择，支持单选或多选模式
• 添加复选框选择，以便对多个项目执行操作
• 构建可搜索的列表，并支持筛选和排序
• 创建分组列表，其中的分组可展开或折叠
• 自定义项目外观，使用模板、样式和主题
• 支持无障碍访问，包括 UIAutomation 和键盘导航
• 构建数据驱动的界面，例如文件资源管理器、联系人列表或产品目录
• 处理大型数据集，并通过优化视图回收提升性能

此技能涵盖完整的 ListView 实现，包括设置、数据绑定、选择、数据操作、自定义和高级功能。

组件概述

SfListView 控件是一款高性能列表视图控件，提供以下功能：

• 数据绑定——支持 IEnumerable 数据源并自动刷新
• 选择模式——支持单选、多选或不选择，并提供事件
• 复选框选择——通过复选框进行多选，支持全选和递归勾选
• 分组——按属性组织项目，并支持展开分组
• 排序——支持升序或降序排序，以及自定义比较器
• 筛选——按条件筛选项目，并支持实时更新
• 项目大小——自动适应或固定项目高度
• 自定义——样式、模板和主题（Office 2016）
• 页眉/页脚——自定义页眉和页脚视图
• 滚动条自定义——自定义外观和行为
• 本地化——支持多种语言
• 无障碍访问——支持屏幕阅读器所需的 UIAutomation

控件结构

SfListView
├── Header View (optional) - Top content area
├── Groups - Collapsible item groups
│   ├── Group Header - Group title and expand/collapse
│   └── Items - Data items in group
├── Items - Flat list of data-bound items
└── Footer View (optional) - Bottom content area

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和依赖项
• 通过设计器和代码添加 SfListView
• 创建数据对象类
• 使用 DataSource 进行基本数据绑定
• 第一个列表视图示例

数据绑定

📄 阅读： references/data-binding.md

• 绑定 IEnumerable 数据源
• 配置 DataSource 属性
• DisplayMember 和 ValueMember
• 使用 ObservableCollection 实时更新
• 以编程方式刷新数据
• 处理数据源更改

选择

📄 阅读： references/selection.md

• SelectionMode（None、One、MultiSimple、MultiExtended）

• SelectedItem 和 SelectedItems 属性

• SelectedIndex 和 SelectedIndices

• SelectionChanged 事件

• 以编程方式进行选择

• 自定义选择外观

• 📄 阅读： references/checkbox-selection.md

• CheckBoxSelectionMode 属性

• CheckedItems 集合

• CheckedIndices 属性

• ItemChecking 和 ItemChecked 事件

• 全选功能

• 在分组列表中递归勾选

• 自定义复选框外观

数据操作

📄 阅读： references/data-operations.md

• 按属性对项目分组
• 配置 GroupDescriptor
• 对项目排序（升序、降序）
• 自定义排序比较器
• 使用谓词进行筛选
• 筛选条件和规则
• 用于实时更新的 LiveDataUpdateMode

自定义

📄 阅读： references/appearance.md

• 样式属性自定义
• ItemStyle 和 GroupHeaderStyle
• 主题支持（Office 2016 等）
• 颜色、字体和边框
• 使用 DrawItem 事件进行自定义渲染
• 选择颜色和焦点指示器

📄 阅读： references/item-sizing-headers.md

• ItemHeight 属性
• GroupHeaderHeight 属性
• AutoFitMode（Height、DynamicHeight）
• 标题视图自定义
• 页脚视图自定义
• 动态高度计算

高级功能

📄 阅读： references/advanced-features.md

• 本地化和区域性支持
• 用于无障碍功能的 UIAutomation
• 滚动条自定义
• 性能优化技巧
• 视图回收策略
• 内存管理

快速入门示例

使用数据绑定的基本 ListView

using System;
using System.Collections.Generic;
using System.Windows.Forms;
using Syncfusion.WinForms.ListView;

namespace ListViewDemo
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            InitializeListView();
        }
        
        private void InitializeListView()
        {
            // Create and configure ListView
            SfListView listView = new SfListView();
            listView.Dock = DockStyle.Fill;
            listView.Size = new Size(400, 500);
            
            // Set data source
            listView.DataSource = GetCountryData();
            listView.DisplayMember = "CountryName";
            
            // Enable selection
            listView.SelectionMode = Syncfusion.WinForms.ListView.Enums.SelectionMode.One;
            listView.SelectionChanged += ListView_SelectionChanged;
            
            // Add to form
            this.Controls.Add(listView);
        }
        
        private List<CountryInfo> GetCountryData()
        {
            return new List<CountryInfo>
            {
                new CountryInfo { CountryName = "United States", Continent = "North America" },
                new CountryInfo { CountryName = "Canada", Continent = "North America" },
                new CountryInfo { CountryName = "Germany", Continent = "Europe" },
                new CountryInfo { CountryName = "Japan", Continent = "Asia" },
                new CountryInfo { CountryName = "Australia", Continent = "Oceania" }
            };
        }
        
        private void ListView_SelectionChanged(object sender, EventArgs e)
        {
            if (sender is SfListView listView && listView.SelectedItem != null)
            {
                var selected = listView.SelectedItem as CountryInfo;
                MessageBox.Show($"Selected: {selected.CountryName}");
            }
        }
    }
    
    public class CountryInfo
    {
        public string CountryName { get; set; }
        public string Continent { get; set; }
    }
}

常见模式

模式 1：分组和排序列表

// Create ListView
SfListView listView = new SfListView();
listView.DataSource = GetCountryData();
listView.DisplayMember = "CountryName";

// Add grouping by continent
listView.View.GroupDescriptors.Add(new GroupDescriptor()
{
    PropertyName = "Continent"
});

// Add sorting by country name
listView.View.SortDescriptors.Add(new SortDescriptor()
{
    PropertyName = "CountryName",
    Direction = Syncfusion.Data.ListSortDirection.Ascending
});

模式 2：使用复选框选择并提供全选功能

// Enable checkbox mode
listView.CheckBoxMode = CheckBoxMode.Default;

// Handle checked items changes
listView.CheckStateChanged += (s, e) =>
{
    MessageBox.Show($"Checked items: {listView.CheckedItems.Count}");
};

// Add Select All button
Button selectAllBtn = new Button { Text = "Select All" };
selectAllBtn.Click += (s, e) =>
{
    // Check all items
    for (int i = 0; i < listView.View.Items.Count; i++)
    {
        listView.SetItemCheckState(i, CheckState.Checked);
    }
};

模式 3：可筛选和搜索的列表

// Add TextBox for search
TextBox searchBox = new TextBox();
searchBox.TextChanged += (s, e) =>
{
    string searchText = searchBox.Text.ToLower();
    
    // Apply filter
    listView.View.Filter = item =>
    {
        if (item is CountryInfo country)
        {
            return country.CountryName.ToLower().Contains(searchText);
        }
        return false;
    };
    
    // Refresh view
    listView.View.RefreshFilter();
};

模式 4：自定义项样式

// Customize item appearance
listView.Style.ItemStyle.BackColor = Color.White;
listView.Style.ItemStyle.HoverBackColor = Color.LightBlue;
listView.Style.ItemStyle.SelectedItemBackColor = Color.Blue;
listView.Style.ItemStyle.SelectedItemForeColor = Color.White;
listView.Style.ItemStyle.Font = new Font("Segoe UI", 10f);

// Customize group headers
listView.Style.GroupHeaderStyle.BackColor = Color.LightGray;
listView.Style.GroupHeaderStyle.ForeColor = Color.Black;
listView.Style.GroupHeaderStyle.Font = new Font("Segoe UI", 10f, FontStyle.Bold);

模式 5：使用 ObservableCollection 实现实时更新

using System.Collections.ObjectModel;
using System.ComponentModel;

public class CountryViewModel : INotifyPropertyChanged
{
    private ObservableCollection<CountryInfo> countries;
    
    public ObservableCollection<CountryInfo> Countries
    {
        get { return countries; }
        set
        {
            countries = value;
            OnPropertyChanged(nameof(Countries));
        }
    }
    
    public CountryViewModel()
    {
        Countries = new ObservableCollection<CountryInfo>
        {
            new CountryInfo { CountryName = "USA", Continent = "North America" }
        };
    }
    
    // Add item - ListView updates automatically
    public void AddCountry(CountryInfo country)
    {
        Countries.Add(country);
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

// Bind to ListView
var viewModel = new CountryViewModel();
listView.DataSource = viewModel.Countries;
listView.DisplayMember = "CountryName";

关键属性

核心属性

Property	Type	Description
DataSource	object	获取/设置数据源（IEnumerable）
DisplayMember	string	要在项中显示的属性名称
ValueMember	string	项值对应的属性名称
SelectedItem	object	当前选中的项
SelectedItems	List	选中项的集合
CheckedItems	List	已勾选项的集合

选择属性

Property	Type	Description
SelectionMode	SelectionMode	None、One、MultiSimple、MultiExtended
SelectedIndex	int	选中项的索引
SelectedIndices	List	选中项的索引集合
AllowMultiSelection	bool	启用多选

复选框属性

Property	Type	Description
CheckBoxSelectionMode	CheckBoxSelectionMode	None、Default、SelectAll
CheckedIndices	List	已勾选项的索引集合
AllowRecursiveChecking	bool	启用组内递归勾选
ShowCheckBoxes	bool	显示/隐藏复选框

外观属性

Property	Type	Description
Style	ListViewStyle	整体样式配置
ItemHeight	int	每个项的高度
GroupHeaderHeight	int	组标题的高度
AutoFitMode	AutoFitMode	None、Height、DynamicHeight

数据操作属性

Property	Type	Description
View	DataView	用于访问分组、排序和筛选
LiveDataUpdateMode	LiveDataUpdateMode	AllowDataShaping、AllowSummary、Default

事件

Event	Description
SelectionChanged	选择发生变化时触发
ItemChecking	正在勾选某个项时触发（可取消）
ItemChecked	某项的勾选状态发生变化后触发
ItemsSourceChanged	DataSource 发生变化时触发
DrawItem	自定义绘制项
QueryItemHeight	动态计算项高度

常见用例

1. 联系人列表应用

显示联系人，按首字母分组，提供搜索功能，并支持选择联系人以执行操作。

2. 产品目录浏览器

显示产品，支持按类别筛选、按价格排序，以及通过复选框选择商品加入购物车。

3. 文件资源管理器视图

创建包含图标的文件/文件夹列表，按类型分组，并按名称/日期/大小排序。

4. 任务管理列表

显示任务，支持勾选完成状态、按优先级/状态分组，以及按日期筛选。

5. 邮件客户端收件箱

显示邮件，并支持选择、按日期排序，以及按已读／未读状态筛选。

6. 客户订单列表

显示订单，并支持按状态分组、按日期排序，以及选择订单查看详情。

7. 设置配置界面

创建设置列表，并通过复选框选择启用或停用的功能。

8. DataGrid 替代方案

使用 ListView 以更简单的列表形式显示数据，无需复杂的网格功能。

相关组件

• DataGrid - 用于显示带列的表格数据
• TreeView - 用于显示层次结构数据
• ComboBox - 用于从列表中进行下拉选择
• CheckedListBox - 简单的复选框列表，不含高级功能

最佳实践

1. 数据绑定

   • 使用 ObservableCollection 自动更新 UI
   • 实现 INotifyPropertyChanged，以响应项属性变更
   • 设置 DisplayMember 和 ValueMember，使其含义清晰

2. 性能

   • 启用视图回收（默认启用）
   • 对大型数据集谨慎使用 AutoFitMode
   • 简单场景下避免使用自定义 DrawItem
   • 使用筛选／分组，而不是重新创建数据源

3. 选择

   • 处理 SelectionChanged 事件以响应用户操作
   • 根据使用场景选择合适的 SelectionMode
   • 如有需要，在数据源变更时清除选择

4. 分组和筛选

   • 使用 View.GroupDescriptors 进行分组
   • 设置 View.Filter 谓词进行筛选
   • 更改筛选条件后调用 RefreshFilter()
   • 使用 SortDescriptors 保持排序一致

5. 自定义

   • 优先使用 Style 属性，而不是自定义绘制
   • 应用主题以保持外观一致
   • 使用 ItemStyle 和 GroupHeaderStyle 进行基本自定义
   • 仅在需要复杂自定义渲染时使用 DrawItem

6. 无障碍

   • 启用 UIAutomation 支持
   • 提供有意义的 DisplayMember 值
   • 支持键盘导航
   • 使用屏幕阅读器进行测试

故障排除

项目未显示

• 确认已设置 DataSource，且其不为 null
• 检查 DisplayMember 是否与属性名称匹配（区分大小写）
• 确保数据对象包含公共属性
• 确认 ListView 的大小不为零

无法选择

• 检查 SelectionMode 是否不为 None
• 确认已订阅 SelectionChanged 事件
• 确保项目已启用
• 检查 AllowMultiSelection 是否与 SelectionMode 匹配

分组／筛选未生效

• 更改筛选条件后调用 View.RefreshFilter()
• 检查 GroupDescriptor 的 PropertyName 是否正确
• 确认数据属性存在且可访问
• 确保 LiveDataUpdateMode 设置合适

性能问题

• 对大型列表减少 AutoFitMode 的使用
• 避免复杂的 DrawItem 逻辑
• 使用视图回收（默认行为）
• 对于超大型数据集，考虑使用虚拟化

复选框问题

• 确认 CheckBoxSelectionMode 不为 None
• 检查分组列表的 AllowRecursiveChecking 设置
• 使用 ItemChecking / ItemChecked 事件，而不是 SelectionChanged
• 注意 CheckedItems 与 SelectedItems 的区别

---

后续步骤： 根据实现需求查看相应的参考文档。先从 getting-started.md 开始进行初始设置，然后按需了解数据绑定、选择和数据操作。