syncfusion-winui-datagrid

实现 WinUI DataGrid（SfDataGrid）

Syncfusion WinUI DataGrid 控件的综合实现指南。SfDataGrid 是一款高性能、功能丰富的控件，可在 WinUI 3 应用程序中显示和操作表格数据，并支持排序、筛选、分组、编辑、汇总等功能。

何时使用此技能

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

• 在 WinUI 应用程序中显示包含 100 至 1,000,000+ 行的表格数据
• 实现可排序、可筛选和可分组的数据视图
• 为数据录入场景启用带验证的内联编辑
• 对数据集执行 CRUD（创建、读取、更新、删除）操作
• 将数据导出为 Excel 格式
• 使用主从视图显示分层数据
• 实现拖放行重排
• 显示数据汇总和聚合结果（总和、平均值、计数等）
• 使用 ObservableCollection 处理实时数据更新
• 创建以数据为核心的企业级 Windows 桌面应用程序

重要说明： 在 WinUI 3 中，DataContext 不会直接从 Window 继承。必须在 XAML 中的 Grid 或 Page 元素上显式设置 DataContext（例如 <Grid DataContext="{x:Bind ViewModel}">），才能确保数据绑定正常工作。

DataGrid 概述

SfDataGrid（Syncfusion.UI.Xaml.DataGrid.SfDataGrid）是 WinUI 3 的主要网格控件，提供以下功能：

• 高性能： 通过 UI 和数据虚拟化支持数百万行
• 丰富的数据操作： 支持多级排序、筛选和分组
• 编辑： 支持单元格、行和批量编辑模式，并提供验证功能
• 汇总： 支持表格、分组和标题汇总，以及自定义聚合
• 选择： 支持单行、多行或单元格选择
• 样式： 支持条件格式和自定义模板
• 导出： 支持带样式的 Excel 导出
• 高级功能： 支持非绑定行、主从视图和冻结列

所需程序包：

• 主程序包： Syncfusion.Grid.WinUI（DataGrid 控件）
• 导出程序包： Syncfusion.GridExport.WinUI（Excel 导出功能）
• Excel 引擎： Syncfusion.XlsIO.NET（导出操作所需）

命名空间： Syncfusion.UI.Xaml.DataGrid

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 数据绑定基础（IEnumerable、ObservableCollection、动态对象）
• ItemsSource 配置和 INotifyCollectionChanged
• 复杂属性绑定（嵌套对象）
• 基本 XAML 设置和首次实现
• 程序包安装和命名空间注册

列管理

📄 阅读： references/columns.md

• 列类型（GridTextColumn、GridNumericColumn、GridCheckBoxColumn、GridComboBoxColumn 等）
• 自动生成列与手动定义列
• 列宽模式（Auto、Star、None、Fill、AutoLastColumnFill）
• 列宽调整、自动调整大小和手动调整大小
• 显示/隐藏列以及列可见性
• 列重排和冻结列

数据操作（排序、筛选、分组）

📄 阅读： references/data-operations.md

• 排序：单列和多列排序、自定义排序、三态排序
• 筛选：程序化筛选器、视图谓词、列筛选器、筛选行
• 分组：单级和多级分组、自定义分组、展开/折叠
• 分组汇总和筛选行配置

编辑与数据验证

📄 阅读： references/editing-validation.md

• 编辑模式：单元格、行和批量编辑
• 编辑触发方式（单击、双击、F2 键）
• 数据验证规则和错误处理
• CRUD 操作：添加、更新、删除行
• 提交和取消更改
• CurrentCell 导航

选择

📄 阅读： references/selection.md

• 选择模式：单选、多选、扩展选择、不选择
• 选择单位：行和单元格
• SelectedItem、SelectedItems、SelectedIndex 绑定
• 以编程方式进行选择和处理 SelectionChanged 事件
• 选择所有行、选择范围

汇总和聚合

📄 阅读： references/summaries.md

• 表格汇总（显示在页脚）
• 分组汇总（针对每个组）
• 标题汇总（显示在分组标题中）
• 内置聚合函数（Sum、Average、Count、Min、Max）
• 自定义汇总计算
• 汇总行位置

条件样式

📄 阅读： references/conditional-styling.md

• 根据数据条件设置行样式
• 单元格样式和自定义模板
• 用于动态样式的样式选择器
• 视觉状态和数据模板
• 交替行颜色

