syncfusion-winforms-datagrid

实现 Syncfusion WinForms DataGrid

全面介绍如何实现 Syncfusion Windows Forms DataGrid（SfDataGrid）组件。该强大的控件可用于显示和操作表格数据，支持列、筛选、排序、分组、编辑、汇总和导出等功能。

何时使用此技能

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

• 在 Windows Forms 应用程序中显示表格数据
• 定义和自定义列（文本、数值、日期、复选框、组合框等）
• 实现筛选、排序和分组等数据操作
• 启用网格内编辑和验证
• 显示数据汇总和聚合结果
• 实现选择功能（单选、多选、行、单元格）
• 将网格数据导出到 Excel 或 PDF
• 根据数据值应用条件样式
• 使用分层数据创建主从视图
• 在网格中启用拖放操作
• 本地化网格文本和消息
• 序列化和反序列化网格状态

组件概述

Syncfusion WinForms DataGrid（SfDataGrid）是一款高性能数据网格控件，提供以下功能：

• 列管理：自动生成、手动定义、堆叠标题、列类型
• 数据操作：筛选（类似 Excel 的界面）、排序、分组并支持展开/折叠
• 编辑：支持多种模式和验证的网格内编辑
• 汇总：分组汇总、表格汇总、标题汇总
• 选择：行、单元格或任意选择模式，并支持多种模式
• 导出：支持自定义的 Excel 和 PDF 导出
• 样式：条件样式、自定义单元格呈现
• 高级功能：主从视图、拖放、本地化、序列化

创建 DataGrid 控件

以编程方式创建 SfDataGrid 控件：

using Syncfusion.WinForms.DataGrid;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private SfDataGrid sfDataGrid1;
        
        public Form1()
        {
            InitializeComponent();
            
            // Create SfDataGrid instance
            sfDataGrid1 = new SfDataGrid();
            
            // Add to form's controls collection
            this.Controls.Add(sfDataGrid1);
        }
    }
}

文档与导航指南

入门

📄 阅读： references/getting-started.md

在以下情况下阅读：

• 首次设置 SfDataGrid 控件
• 了解程序集部署和 NuGet 包安装
• 通过设计器或代码创建控件
• 创建数据模型和集合
• 将数据绑定到网格
• 配置自动生成或手动定义的列
• 处理 TableControl 事件（KeyDown、MouseDown）
• 启用基本功能（排序、筛选、分组、编辑）
• 查看完整的可运行示例

列管理

📄 阅读： references/columns.md

在以下情况下阅读：

• 定义列（自动生成或手动定义）
• 使用不同类型的列（GridTextColumn、GridNumericColumn、GridDateTimeColumn、GridCheckBoxColumn、GridComboBoxColumn 等）
• 自定义自动生成的列或使用 Data Annotations
• 以编程方式添加、移除或重新排列列
• 创建跨多个列的堆叠标题
• 隐藏、显示或调整列的大小
• 启用列拖放以重新排列列

编辑数据

📄 阅读： references/editing.md

在以下情况下阅读：

• 为网格或特定列启用或禁用编辑
• 配置编辑模式（单击、双击、F2 键）
• 处理编辑事件（开始编辑、结束编辑、值已更改）
• 在编辑期间实现验证
• 以编程方式开始、结束或取消编辑
• 自定义编辑模式下的光标位置
• 以编程方式更改单元格值

筛选

📄 阅读： references/filtering.md

在以下情况下阅读：

• 实现以编程方式筛选（视图筛选、列筛选）
• 为用户启用类似 Excel 的筛选界面
• 应用不同的筛选类型（字符串、数值、日期）
• 使用包含多个条件的筛选谓词
• 处理筛选事件
• 清除或修改现有筛选条件
• 排查筛选问题

排序

📄 阅读： references/sorting.md

适用于以下情况：

