syncfusion-wpf-datagrid

Syncfusion WPF DataGrid

Syncfusion WPF DataGrid（SfDataGrid）是一款高性能、功能丰富的组件，用于在 Windows Presentation Foundation 应用程序中显示和处理表格数据。它提供丰富的功能，包括数据绑定、列配置、排序、筛选、分组、编辑和导出。

何时使用此技能

在以下情况下，请使用 Syncfusion WPF DataGrid：

• 在 Windows Presentation Foundation 应用程序中显示表格数据
• 借助虚拟化和性能优化，高效处理大型数据集
• 启用排序、筛选和分组等数据操作
• 通过验证和自定义编辑器实现数据编辑
• 将数据导出为 Excel 或 PDF 格式
• 通过主从关系创建分层视图
• 计算分组、表格或标题的汇总值
• 通过条件样式和主题自定义外观
• 通过全面的数据绑定支持 MVVM 模式
• 配置不同类型的列和自动调整大小策略

组件概览

SfDataGrid 组件提供：

• 数据绑定：支持任意 IEnumerable 源、DataTable 和 MVVM 模式
• 列类型：15 种以上内置列类型（文本、数值、DateTime、ComboBox、CheckBox 等）
• 数据操作：支持自定义逻辑的高级排序、筛选和分组
• 编辑：支持验证、自定义编辑器以及添加/删除操作的行内编辑
• 导出：支持导出为 Excel 和 PDF，并提供自定义选项
• 汇总：提供表格、分组和标题汇总，并内置聚合函数
• 主从视图：用于显示分层数据的嵌套网格视图
• 样式：支持条件样式、主题和全面的视觉自定义
• 性能：支持 UI 虚拟化、按需加载和优化渲染
• 选择：支持多种选择模式（行、单元格、扩展选择），并可通过代码进行控制
• 筛选编辑器：可视化筛选表达式生成器，支持 AND/OR 逻辑、嵌套分组和筛选编辑器面板
• 调整大小：支持交互式调整列和行的大小，并提供约束、隐藏列/行支持和调整大小事件

文档与导航指南

入门与设置

📄 阅读： references/getting-started.md

阅读时机：

• 首次在 WPF 项目中设置 SfDataGrid
• 安装 NuGet 包并添加程序集引用
• 配置带数据绑定的基本网格
• 了解命名空间导入和 XAML 设置
• 实现许可证注册

内容包括：

• 通过 NuGet 安装（Syncfusion.SfGrid.WPF）
• 程序集引用和依赖项
• SfDataGrid 的基本 XAML 标记
• 使用 ItemsSource 进行数据绑定
• 自动生成列
• 许可证配置
• 必要的命名空间导入

列与配置

列类型与定义

📄 阅读： references/columns.md

阅读时机：

• 手动定义列，而非自动生成
• 使用特定列类型（GridTextColumn、GridNumericColumn 等）
• 配置列属性（HeaderText、MappingName、Width）
• 管理列操作（添加、删除、重新排序）
• 启用列调整大小和拖放
• 在水平滚动时冻结列
• 将列属性绑定到 ViewModel

内容包括：

• 15 种以上内置列类型及其使用场景
• 在 XAML 和代码隐藏中手动定义列
• 列属性和配置选项
• 文本输入的字符大小写设置（CharacterCasing：Upper、Lower、Normal）
• 列操作方法
• AllowResizing 和列宽管理
• 用于重新排序的 AllowDraggingColumns
• 用于固定列的 FrozenColumnsCount
• 用于动态列配置的 ViewModel 绑定

自动调整列宽

📄 阅读： references/autosize-columns.md

阅读时机：

• 实现自动列宽计算
• 使用 ColumnSizer 模式（Auto、Star、SizeToCells）
• 使用指定列填充网格的剩余宽度
• 在运行时刷新列宽
• 自定义自动调整大小逻辑
• 实现星号列比例
• 处理基于字体的宽度计算

涵盖内容：

• ColumnSizer 枚举和模式
• AutoFitColumns() 方法的用法
• 单列的 ColumnWidthMode
• AutoLastColumnFill 和 AutoWithLastColumnFill
• 动态刷新自动调整大小计算
• 自定义 GridColumnSizer 实现
• 星号列调整器比例和权重
• 基于字体的宽度计算策略

列和行调整大小

📄 阅读： references/resizing.md

阅读时机：

