syncfusion-winforms-listview

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing ListView

ListView实现指南

Guide for implementing Syncfusion® Windows Forms ListView (SfListView) — a high-performance list control for creating rich list-based user interfaces with data binding, grouping, sorting, filtering, selection modes, checkbox selection, and extensive customization options.
本指南用于实现Syncfusion® Windows Forms ListView(SfListView),这是一款高性能列表控件,可用于创建功能丰富的列表类用户界面,支持数据绑定、分组、排序、筛选、多种选择模式、复选框选择和大量自定义选项。

When to Use This Skill

何时使用本指南

Use this skill when you need to:
  • Create list views with data binding to collections in Windows Forms applications
  • Display item collections with grouping, sorting, and filtering capabilities
  • Implement item selection with single or multiple selection modes
  • Add checkbox selection for multi-item operations
  • Build searchable lists with filtering and sorting
  • Create grouped lists with expandable/collapsible groups
  • Customize item appearance with templates, styles, and themes
  • Support accessibility with UIAutomation and keyboard navigation
  • Build data-driven UIs similar to file explorers, contact lists, or product catalogs
  • Handle large datasets with optimized view recycling
This skill covers complete ListView implementation including setup, data binding, selection, data operations, customization, and advanced features.
当你需要完成以下需求时可以使用本指南:
  • 在Windows Forms应用中创建绑定集合数据的列表视图
  • 展示具备分组、排序、筛选能力的项目集合
  • 实现单选或多选模式的项目选择功能
  • 新增复选框选择能力以支持多项目操作
  • 构建支持筛选和排序的可搜索列表
  • 创建支持展开/收起的分组列表
  • 通过模板、样式和主题自定义项目外观
  • 支持UIAutomation和键盘导航的无障碍访问
  • 构建类似文件资源管理器、联系人列表或产品目录的数据驱动UI
  • 通过优化的视图复用机制处理大型数据集
本指南覆盖了完整的ListView实现流程,包括环境搭建、数据绑定、选择功能、数据操作、自定义配置和高级特性。

Component Overview

组件概览

The SfListView control is a high-performance list view control that provides:
  • Data Binding - Support for IEnumerable data sources with automatic refresh
  • Selection Modes - Single, multiple, or none with events
  • Checkbox Selection - Multi-select with checkbox, select all, recursive checking
  • Grouping - Organize items by property with expandable groups
  • Sorting - Ascending/descending sort with custom comparers
  • Filtering - Filter items by criteria with live updates
  • Item Sizing - Auto-fit or fixed item heights
  • Customization - Styles, templates, themes (Office 2016)
  • Header/Footer - Custom header and footer views
  • Scrollbar Customization - Appearance and behavior
  • Localization - Multi-language support
  • Accessibility - UIAutomation support for screen readers
SfListView 是一款高性能列表视图控件,提供以下能力:
  • 数据绑定:支持IEnumerable数据源,可自动刷新
  • 选择模式:支持单选、多选、不开启选择,并配套对应事件
  • 复选框选择:支持多选、全选、分组递归勾选
  • 分组:按属性组织项目,支持分组展开/收起
  • 排序:支持升序/降序排序,可自定义比较器
  • 筛选:按条件筛选项目,支持实时更新
  • 项目尺寸:支持自适应高度或固定项目高度
  • 自定义配置:支持样式、模板、主题(如Office 2016)
  • 页眉/页脚:支持自定义页眉和页脚视图
  • 滚动条自定义:可自定义滚动条外观和行为
  • 本地化:支持多语言
  • 无障碍能力:支持面向屏幕阅读器的UIAutomation

Control Structure

控件结构

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
SfListView
├── 页眉视图(可选) - 顶部内容区域
├── 分组 - 可收起的项目分组
│   ├── 分组头部 - 分组标题和展开/收起按钮
│   └── 项目 - 分组内的数据项
├── 项目 - 扁平化的数据绑定项列表
└── 页脚视图(可选) - 底部内容区域

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Assembly deployment and dependencies
  • Adding SfListView via designer and code
  • Creating data object classes
  • Basic data binding with DataSource
  • First list view example