• 通过点击操作启用 UI 排序
• 以编程方式应用排序（单列或多列）
• 实现自定义排序比较器
• 处理排序事件
• 配置三态排序
• 清除或修改现有排序
• 排查排序问题

分组

📄 阅读： references/grouping.md

适用于以下情况：

• 通过拖放启用 UI 分组
• 以编程方式对数据分组（单级或多级）
• 自定义分组标题和格式
• 展开／折叠分组
• 使用 KeySelector 实现自定义分组逻辑
• 处理分组事件
• 排查分组问题

选择

📄 阅读： references/selection.md

适用于以下情况：

• 配置选择模式（单选、多选、扩展选择）
• 设置选择单位（行、单元格、任意）
• 以编程方式选择行、列或单元格
• 处理选择变更事件
• 实现基于 CheckBox 的选择
• 禁用特定行或列的选择
• 使用当前单元格和已选项目

数据汇总

📄 阅读： references/summaries.md

适用于以下情况：

• 显示分组汇总（求和、平均值、计数、最小值、最大值）
• 在顶部或底部添加表格汇总
• 自定义汇总行和格式
• 创建分组标题汇总
• 实现自定义聚合函数
• 设置汇总行的位置和样式

导出到 Excel 和 PDF

📄 阅读： references/export.md

适用于以下情况：

• 将网格数据导出到 Excel 或 PDF
• 自定义导出外观和格式
• 导出选定行或筛选后的数据
• 在导出时包含或排除特定列
• 处理导出事件以进行自定义
• 使用样式和主题导出
• 配置 PDF 导出的页面设置

条件样式和自定义渲染

📄 阅读： references/styling.md

适用于以下情况：

• 根据单元格值或行数据应用条件样式
• 自定义单元格、行和列的外观
• 处理 DrawCell 事件以进行自定义渲染
• 应用主题和视觉样式
• 为不同类型的单元格应用不同样式
• 实现交替行颜色
• 创建自定义单元格渲染器

高级功能

📄 阅读： references/advanced-features.md

适用于以下情况：

• 使用分层数据实现主从视图
• 启用拖放操作（行、列）
• 为不同区域设置本地化网格文本和消息
• 序列化和反序列化网格状态（列、排序、分组、筛选）
• 配置网格设置和首选项
• 处理复杂的分层数据结构

快速入门示例

以下是一个完整的分步示例，演示如何从头创建可运行的 WinForms DataGrid 应用程序：

步骤 1：创建数据模型类

首先，创建用于表示数据的类：

using System;
using System.Collections.ObjectModel;

public class OrderInfo
{
    public int OrderID { get; set; }
    public string CustomerID { get; set; }
    public string CustomerName { get; set; }
    public string Country { get; set; }
    public string ShipCity { get; set; }
    
    public OrderInfo(int orderId, string customerName, string country, string customerId, string shipCity)
    {
        this.OrderID = orderId;
        this.CustomerName = customerName;
        this.Country = country;
        this.CustomerID = customerId;
        this.ShipCity = shipCity;
    }
}

public class OrderInfoCollection
{
    private ObservableCollection<OrderInfo> _orders;
    
    public ObservableCollection<OrderInfo> Orders
    {
        get { return _orders; }
        set { _orders = value; }
    }
    
    public OrderInfoCollection()
    {
        _orders = new ObservableCollection<OrderInfo>();
        GenerateOrders();
    }
    