高级行功能

📄 阅读： references/row-features.md

• 拖放行以重新排序
• 非绑定行（位于数据行上方和下方）
• 用于分层数据的主从视图
• 自定义行高
• 详情视图模板和嵌套网格

数据虚拟化

📄 阅读： references/virtualization.md

• 对大型数据集进行数据虚拟化
• UI 虚拟化（默认启用）
• 虚拟模式配置
• 性能优化技巧
• 高效处理 100,000+ 行

导出到 Excel

📄 阅读： references/export.md

• 将整个网格导出到 Excel（.xlsx）
• 导出选项和自定义
• 仅导出选定的行
• 导出时保留样式和格式
• 自定义导出逻辑

快速入门示例

基本实现

<Page xmlns:dataGrid="using:Syncfusion.UI.Xaml.DataGrid">
    
    <Grid>
        <dataGrid:SfDataGrid x:Name="sfDataGrid"
                             ItemsSource="{Binding Orders}"
                             AutoGenerateColumns="True"
                             AllowSorting="True"
                             AllowFiltering="True"
                             AllowEditing="True"
                             SelectionMode="Single" />
    </Grid>
</Page>

// MainPage.xaml.cs
using Microsoft.UI.Xaml.Controls;
using System.Collections.ObjectModel;

public sealed partial class MainPage : Page
{
    public ObservableCollection<Order> Orders { get; set; }
    
    public MainPage()
    {
        this.InitializeComponent();
        
        Orders = new ObservableCollection<Order>
        {
            new Order { OrderID = 1001, CustomerName = "Maria Anders", Country = "Germany", Total = 250.50M },
            new Order { OrderID = 1002, CustomerName = "Ana Trujillo", Country = "Mexico", Total = 180.00M },
            new Order { OrderID = 1003, CustomerName = "Antonio Moreno", Country = "Mexico", Total = 420.75M }
        };
        
        sfDataGrid.ItemsSource = Orders;
    }
}

// Order Model
public class Order
{
    public int OrderID { get; set; }
    public string CustomerName { get; set; }
    public string Country { get; set; }
    public decimal Total { get; set; }
}

常见模式

模式 1：手动定义列

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     AutoGenerateColumns="False"
                     ItemsSource="{Binding Orders}">
    <dataGrid:SfDataGrid.Columns>
        <dataGrid:GridTextColumn MappingName="OrderID" 
                                 HeaderText="Order ID" 
                                 Width="120" />
        <dataGrid:GridTextColumn MappingName="CustomerName" 
                                 HeaderText="Customer" 
                                 Width="200" />
        <dataGrid:GridTextColumn MappingName="Country" 
                                 Width="150" />
        <dataGrid:GridNumericColumn MappingName="Total" 
                                    HeaderText="Total Amount"
                                    Width="150" />
    </dataGrid:SfDataGrid.Columns>
</dataGrid:SfDataGrid>

模式 2：启用排序和筛选

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     AllowSorting="True"
                     AllowFiltering="True"
                     FilterRowPosition="FixedTop"
                     AllowTriStateSorting="True" />

模式 3：启用分组

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     AllowGrouping="True"
                     ShowGroupDropArea="True" />

// Programmatic grouping
sfDataGrid.GroupColumnDescriptions.Add(new GroupColumnDescription { ColumnName = "Country" });

模式 4：启用编辑

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     AllowEditing="True"
                     EditTrigger="OnDoubleTap"
                     NavigationMode="Cell" />

模式 5：添加汇总

<dataGrid:SfDataGrid x:Name="sfDataGrid"
                     ItemsSource="{Binding Orders}"
                     ShowRowHeader="True">
    <dataGrid:SfDataGrid.TableSummaryRows>
        <dataGrid:GridTableSummaryRow ShowSummaryInRow="False">
            <dataGrid:GridTableSummaryRow.SummaryColumns>
                <dataGrid:GridSummaryColumn Name="TotalSum"
                                            MappingName="Total"
                                            SummaryType="DoubleAggregate"
                                            Format="'Total: {Sum:C}'" />
                <dataGrid:GridSummaryColumn Name="OrderCount"
                                            MappingName="OrderID"
                                            SummaryType="CountAggregate"
                                            Format="'Count: {Count}'" />
            </dataGrid:GridTableSummaryRow.SummaryColumns>
        </dataGrid:GridTableSummaryRow>
    </dataGrid:SfDataGrid.TableSummaryRows>