• 启用列或行的交互式调整大小
• 限制仅允许调整特定列的大小
• 设置列宽的最小值和最大值约束
• 允许用户调整隐藏列或行的大小
• 以编程方式取消或检测调整大小操作

涵盖内容：

• 网格级别的 AllowResizingColumns 和列级别的 GridColumn.AllowResizing
• AllowResizingRows，用于交互式调整行高
• 调整大小时遵循 MinWidth 和 MaxWidth 约束
• AllowResizingHiddenColumns 和 AllowResizingHiddenRows（隐藏项的调整大小指示器）
• 通过 ResizingColumns 事件取消列调整大小（e.Cancel）
• 检测调整列大小完成（ColumnResizingReason.Resized、e.Width）
• 通过 RowResizing 事件取消行调整大小（e.Cancel）
• 检测调整行大小完成（RowResizingReason.Resized、e.Height）

数据操作

排序

📄 阅读： references/sorting.md

阅读时机：

• 在 DataGrid 中启用排序
• 实现单列或多列排序
• 添加编程式排序
• 创建自定义排序逻辑
• 处理三态排序
• 控制初始排序方向
• 响应排序事件

涵盖内容：

• 用于启用排序功能的 AllowSorting 属性
• 网格和列级别的 InitialSortDirection，用于设置首次点击时的排序方向
• 用于编程式排序的 SortColumnDescriptions 集合
• 列级别的 AllowSorting
• 用于排序逻辑的自定义 IComparer 实现
• SortClickAction（SingleClick、DoubleClick）
• 三态排序配置
• 排序事件（SortColumnsChanging、SortColumnsChanged）
• 移除排序指示器

筛选

📄 阅读： references/filtering.md

阅读时机：

• 实现数据筛选功能
• 使用谓词添加编程式筛选条件
• 配置筛选行或高级筛选 UI
• 创建自定义筛选逻辑
• 使用 Excel 风格的筛选
• 处理筛选事件

涵盖内容：

• 使用 View.Filter 谓词进行视图筛选
• 使用 FilterPredicates 进行列筛选
• 筛选行实现（AllowFiltering）
• 高级筛选 UI 配置
• Excel 风格的筛选弹出窗口
• 自定义筛选逻辑和条件
• FilterChanged 和 FilterChanging 事件
• RefreshFilter() 方法的用法
• 筛选行自定义

筛选编辑器

📄 阅读： references/filter-editor.md

阅读时机：

• 启用高级可视化筛选编辑器，以处理复杂的筛选表达式
• 在网格上方或下方显示筛选编辑器面板
• 使用 AND/OR 运算符和嵌套组构建多条件筛选表达式
• 暂停和恢复筛选，同时保留筛选条件
• 了解筛选编辑器如何与其他筛选机制同步

涵盖内容：

• 启用筛选编辑器（EnableFilterEditor 属性）
• 从列弹出窗口和筛选编辑器面板打开筛选编辑器
• 筛选编辑器中的应用 / 确定 / 取消操作
• 使用 FilterPanelPosition 属性（Top / Bottom / None）显示筛选编辑器面板
• 在面板中展开 / 折叠筛选表达式
• 使用面板复选框启用 / 暂停筛选
• 关闭筛选编辑器面板（隐藏面板但不清除筛选条件）
• 与复选框筛选 UI、高级筛选 UI、筛选行和 FilterPredicates 的筛选同步
• 限制（仅支持 SfDataGrid.Columns，不显示 View.Filter 委托）

分组

📄 阅读： references/grouping.md

阅读时机：

• 启用数据分组功能
• 按列以编程方式添加分组
• 自定义组的显示方式和行为
• 实现自定义分组逻辑
• 管理组的展开 / 折叠状态
• 添加组汇总

涵盖内容：

• AllowGrouping 属性配置
• 使用 GroupColumnDescriptions 以编程方式分组
• 将列标题拖放到分组面板
• 自定义 IGroupComparer 实现
• 组展开 / 折叠方法
• ShowGroupDropArea 属性
• 组汇总集成
• 分组事件（GroupExpanding、GroupExpanded、GroupCollapsing、GroupCollapsed）

选择

📄 阅读： references/selection.md

阅读时机：

• 配置网格中的选择模式
• 实现行选择或单元格选择
• 以编程方式添加选择
• 处理选择事件
• 使用复选框选择列

涵盖内容：