    private void GenerateOrders()
    {
        _orders.Add(new OrderInfo(1001, "Maria Anders", "Germany", "ALFKI", "Berlin"));
        _orders.Add(new OrderInfo(1002, "Ana Trujilo", "Mexico", "ANATR", "Mexico D.F."));
        _orders.Add(new OrderInfo(1003, "Antonio Moreno", "Mexico", "ANTON", "Mexico D.F."));
        _orders.Add(new OrderInfo(1004, "Thomas Hardy", "UK", "AROUT", "London"));
        _orders.Add(new OrderInfo(1005, "Christina Berglund", "Sweden", "BERGS", "Lula"));
        _orders.Add(new OrderInfo(1006, "Hanna Moos", "Germany", "BLAUS", "Mannheim"));
        _orders.Add(new OrderInfo(1007, "Frederique Citeaux", "France", "BLONP", "Strasbourg"));
        _orders.Add(new OrderInfo(1008, "Martin Sommer", "Spain", "BOLID", "Madrid"));
        _orders.Add(new OrderInfo(1009, "Laurence Lebihan", "France", "BONAP", "Marseille"));
        _orders.Add(new OrderInfo(1010, "Elizabeth Lincoln", "Canada", "BOTTM", "Tsawassen"));
    }
}

步骤 2：在窗体中创建和配置 DataGrid

using System;
using System.Windows.Forms;
using Syncfusion.WinForms.DataGrid;
using Syncfusion.WinForms.DataGrid.Enums;

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private SfDataGrid sfDataGrid1;
        
        public Form1()
        {
            InitializeComponent();
            InitializeDataGrid();
        }
        
        private void InitializeDataGrid()
        {
            // Create DataGrid instance
            sfDataGrid1 = new SfDataGrid();
            sfDataGrid1.Dock = DockStyle.Fill;
            
            // Create and bind data source
            OrderInfoCollection collection = new OrderInfoCollection();
            sfDataGrid1.DataSource = collection.Orders;
            
            // Enable features
            sfDataGrid1.AllowEditing = true;
            sfDataGrid1.AllowFiltering = true;
            sfDataGrid1.AllowSorting = true;
            sfDataGrid1.AllowGrouping = true;
            sfDataGrid1.ShowGroupDropArea = true;
            
            // Configure selection
            sfDataGrid1.SelectionMode = GridSelectionMode.Extended;
            
            // Auto-generate columns from data model
            sfDataGrid1.AutoGenerateColumns = true;
            
            // Add to form
            this.Controls.Add(sfDataGrid1);
        }
    }
}

步骤 3：手动定义列（可选）

如果你想全面控制列，而不是自动生成列：

private void InitializeDataGrid()
{
    sfDataGrid1 = new SfDataGrid();
    sfDataGrid1.Dock = DockStyle.Fill;
    
    // Disable auto-generation to define columns manually
    sfDataGrid1.AutoGenerateColumns = false;
    
    // Add columns with specific properties
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "OrderID", 
        HeaderText = "Order ID",
        Width = 100,
        AllowEditing = false // Make this column read-only
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "CustomerID", 
        HeaderText = "Customer ID",
        Width = 120
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "CustomerName", 
        HeaderText = "Customer Name",
        Width = 150
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "Country", 
        HeaderText = "Country",
        Width = 120
    });
    
    sfDataGrid1.Columns.Add(new GridTextColumn() 
    { 
        MappingName = "ShipCity", 
        HeaderText = "Ship City",
        Width = 120
    });
    
    // Bind data source
    OrderInfoCollection collection = new OrderInfoCollection();
    sfDataGrid1.DataSource = collection.Orders;
    
    // Enable features
    sfDataGrid1.AllowSorting = true;
    sfDataGrid1.AllowFiltering = true;
    sfDataGrid1.AllowGrouping = true;
    sfDataGrid1.ShowGroupDropArea = true;
    
    // Add to form
    this.Controls.Add(sfDataGrid1);
}

运行效果

运行应用程序后：

• 显示 10 个订单及客户信息的数据网格
• 点击列标题可排序
• 点击筛选图标可筛选数据
• 将列标题拖到拖放区域，可按该列分组
• 双击单元格可编辑（如果 AllowEditing 为 true）
• 支持使用 Ctrl/Shift 键进行多选

基本数据操作

绑定不同的数据源

DataGrid 支持各种数据源类型：

// Bind to ObservableCollection (recommended for automatic UI updates)
ObservableCollection<OrderInfo> orders = new ObservableCollection<OrderInfo>();
sfDataGrid1.DataSource = orders;