📄 阅读: references/getting-started.md
  • 程序集部署和依赖项
  • 通过设计器和代码添加SfListView
  • 创建数据对象类
  • 基于DataSource的基础数据绑定
  • 首个列表视图示例

Data Binding

数据绑定

📄 Read: references/data-binding.md
  • Binding to IEnumerable data sources
  • DataSource property configuration
  • DisplayMember and ValueMember
  • ObservableCollection for live updates
  • Refreshing data programmatically
  • Data source change handling
📄 阅读: references/data-binding.md
  • 绑定到IEnumerable数据源
  • DataSource属性配置
  • DisplayMember和ValueMember
  • 用于实时更新的ObservableCollection
  • 程序化刷新数据
  • 数据源变更处理

Selection

选择功能

📄 Read: references/selection.md
  • SelectionMode (None, One, MultiSimple, MultiExtended)
  • SelectedItem and SelectedItems properties
  • SelectedIndex and SelectedIndices
  • SelectionChanged event
  • Programmatic selection
  • Selection appearance customization
📄 Read: references/checkbox-selection.md
  • CheckBoxMode property
  • CheckedItems collection
  • CheckedIndices property
  • CheckStateChanged event
  • Select all functionality
  • Recursive checking in grouped lists
  • Checkbox appearance customization
📄 阅读: references/selection.md
  • SelectionMode(None, One, MultiSimple, MultiExtended)
  • SelectedItem和SelectedItems属性
  • SelectedIndex和SelectedIndices
  • SelectionChanged事件
  • 程序化选择
  • 选择外观自定义
📄 阅读: references/checkbox-selection.md
  • CheckBoxMode属性
  • CheckedItems集合
  • CheckedIndices属性
  • CheckStateChanged事件
  • 全选功能
  • 分组列表的递归勾选
  • 复选框外观自定义

Data Operations

数据操作

📄 Read: references/data-operations.md
  • Grouping items by property
  • GroupDescriptor configuration
  • Sorting items (ascending, descending)
  • Custom sort comparers
  • Filtering with predicates
  • Filter criteria and conditions
  • LiveDataUpdateMode for real-time updates
📄 阅读: references/data-operations.md
  • 按属性对项目分组
  • GroupDescriptor配置
  • 项目排序(升序、降序)
  • 自定义排序比较器
  • 基于谓词的筛选
  • 筛选规则和条件
  • 用于实时更新的LiveDataUpdateMode

Customization

自定义配置

📄 Read: references/appearance.md
  • Style property customization
  • ItemStyle and GroupHeaderStyle
  • Theme support (Office 2016, etc.)
  • Colors, fonts, and borders
  • DrawItem event for custom rendering
  • Selection colors and focus indicators
📄 Read: references/item-sizing-headers.md
  • ItemHeight property
  • GroupHeaderHeight property
  • AutoFitMode (Height, DynamicHeight)
  • Header view customization
  • Footer view customization
  • Dynamic height calculation
📄 阅读: references/appearance.md
  • 样式属性自定义
  • ItemStyle和GroupHeaderStyle
  • 主题支持(Office 2016等)
  • 颜色、字体和边框
  • 用于自定义渲染的DrawItem事件
  • 选择颜色和焦点指示器
📄 阅读: references/item-sizing-headers.md
  • ItemHeight属性
  • GroupHeaderHeight属性
  • AutoFitMode(Height, DynamicHeight)
  • 页眉视图自定义
  • 页脚视图自定义
  • 动态高度计算

Advanced Features

高级特性

📄 Read: references/advanced-features.md
  • Localization and culture support
  • UIAutomation for accessibility
  • Scrollbar customization
  • Performance optimization techniques
  • View recycling strategy
  • Memory management
📄 阅读: references/advanced-features.md
  • 本地化和文化支持
  • 无障碍相关的UIAutomation
  • 滚动条自定义
  • 性能优化技巧
  • 视图复用策略
  • 内存管理

Quick Start Example

快速入门示例

Basic ListView with Data Binding

基础数据绑定ListView