• SelectionMode（Single、Multiple、Extended、None）
• SelectionUnit（Row、Cell、Any）
• SelectedItem 和 SelectedItems 属性
• 用于单选的 SelectedIndex
• 以编程方式选择的方法（SelectRow、SelectCell）
• 选择事件（SelectionChanging、SelectionChanged）
• CheckBox 选择列
• NavigationMode 和键盘选择

编辑和操作

网格编辑

📄 阅读： references/editing.md

阅读时机：

• 启用网格中的行内编辑
• 配置编辑模式和触发方式
• 实现列级编辑控制
• 为编辑后的单元格添加验证
• 为列创建自定义编辑器
• 管理添加 / 删除行操作
• 处理编辑事件

涵盖内容：

• 用于网格级控制的 AllowEditing 属性
• 列级别的 AllowEditing
• EditTrigger（OnTap、OnDoubleTap）
• BeginEdit() 和 EndEdit() 方法
• 使用 IDataErrorInfo 和 INotifyDataErrorInfo 进行验证
• 自定义编辑器模板
• AddNewRow 配置
• 以编程方式删除行
• 编辑事件（CurrentCellBeginEdit、CurrentCellEndEdit 等）

数据操作

📄 阅读： references/data-manipulation.md

阅读时机：

• 以编程方式向网格添加行
• 删除行或清除数据
• 在代码中更新单元格值
• 执行 CRUD 操作
• 实现数据验证
• 更改后刷新网格数据

涵盖内容：

• 使用 View.AddNew() 添加行
• 使用 View.Remove() 和 View.RemoveAt() 删除行
• 为单元格更改更新数据源
• CRUD 操作模式
• 数据验证策略
• RefreshView() 和 Refresh() 方法
• CommitEdit() 和 CancelEdit() 操作
• UpdateSourceTrigger 配置

拖放

📄 阅读： references/drag-and-drop.md

阅读时机：

• 启用网格内的行拖放
• 实现多个网格之间的拖放
• 配置列拖放
• 自定义拖放行为
• 处理拖放事件

涵盖内容：

• AllowDraggingRows 属性
• 同一网格内的行拖放
• 不同网格之间的拖放
• 用于列重新排序的 AllowDraggingColumns
• 拖放事件（RowDragStarting、RowDragOver、RowDropping、RowDropped）
• 自定义拖放逻辑
• 放置位置指示器

导出和序列化

导出到 Excel 和 PDF

📄 阅读： references/export.md

阅读时机：

• 将网格数据导出为 Excel 格式
• 将网格导出为 PDF 文档
• 自定义导出外观和格式
• 仅导出选定的行
• 处理导出事件
• 添加导出功能所需的程序集

涵盖内容：

• 用于 Excel 导出的 ExcelExportingOptions
• 用于 PDF 导出的 PdfExportingOptions
• ExportToExcel() 和 ExportToPdf() 方法
• 所需的 NuGet 包（Syncfusion.SfGridConverter.WPF）
• 自定义导出样式和外观
• ExportMode（All、SelectedRows）
• 导出事件（ExcelExportingOptions.CellExporting）
• 从导出中排除列
• 在导出内容中自定义单元格格式

高级功能

汇总

📄 阅读： references/summaries.md

阅读时机：

• 为整个网格添加表汇总
• 在组内实现分组汇总
• 在组标题中创建标题汇总
• 使用内置聚合函数
• 创建自定义汇总计算
• 设置汇总显示格式

涵盖内容：

• 用于表汇总的 GridSummaryRow
• TableSummaryRows 集合
• 用于组级聚合的 GroupSummaryRows
• 用于组标题的 CaptionSummaryRow
• 内置聚合函数（Count、Sum、Average、Min、Max 等）
• 自定义聚合实现
• 汇总显示格式字符串
• SummaryColumns 配置
• 用于自定义模板的 ShowSummaryInRow

主从视图

📄 阅读： references/master-detail-view.md

阅读时机：

• 创建分层网格视图
• 实现主从关系
• 配置嵌套网格
• 设置自动展开的详细信息
• 支持多个详细视图
• 自定义详细视图模板

涵盖内容：

• DetailsViewDefinition 设置
• AutoGenerateRelations 属性
• DetailsViewTemplate 中的嵌套 SfDataGrid
• 用于指定子集合的 RelationalColumn
• ExpandAllDetailsView() 方法
• 多个详细视图级别
• 自定义详细视图模板
• 详细视图事件

高级配置

📄 阅读： references/advanced-features.md

阅读时机：