// Bind to List
List<OrderInfo> orderList = new List<OrderInfo>();
sfDataGrid1.DataSource = orderList;

// Bind to DataTable
DataTable dataTable = new DataTable();
sfDataGrid1.DataSource = dataTable;

// Bind to BindingList
BindingList<OrderInfo> bindingList = new BindingList<OrderInfo>();
sfDataGrid1.DataSource = bindingList;

处理选择事件

// Handle selection changed
sfDataGrid1.SelectionChanged += (sender, e) =>
{
    if (sfDataGrid1.SelectedItem != null)
    {
        var selectedOrder = sfDataGrid1.SelectedItem as OrderInfo;
        Console.WriteLine($"Selected: {selectedOrder.CustomerName}");
    }
};


## Common Patterns

### Manual Column Definition with Selection

```csharp
sfDataGrid.AutoGenerateColumns = false;

// Add columns
sfDataGrid.Columns.Add(new GridTextColumn() 
{ 
    MappingName = "OrderID", 
    HeaderText = "Order ID",
    AllowEditing = false 
});

sfDataGrid.Columns.Add(new GridNumericColumn() 
{ 
    MappingName = "Quantity", 
    HeaderText = "Qty"
});

// Configure selection
sfDataGrid.SelectionMode = GridSelectionMode.Multiple;
sfDataGrid.SelectionUnit = SelectionUnit.Row;

关键属性

网格核心属性

• DataSource - 要绑定的数据源
• AutoGenerateColumns - 启用／禁用自动生成列
• AllowEditing - 启用／禁用编辑
• AllowFiltering - 启用／禁用筛选
• AllowSorting - 启用／禁用排序
• AllowGrouping - 启用／禁用分组
• AllowDraggingColumns - 启用／禁用列重新排序
• AllowDraggingRows - 启用／禁用行重新排序

选择属性

• SelectionMode - Single、Multiple、Extended、None
• SelectionUnit - Row、Cell、Any
• SelectedItem - 获取／设置选中项
• SelectedItems - 获取／设置多个选中项

视觉属性

• HeaderRowHeight - 标题行的高度
• RowHeight - 默认行高
• Style - 网格样式选项
• ShowGroupDropArea - 显示／隐藏分组放置区域
• ShowRowHeader - 显示／隐藏行标题

常见用例

用例 1：电商订单管理

显示订单，支持按状态筛选、按日期排序、按客户分组、编辑更新，以及为优先级订单应用条件样式。

用例 2：财务报告

显示交易数据及汇总信息（总计、平均值），支持导出到 Excel/PDF、为负值应用条件样式，并以主从模式显示交易详情。

用例 3：库存管理

跟踪产品，支持按类别筛选、为库存不足的项目应用条件样式、编辑数量，以及选择多项进行批量操作。

用例 4：客户关系管理

管理联系人，支持多列排序、按地区分组、导出，以及为状态指示器自定义呈现方式。

用例 5：项目管理

显示任务，以主从模式展示子任务，支持拖放重新排序、按状态应用条件样式，以及汇总进度跟踪信息。

故障排除

常见问题及解决方案：

• 列未显示：检查 MappingName 是否与属性名称完全匹配（区分大小写）
• 无法编辑：确认网格级和列级的 AllowEditing 属性均已设置
• 筛选未生效：确保已启用 AllowFiltering，并在以编程方式进行更改后调用 RefreshFilter()
• 导出格式问题：自定义导出选项并处理导出事件
• 样式未显示：确保已连接 DrawCell 事件，并正确设置 Style 属性
• 无法选择：检查 SelectionMode 和 SelectionUnit 是否已正确配置

有关各功能区域的详细故障排除指南，请参阅上方相应的参考文件。

---

后续步骤

从 入门指南 开始，安装并配置 SfDataGrid，然后根据应用程序需求，通过上方的导航指南探索具体功能。