</dataGrid:SfDataGrid>

关键属性

属性	类型	描述
ItemsSource	object	网格的数据源（IEnumerable）
AutoGenerateColumns	bool	根据数据源属性自动创建列
Columns	Columns	手动定义的列集合
AllowSorting	bool	启用/禁用排序（默认：false）
AllowFiltering	bool	启用/禁用筛选（默认：false）
AllowGrouping	bool	启用/禁用分组（默认：false）
AllowEditing	bool	启用/禁用编辑（默认：false）
SelectionMode	GridSelectionMode	单选、多选、扩展选择、不选择
SelectionUnit	GridSelectionUnit	行或单元格
NavigationMode	NavigationMode	单元格或行导航
ColumnWidthMode	ColumnWidthMode	None、Star、Auto、SizeToCells、SizeToHeader、AutoLastColumnFill、AutoWithLastColumnFill
ShowGroupDropArea	bool	显示用于分组的拖放区域
FilterRowPosition	FilterRowPosition	FixedTop、Top、Bottom

常见用例

企业数据录入应用程序

• 启用编辑、验证和 CRUD 操作
• 使用批量编辑模式提高效率
• 实现 SelectedItems 绑定以支持批量操作
• 添加表格汇总以获取数据洞察

数据分析仪表板

• 启用排序、筛选和分组
• 添加表格级和分组级汇总
• 使用条件样式突出显示关键数据
• 实现导出到 Excel 以生成报告

主从数据查看器

• 配置 DetailsViewDefinition 以显示嵌套数据
• 使用分层数据绑定
• 启用详情的展开/折叠
• 为主行和详情行设置不同样式

大型数据集浏览器（100K+ 行）

• 启用数据虚拟化
• 禁用不需要的功能（分组、汇总）
• 使用冻结列显示重要数据
• 实现增量加载

事务管理系统

• 启用行拖放功能以调整优先级
• 使用未绑定行显示总计和摘要信息
• 使用 ObservableCollection 实现实时更新
• 添加验证规则以确保数据完整性

与 MVVM 集成

// ViewModel
public class OrderViewModel : INotifyPropertyChanged
{
    private ObservableCollection<Order> orders;
    private Order selectedOrder;
    
    public ObservableCollection<Order> Orders
    {
        get => orders;
        set { orders = value; OnPropertyChanged(); }
    }
    
    public Order SelectedOrder
    {
        get => selectedOrder;
        set { selectedOrder = value; OnPropertyChanged(); }
    }
    
    public ICommand DeleteCommand { get; }
    public ICommand ExportCommand { get; }
}

<dataGrid:SfDataGrid ItemsSource="{Binding Orders}"
                     SelectedItem="{Binding SelectedOrder, Mode=TwoWay}" />

性能提示

1. 使用 ObservableCollection 自动更新 UI，而不是使用 List
2. 将 AutoGenerateColumns="False" 并尽可能手动定义列
3. 启用虚拟化（默认已启用，请勿在非必要时禁用）
4. 冻结必要的列，提升水平滚动性能
5. 当数据大小已知时，使用 ColumnWidthMode="None" 设置静态列宽
6. 将分组层级限制为 2～3 级，以获得更好的性能
7. 对于超大型数据集（100K+），使用筛选而不是分组
8. 在 Page.Unloaded 事件中释放网格

故障排除

未显示数据：

• 确认 ItemsSource 已正确绑定
• 检查属性是否具有公共 getter
• 如果使用绑定，请确保已设置 DataContext

无法编辑：

• 设置 AllowEditing="True"
• 设置 NavigationMode="Cell"
• 确认列的 AllowEditing="True"（若未设置，则继承自网格）

大型数据集性能不佳：

• 确认已启用虚拟化（默认已启用）
• 减少列数
• 使用 ColumnWidthMode="None"，而不是 Auto
• 对于 500K+ 行的数据，考虑使用分页

无法排序/筛选：

• 设置 AllowSorting="True" 和/或 AllowFiltering="True"
• 确认数据源实现了 IEnumerable
• 检查列是否单独禁用了这些功能

相关组件

• TreeGrid： 用于分层树形数据
• PivotGrid： 用于 OLAP 和数据透视表场景
• PropertyGrid： 用于编辑对象属性