csharp
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; }
    }
}
csharp
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()
        {
            // 创建并配置ListView
            SfListView listView = new SfListView();
            listView.Dock = DockStyle.Fill;
            listView.Size = new Size(400, 500);
            
            // 设置数据源
            listView.DataSource = GetCountryData();
            listView.DisplayMember = "CountryName";
            
            // 开启选择功能
            listView.SelectionMode = Syncfusion.WinForms.ListView.Enums.SelectionMode.One;
            listView.SelectionChanged += ListView_SelectionChanged;
            
            // 添加到窗体
            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; }
    }
}

Common Patterns

常用实现模式

Pattern 1: Grouped and Sorted List

模式1:分组排序列表

csharp
// 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
});
csharp
// 创建ListView
SfListView listView = new SfListView();
listView.DataSource = GetCountryData();
listView.DisplayMember = "CountryName";

// 按大洲分组
listView.View.GroupDescriptors.Add(new GroupDescriptor()
{
    PropertyName = "Continent"
});

// 按国家名称排序
listView.View.SortDescriptors.Add(new SortDescriptor()
{
    PropertyName = "CountryName",
    Direction = Syncfusion.Data.ListSortDirection.Ascending
});

Pattern 2: Checkbox Selection with Select All

模式2:支持全选的复选框选择

csharp
// 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);
    }
};
csharp
// 开启复选框模式
listView.CheckBoxMode = CheckBoxMode.Default;

// 处理勾选项目变更
listView.CheckStateChanged += (s, e) =>
{
    MessageBox.Show($"Checked items: {listView.CheckedItems.Count}");
};

// 添加全选按钮
Button selectAllBtn = new Button { Text = "Select All" };
selectAllBtn.Click += (s, e) =>
{
    // 勾选所有项目
    for (int i = 0; i < listView.View.Items.Count; i++)
    {
        listView.SetItemCheckState(i, CheckState.Checked);
    }
};

Pattern 3: Filtered and Searchable List

模式3:可筛选搜索的列表

csharp
// 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();
};
csharp
// 添加搜索文本框
TextBox searchBox = new TextBox();
searchBox.TextChanged += (s, e) =>
{
    string searchText = searchBox.Text.ToLower();
    
    // 应用筛选规则
    listView.View.Filter = item =>
    {
        if (item is CountryInfo country)
        {
            return country.CountryName.ToLower().Contains(searchText);
        }
        return false;
    };
    
    // 刷新视图
    listView.View.RefreshFilter();
};

Pattern 4: Custom Item Styling

模式4:自定义项目样式

csharp
// 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);
csharp
// 自定义项目外观
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);

// 自定义分组头部
listView.Style.GroupHeaderStyle.BackColor = Color.LightGray;
listView.Style.GroupHeaderStyle.ForeColor = Color.Black;
listView.Style.GroupHeaderStyle.Font = new Font("Segoe UI", 10f, FontStyle.Bold);

Pattern 5: ObservableCollection with Live Updates

模式5:支持实时更新的ObservableCollection