• 实现本地化和全球化
• 序列化和反序列化网格状态
• 保存和恢复网格配置
• 支持多种语言和区域性
• 持久化用户偏好设置

涵盖内容：

• 使用 ResourceManager 和 Resx 文件进行本地化
• 设置 CurrentUICulture 以支持语言
• 创建特定区域性的资源文件
• 序列化选项（SerializationOptions）
• Serialize() 和 Deserialize() 方法
• 将网格状态保存到 XML 文件或流
• 从文件恢复网格配置
• 使用 SerializationController 自定义列序列化
• 性能提示（UI 虚拟化、NotifyListChangedAction）
• AllowFrozenGroupHeaders 选项

样式与自定义

📄 阅读： references/styling.md

阅读时机：

• 应用单元格样式和条件格式
• 自定义行的外观
• 实现交替行样式
• 根据数据创建条件样式
• 设置标题、汇总行和分组行的样式
• 使用 SfSkinManager 应用主题

涵盖内容：

• 使用 CellStyle 统一设置单元格样式
• 使用 CellStyleSelector 设置条件单元格格式
• 使用 RowStyle 和 RowStyleSelector 设置行的外观
• 使用 AlternatingRowStyle 创建斑马纹
• 使用 HeaderStyle 设置列标题样式
• 使用 GroupCaptionStyle 设置分组行样式
• 使用 SummaryCellStyle 设置汇总行样式
• 使用 SfSkinManager 应用主题
• 样式中的触发器和数据绑定
• 视觉状态（Normal、Selected、Current）

快速入门示例

以下是一个在 WPF 中使用 SfDataGrid 的最简示例：

XAML

<Window x:Class="DataGridDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    
    <Grid>
        <syncfusion:SfDataGrid x:Name="dataGrid"
                               AutoGenerateColumns="True"
                               AllowSorting="True"
                               AllowFiltering="True"
                               AllowGrouping="True"
                               AllowEditing="True"
                               ItemsSource="{Binding Orders}">
        </syncfusion:SfDataGrid>
    </Grid>
</Window>

使用 ViewModel 的代码隐藏

using System.Collections.ObjectModel;
using System.ComponentModel;
using Syncfusion.UI.Xaml.Grid;

public class OrderInfo : INotifyPropertyChanged
{
    private string orderId;
    private string customerName;
    private string country;
    private decimal orderTotal;

    public string OrderID 
    { 
        get => orderId; 
        set { orderId = value; OnPropertyChanged(nameof(OrderID)); } 
    }
    
    public string CustomerName 
    { 
        get => customerName; 
        set { customerName = value; OnPropertyChanged(nameof(CustomerName)); } 
    }
    
    public string Country 
    { 
        get => country; 
        set { country = value; OnPropertyChanged(nameof(Country)); } 
    }
    
    public decimal OrderTotal 
    { 
        get => orderTotal; 
        set { orderTotal = value; OnPropertyChanged(nameof(OrderTotal)); } 
    }

    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

public class ViewModel
{
    public ObservableCollection<OrderInfo> Orders { get; set; }