csharp
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";
csharp
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" }
        };
    }
    
    // 添加项目 - ListView会自动更新
    public void AddCountry(CountryInfo country)
    {
        Countries.Add(country);
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

// 绑定到ListView
var viewModel = new CountryViewModel();
listView.DataSource = viewModel.Countries;
listView.DisplayMember = "CountryName";

Key Properties

核心属性

Core Properties

基础属性

PropertyTypeDescription
DataSourceobjectGets/sets the data source (IEnumerable)
DisplayMemberstringProperty name to display in items
ValueMemberstringProperty name for item values
SelectedItemobjectCurrently selected item
SelectedItemsList<object>Collection of selected items
CheckedItemsList<object>Collection of checked items
属性类型描述
DataSourceobject获取/设置数据源(IEnumerable类型)
DisplayMemberstring列表项展示的属性名称
ValueMemberstring列表项对应值的属性名称
SelectedItemobject当前选中的项目
SelectedItemsList<object>选中项目的集合
CheckedItemsList<object>勾选项目的集合

Selection Properties

选择属性

PropertyTypeDescription
SelectionModeSelectionModeNone, One, MultiSimple, MultiExtended
SelectedIndexintIndex of selected item
SelectedIndicesList<int>Indices of selected items
AllowMultiSelectionboolEnable multiple selection
属性类型描述
SelectionModeSelectionMode可选值:None, One, MultiSimple, MultiExtended
SelectedIndexint选中项目的索引
SelectedIndicesList<int>选中项目的索引集合
AllowMultiSelectionbool开启多选功能

Checkbox Properties

复选框属性

PropertyTypeDescription
CheckBoxModeCheckBoxModeNone, Default, SelectAll
CheckedIndicesList<int>Indices of checked items
RecursiveCheckStateboolEnable recursive checking in groups
ShowCheckBoxboolShow/hide checkboxes
属性类型描述
CheckBoxModeCheckBoxMode可选值:None, Default, SelectAll
CheckedIndicesList<int>勾选项目的索引集合
RecursiveCheckStatebool开启分组内递归勾选
ShowCheckBoxbool显示/隐藏复选框

Appearance Properties

外观属性

PropertyTypeDescription
StyleListViewStyleOverall style configuration
ItemHeightintHeight of each item
GroupHeaderHeightintHeight of group headers
AutoFitModeAutoFitModeNone, Height, DynamicHeight
属性类型描述
StyleListViewStyle整体样式配置
ItemHeightint单个项目的高度
GroupHeaderHeightint分组头部的高度
AutoFitModeAutoFitMode可选值:None, Height, DynamicHeight

Data Operation Properties

数据操作属性

PropertyTypeDescription
ViewDataViewAccess to grouping, sorting, filtering
LiveDataUpdateModeLiveDataUpdateModeAllowDataShaping, AllowSummary, Default
属性类型描述
ViewDataView用于访问分组、排序、筛选能力的入口
LiveDataUpdateModeLiveDataUpdateMode可选值:AllowDataShaping, AllowSummary, Default

Events

事件

EventDescription
SelectionChangedFired when selection changes
CheckStateChangedFired when checkbox state changes
ItemsSourceChangedFired when DataSource changes
DrawItemCustom drawing for items
QueryItemHeightDynamic item height calculation
事件描述
SelectionChanged选中状态变更时触发
CheckStateChanged复选框勾选状态变更时触发
ItemsSourceChanged数据源变更时触发
DrawItem用于自定义绘制项目
QueryItemHeight用于动态计算项目高度

Common Use Cases

常见使用场景

1. Contact List Application

1. 联系人列表应用

Display contacts with grouping by first letter, search functionality, and selection for actions.
展示联系人,支持按首字母分组、搜索功能和操作选择。

2. Product Catalog Browser

2. 产品目录浏览器

Show products with filtering by category, sorting by price, and checkbox selection for cart.
展示产品,支持按类别筛选、按价格排序,支持复选框选择加入购物车。

3. File Explorer View

3. 文件资源管理器视图

Create file/folder lists with icons, grouping by type, sorting by name/date/size.
创建文件/文件夹列表,支持图标、按类型分组、按名称/日期/大小排序。

4. Task Management Lists

4. 任务管理列表

Display tasks with checkbox completion, grouping by priority/status, filtering by date.
展示任务,支持复选框标记完成、按优先级/状态分组、按日期筛选。

5. Email Client Inbox

5. 邮件客户端收件箱

Show email messages with selection, sorting by date, filtering by read/unread status.
展示邮件,支持选择、按日期排序、按已读/未读状态筛选。

6. Customer Order Lists

6. 客户订单列表

Display orders with grouping by status, sorting by date, selection for details.
展示订单,支持按状态分组、按日期排序、选择查看详情。

7. Settings Configuration UI

7. 设置配置UI

Create lists of settings with checkbox selection for enable/disable features.
创建设置列表,支持复选框选择启用/禁用功能。

8. Data Grid Alternative

8. 数据网格替代方案

Use ListView for simpler list-based data display without complex grid features.
使用ListView实现更简单的列表类数据展示,无需复杂的网格特性。

Related Components

相关组件

  • DataGrid - For tabular data with columns
  • TreeView - For hierarchical data structures
  • ComboBox - For dropdown selection from list
  • CheckedListBox - Simple checkbox list without advanced features
  • DataGrid - 用于展示带列的表格数据
  • TreeView - 用于展示层级数据结构
  • ComboBox - 用于下拉列表选择
  • CheckedListBox - 简单复选框列表,无高级特性

Best Practices

最佳实践

  1. Data Binding
    • Use ObservableCollection for automatic UI updates
    • Implement INotifyPropertyChanged for item property changes
    • Set DisplayMember and ValueMember for clarity
  2. Performance
    • Enable view recycling (enabled by default)
    • Use AutoFitMode carefully with large datasets
    • Avoid custom DrawItem for simple scenarios
    • Use filtering/grouping instead of recreating data source
  3. Selection
    • Handle SelectionChanged event for user actions
    • Use appropriate SelectionMode for use case
    • Clear selection when data source changes if needed
  4. Grouping and Filtering
    • Use View.GroupDescriptors for grouping
    • Set View.Filter predicate for filtering
    • Call RefreshFilter() after changing filter criteria
    • Use SortDescriptors for consistent ordering
  5. Customization
    • Use Style properties before custom drawing
    • Apply themes for consistent appearance
    • Use ItemStyle and GroupHeaderStyle for basic customization
    • Only use DrawItem for complex custom rendering
  6. Accessibility
    • Enable UIAutomation support
    • Provide meaningful DisplayMember values
    • Support keyboard navigation
    • Test with screen readers
  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值
    • 支持键盘导航
    • 使用屏幕阅读器进行测试

Troubleshooting

问题排查

Items Not Displaying

项目不显示

  • Verify DataSource is set and not null
  • Check DisplayMember matches property name (case-sensitive)
  • Ensure data objects are public properties
  • Verify ListView size is not zero
  • 确认DataSource已设置且不为null
  • 检查DisplayMember是否匹配属性名称(大小写敏感)
  • 确认数据对象的属性为公开属性
  • 确认ListView尺寸不为0

Selection Not Working

选择功能不生效

  • Check SelectionMode is not None
  • Verify SelectionChanged event is subscribed
  • Ensure items are enabled
  • Check if AllowMultiSelection matches SelectionMode
  • 检查SelectionMode不是None
  • 确认已订阅SelectionChanged事件
  • 确认项目处于启用状态
  • 检查AllowMultiSelection和SelectionMode是否匹配

Grouping/Filtering Not Applied

分组/筛选未生效

  • Call View.RefreshFilter() after filter changes
  • Check GroupDescriptor PropertyName is correct
  • Verify data property exists and is accessible
  • Ensure LiveDataUpdateMode is appropriate
  • 修改筛选规则后调用View.RefreshFilter()
  • 检查GroupDescriptor的PropertyName是否正确
  • 确认对应数据属性存在且可访问
  • 确认LiveDataUpdateMode配置合适

Performance Issues

性能问题

  • Reduce AutoFitMode usage for large lists
  • Avoid complex DrawItem logic
  • Use view recycling (default behavior)
  • Consider virtualization for very large datasets
  • 大型列表减少AutoFitMode的使用
  • 避免复杂的DrawItem逻辑
  • 使用视图复用(默认行为)
  • 超大型数据集考虑使用虚拟化能力

Checkbox Issues

复选框问题

  • Verify CheckBoxMode is not None
  • Check RecursiveCheckState setting for grouped lists
  • Use CheckStateChanged event, not SelectionChanged
  • Ensure CheckedItems vs SelectedItems distinction

Next Steps: Navigate to specific reference documents based on your implementation needs. Start with getting-started.md for initial setup, then explore data binding, selection, and data operations as needed.
  • 确认CheckBoxMode不是None
  • 检查分组列表的RecursiveCheckState设置
  • 使用CheckStateChanged事件而非SelectionChanged
  • 明确区分CheckedItems和SelectedItems的差异

后续步骤: 根据你的实现需求导航到对应的参考文档。首次搭建请先阅读getting-started.md,之后按需探索数据绑定、选择功能和数据操作相关内容。