    public ViewModel()
    {
        Orders = new ObservableCollection<OrderInfo>
        {
            new OrderInfo { OrderID = "1001", CustomerName = "John Doe", Country = "USA", OrderTotal = 1500.50m },
            new OrderInfo { OrderID = "1002", CustomerName = "Jane Smith", Country = "UK", OrderTotal = 2300.75m },
            new OrderInfo { OrderID = "1003", CustomerName = "Bob Johnson", Country = "Canada", OrderTotal = 890.25m }
        };
    }
}

常见模式

MVVM 数据绑定模式

// ViewModel property
public ObservableCollection<Employee> Employees { get; set; }

// XAML binding
<syncfusion:SfDataGrid ItemsSource="{Binding Employees}" />

手动定义列

<syncfusion:SfDataGrid AutoGenerateColumns="False" ItemsSource="{Binding Orders}">
    <syncfusion:SfDataGrid.Columns>
        <syncfusion:GridTextColumn MappingName="OrderID" HeaderText="Order ID" Width="120"/>
        <syncfusion:GridTextColumn MappingName="CustomerName" HeaderText="Customer" Width="150"/>
        <syncfusion:GridNumericColumn MappingName="OrderTotal" HeaderText="Total" 
                                      NumberDecimalDigits="2" Width="120"/>
        <syncfusion:GridDateTimeColumn MappingName="OrderDate" HeaderText="Date" 
                                       Pattern="ShortDate" Width="120"/>
    </syncfusion:SfDataGrid.Columns>
</syncfusion:SfDataGrid>

以编程方式排序

// Add sort description
dataGrid.SortColumnDescriptions.Add(new SortColumnDescription
{
    ColumnName = "OrderTotal",
    SortDirection = ListSortDirection.Descending
});

以编程方式筛选

// Set filter predicate
dataGrid.View.Filter = (obj) =>
{
    var order = obj as OrderInfo;
    return order != null && order.OrderTotal > 1000;
};
dataGrid.View.RefreshFilter();

使用面板启用筛选器编辑器

<syncfusion:SfDataGrid x:Name="dataGrid"
                       AllowFiltering="True"
                       EnableFilterEditor="True"
                       FilterPanelPosition="Bottom"
                       ItemsSource="{Binding Orders}" />

调整列和行大小

<syncfusion:SfDataGrid AllowResizingColumns="True"
                       AllowResizingRows="True"
                       AllowResizingHiddenColumns="True"
                       ItemsSource="{Binding Orders}" />

// Cancel resizing for a specific column
dataGrid.ResizingColumns += (sender, e) =>
{
    if (e.ColumnIndex == 0) e.Cancel = true;
};

// Detect when resize is complete
dataGrid.ResizingColumns += (sender, e) =>
{
    if (e.Reason == ColumnResizingReason.Resized)
        Debug.WriteLine($"Column resized to {e.Width}px");
};

处理选择

// Handle selection changed
dataGrid.SelectionChanged += (sender, e) =>
{
    var selectedItem = dataGrid.SelectedItem as OrderInfo;
    if (selectedItem != null)
    {
        MessageBox.Show($"Selected Order: {selectedItem.OrderID}");
    }
};

导出到 Excel

using Syncfusion.UI.Xaml.Grid.Converter;

var options = new ExcelExportingOptions
{
    ExcelVersion = ExcelVersion.Excel2013
};
dataGrid.ExportToExcel(dataGrid.View, options);

关键属性

核心属性

• ItemsSource：网格的数据源（IEnumerable）
• AutoGenerateColumns：根据数据源自动创建列（bool）
• Columns：手动定义的列集合

数据操作属性

• AllowSorting：启用列排序（bool）
• AllowFiltering：启用筛选功能（bool）
• AllowGrouping：启用按列分组（bool）
• AllowEditing：启用行内编辑（bool）

列配置

• ColumnSizer：列的自动调整大小策略
• FrozenColumnsCount：从左侧冻结的列数（int）
• AllowResizingColumns：启用调整列大小（bool）
• AllowResizingRows：启用调整行高（bool）
• AllowResizingHiddenColumns：为隐藏列显示调整大小指示器（bool）
• AllowResizingHiddenRows：为隐藏行显示调整大小指示器（bool）
• AllowDraggingColumns：启用列重排（bool）

筛选器编辑器属性

• EnableFilterEditor：启用可视化筛选器编辑器，以构建复杂的筛选表达式（bool）
• FilterPanelPosition：筛选器编辑器面板的位置（Top / Bottom / None）

选择属性

• SelectionMode：选择行为（Single、Multiple、Extended、None）
• SelectionUnit：选择单位（Row、Cell、Any）
• SelectedItem：当前选中的项（object）
• SelectedItems：选中项的集合

视觉属性

• HeaderRowHeight：列标题行的高度（double）
• RowHeight：数据行的默认高度（double）
• GridLinesVisibility：网格线的可见性（Both、Horizontal、Vertical、None）

常见用例

业务应用

创建带有可编辑网格、验证和 CRUD 操作的数据录入表单，用于管理订单、客户或库存等业务记录。

数据分析与报告

通过排序、筛选、分组和汇总显示大型数据集，以分析销售数据、财务报告或统计信息。

主从视图

通过可展开的详细信息视图展示层次化的数据关系，例如订单行项目、客户订单或类别产品结构。

数据导出与打印

将筛选和分组后的数据导出到 Excel 或 PDF，以便分享报告、创建备份或打印格式化文档。

仪表板与监控

构建实时数据监控网格，支持自动刷新、用于警报的条件样式，以及 KPI 汇总行。

---

**后续步骤：**根据实现需求，前往上方相应的参考文档。先阅读 getting-started.md 完成初始设置，然后根据需要查看特定功能指南。