syncfusion-winforms-grid-grouping-control

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Grid Grouping Controls

实现网格分组控件

Comprehensive guide for implementing Syncfusion® Windows Forms GridGroupingControl - an enterprise-level grid component with built-in support for hierarchical grouping, filtering, multi-column sorting, summaries, and complex data relationships.
这是实现Syncfusion® Windows Forms GridGroupingControl的综合指南,该控件是一款企业级网格组件,原生支持层级分组、过滤、多列排序、汇总以及复杂数据关系处理。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Implement GridGroupingControl in Windows Forms applications
  • Display hierarchical or grouped data with automatic grouping by one or more columns
  • Create master-detail relationships with nested tables and child relations
  • Apply advanced filtering (Excel-like, dynamic, or programmatic filters)
  • Add data summaries (group summaries, caption summaries, table summaries)
  • Sort data by single or multiple columns with custom sorting logic
  • Handle large datasets with virtualization and performance optimization
  • Export grouped data to Excel, PDF, CSV, HTML, or Word
  • Customize grid appearance with conditional formatting and styling
  • Bind to various data sources (DataTable, XML, collections, dynamic objects)
This skill is essential for applications requiring sophisticated data grouping, drill-down capabilities, and comprehensive data management features.
当你需要完成以下需求时可使用本技能:
  • 在Windows Forms应用中实现GridGroupingControl
  • 展示层级或分组数据,支持按单个或多个列自动分组
  • 创建主从关系,支持嵌套表和子关系配置
  • 应用高级过滤(类Excel过滤、动态过滤、程序化过滤)
  • 添加数据汇总(分组汇总、标题汇总、表格汇总)
  • 数据排序,支持单列/多列排序以及自定义排序逻辑
  • 处理大数据集,支持虚拟化和性能优化
  • 导出分组数据到Excel、PDF、CSV、HTML或Word格式
  • 自定义网格外观,支持条件格式和样式配置
  • 绑定多种数据源(DataTable、XML、集合、动态对象)
本技能对于需要复杂数据分组、下钻能力和全面数据管理功能的应用来说是必不可少的。

Component Overview

组件概述

GridGroupingControl is a powerful data grid component that extends standard grid functionality with:
  • Hierarchical Grouping: Organize data into nested groups based on field values
  • Group Drop Area: Interactive area for drag-and-drop grouping by column headers
  • Multi-Level Sorting: Sort by multiple columns with custom sort logic
  • Advanced Filtering: Excel-like filters, dynamic filters, and programmatic record filters
  • Summaries: Column summaries, group summaries, and caption summaries with aggregates
  • Master-Detail Support: Display nested tables with parent-child relationships
  • Data Virtualization: Handle millions of records with instant scrolling
  • Rich Editing: In-place editing with validation and custom editors
  • Flexible Styling: Conditional formatting, themes, and cell-level customization
The control is designed for business applications requiring enterprise-level data management capabilities.
GridGroupingControl是一款功能强大的数据网格组件,在标准网格功能基础上扩展了以下能力:
  • 层级分组: 按字段值将数据组织为嵌套分组
  • 分组拖放区域: 支持通过拖拽列标题进行分组的交互区域
  • 多级排序: 支持按多列排序以及自定义排序逻辑
  • 高级过滤: 类Excel过滤、动态过滤、程序化记录过滤
  • 汇总功能: 列汇总、分组汇总、带聚合的标题汇总
  • 主从支持: 展示带父子关系的嵌套表
  • 数据虚拟化: 支持处理百万级记录,实现瞬间滚动
  • 丰富编辑能力: 带校验和自定义编辑器的就地编辑
  • 灵活样式: 条件格式、主题、单元格级别自定义
该控件专为需要企业级数据管理能力的业务应用设计。

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and assembly deployment
  • Creating GridGroupingControl through Designer and Code
  • Basic data source binding
  • Populating data and first grid example
  • Essential properties and initial configuration
📄 阅读: references/getting-started.md
  • 安装与程序集部署
  • 通过设计器和代码创建GridGroupingControl
  • 基础数据源绑定
  • 数据填充与首个网格示例
  • 核心属性与初始配置

Data Binding and Sources

数据绑定与数据源

📄 Read: references/data-binding.md
  • ADO.NET data binding (DataTable, DataSet, DataView)
  • XML data binding with ReadXml/WriteXml
  • Custom collections (IList, IBindingList, ITypedList)
  • Strongly typed collections and generic collections
  • Dynamic object binding for .NET 4.0+
  • Unbound mode with custom columns
  • Collection interfaces and change notifications
When to read: Setting up data sources, binding to databases, working with custom objects, or implementing unbound scenarios.
📄 阅读: references/data-binding.md
  • ADO.NET数据绑定(DataTable、DataSet、DataView)
  • 基于ReadXml/WriteXml的XML数据绑定
  • 自定义集合(IList、IBindingList、ITypedList)
  • 强类型集合与泛型集合
  • .NET 4.0+的动态对象绑定
  • 带自定义列的非绑定模式
  • 集合接口与变更通知
适用场景: 配置数据源、绑定数据库、处理自定义对象、实现非绑定场景。

Grouping Features

分组功能

📄 Read: references/grouping.md
  • Adding data groups (Designer and programmatic)
  • GroupDropArea configuration and customization
  • Multi-column grouping and nested groups
  • Custom grouping with IComparer and IGroupByColumnCategorizer
  • GroupBy options (headers, footers, preview rows)
  • GroupCaptionSection and caption text tokens
  • Working with groups (expand/collapse, iterate, access)
  • Grouping events and customization
When to read: Implementing grouping functionality, customizing group appearance, working with nested groups, or handling group-related events.
📄 阅读: references/grouping.md
  • 添加数据分组(设计器和程序化实现)
  • GroupDropArea配置与自定义
  • 多列分组与嵌套分组
  • 基于IComparer和IGroupByColumnCategorizer的自定义分组
  • GroupBy选项(头部、底部、预览行)
  • GroupCaptionSection与标题文本占位符
  • 分组操作(展开/收起、遍历、访问)
  • 分组事件与自定义
适用场景: 实现分组功能、自定义分组外观、处理嵌套分组、响应分组相关事件。

Sorting Operations

排序操作

📄 Read: references/sorting.md
  • Programmatic sorting with SortedColumns collection
  • Multi-column sorting with precedence
  • Sort icon placement and customization
  • Removing and clearing sorting
  • Sorting grouped columns
  • Sort by summary values
  • Sort by display member (foreign key relations)
  • Custom sorting with IComparer
  • Sorting events (Changing/Changed)
When to read: Implementing sorting features, customizing sort behavior, sorting by computed values, or handling sort events.
📄 阅读: references/sorting.md
  • 基于SortedColumns集合的程序化排序
  • 带优先级的多列排序
  • 排序图标位置与自定义
  • 移除与清除排序
  • 分组列排序
  • 按汇总值排序
  • 按展示成员排序(外键关系)
  • 基于IComparer的自定义排序
  • 排序事件(Changing/Changed)
适用场景: 实现排序功能、自定义排序行为、按计算值排序、响应排序事件。

Filtering and Search

过滤与搜索

📄 Read: references/filtering.md
  • Setting up filter bar for user filtering
  • Record filters (programmatic filtering)
  • Filter by expression with operators
  • Dynamic filter with GridDynamicFilter
  • Excel-like filter (Optimized and Office2007)
  • Filter by color, number, date, and null values
  • Filter by display member vs value member
  • Stacked header filtering
  • Getting filtered records and filter strings
  • Filtering events
When to read: Implementing filtering capabilities, Excel-like filtering UI, programmatic data filtering, or filter customization.
📄 阅读: references/filtering.md
  • 配置过滤栏供用户过滤
  • 记录过滤(程序化过滤)
  • 带运算符的表达式过滤
  • 基于GridDynamicFilter的动态过滤
  • 类Excel过滤(优化版与Office2007版)
  • 按颜色、数字、日期和空值过滤
  • 按展示成员/值成员过滤
  • 堆叠头部过滤
  • 获取过滤后记录与过滤字符串
  • 过滤事件
适用场景: 实现过滤能力、类Excel过滤UI、程序化数据过滤、过滤自定义。

Summaries and Aggregates

汇总与聚合

📄 Read: references/summaries.md
  • Summary types (Column, Group, Table, Caption)
  • Adding summaries with SummaryDescriptor
  • Built-in aggregate functions (Sum, Average, Count, Min, Max)
  • Custom summaries with ISummaryAggregate
  • Sort by summary values
  • Summary appearance and formatting
  • Summary in group captions
  • Summary events
When to read: Adding aggregate calculations, displaying group totals, implementing custom aggregates, or showing summaries in captions.
📄 阅读: references/summaries.md
  • 汇总类型(列、分组、表格、标题)
  • 通过SummaryDescriptor添加汇总
  • 内置聚合函数(求和、平均值、计数、最小值、最大值)
  • 基于ISummaryAggregate的自定义汇总
  • 按汇总值排序
  • 汇总外观与格式化
  • 分组标题中的汇总
  • 汇总事件
适用场景: 添加聚合计算、展示分组总计、实现自定义聚合、在标题中展示汇总。

Relations and Hierarchy

关系与层级

📄 Read: references/relations-and-hierarchy.md
  • Master-detail relationships setup
  • Nested tables configuration
  • Relations descriptor and child table descriptor
  • Hierarchy display and navigation
  • Expand/collapse nested tables
  • Working with child tables programmatically
  • Foreign key reference relations
When to read: Implementing master-detail grids, displaying nested data, configuring parent-child relationships, or working with hierarchical data.
📄 阅读: references/relations-and-hierarchy.md
  • 主从关系配置
  • 嵌套表配置
  • 关系描述符与子表描述符
  • 层级展示与导航
  • 展开/收起嵌套表
  • 程序化操作子表
  • 外键引用关系
适用场景: 实现主从网格、展示嵌套数据、配置父子关系、处理层级数据。

Editing Capabilities

编辑能力

📄 Read: references/editing.md
  • Enabling/disabling editing
  • Cell editing modes and activation
  • Current cell behavior
  • Data validation
  • Editing events (StartEditing, EditingComplete)
  • Custom editors and cell types
  • AddNew record functionality
When to read: Configuring edit behavior, implementing validation, customizing editors, or handling edit events.
📄 阅读: references/editing.md
  • 启用/禁用编辑
  • 单元格编辑模式与激活方式
  • 当前单元格行为
  • 数据校验
  • 编辑事件(StartEditing、EditingComplete)
  • 自定义编辑器与单元格类型
  • AddNew记录功能
适用场景: 配置编辑行为、实现校验、自定义编辑器、响应编辑事件。

Selection Features

选择功能

📄 Read: references/selections.md
  • Selection modes (None, One, Multiple, MultiSimple, MultiExtended)
  • Record selection vs cell selection
  • Programmatic selection
  • Getting selected records
  • Selection events
  • Selection appearance
When to read: Implementing selection functionality, programmatic record selection, or customizing selection behavior.
📄 阅读: references/selections.md
  • 选择模式(无、单选、多选、简单多选、扩展多选)
  • 记录选择与单元格选择
  • 程序化选择
  • 获取选中记录
  • 选择事件
  • 选择外观
适用场景: 实现选择功能、程序化记录选择、自定义选择行为。

Column Management

列管理

📄 Read: references/column-management.md
  • Adding/removing columns programmatically
  • Column properties (Width, HeaderText, MappingName)
  • Column width and auto-sizing
  • Column visibility and VisibleColumns collection
  • Column reordering and drag-drop
  • Frozen columns
  • Unbound columns
When to read: Managing column visibility, configuring column properties, implementing frozen columns, or adding unbound columns.
📄 阅读: references/column-management.md
  • 程序化添加/移除列
  • 列属性(宽度、头部文本、映射名)
  • 列宽与自动调整
  • 列可见性与VisibleColumns集合
  • 列重排序与拖拽
  • 冻结列
  • 非绑定列
适用场景: 管理列可见性、配置列属性、实现冻结列、添加非绑定列。

Appearance and Styling

外观与样式

📄 Read: references/appearance-and-formatting.md
  • Cell styles and GridStyleInfo
  • Conditional formatting
  • Themes and visual styles
  • Row and column appearance
  • QueryCellStyleInfo event for dynamic styling
  • Appearance properties for different cell types
  • BackColor, ForeColor, Font customization
When to read: Customizing grid appearance, applying conditional formatting, implementing themes, or styling specific cells.
📄 阅读: references/appearance-and-formatting.md
  • 单元格样式与GridStyleInfo
  • 条件格式
  • 主题与视觉样式
  • 行与列外观
  • 用于动态样式的QueryCellStyleInfo事件
  • 不同单元格类型的外观属性
  • 背景色、前景色、字体自定义
适用场景: 自定义网格外观、应用条件格式、实现主题、给特定单元格设置样式。

Cell Types and Customization

单元格类型与自定义

📄 Read: references/cell-types.md
  • Built-in cell types (TextBox, ComboBox, CheckBox, Image)
  • ComboBox cells with DataSource
  • CheckBox cells for boolean data
  • Image cells for displaying graphics
  • Custom cell types and renderers
  • Cell type configuration
When to read: Implementing dropdown lists, checkboxes, image cells, or creating custom cell renderers.
📄 阅读: references/cell-types.md
  • 内置单元格类型(文本框、下拉框、复选框、图片)
  • 带数据源的下拉框单元格
  • 用于布尔值的复选框单元格
  • 展示图片的图片单元格
  • 自定义单元格类型与渲染器
  • 单元格类型配置
适用场景: 实现下拉列表、复选框、图片单元格、创建自定义单元格渲染器。

Grid Layout

网格布局

📄 Read: references/grid-layout.md
  • Row and column sizing (auto-size, fit)
  • Stacked headers for grouped column headers
  • Covered ranges (merged cells)
  • Grid borders and lines
  • Layout customization and spacing
When to read: Configuring row heights, implementing stacked headers, merging cells, or customizing grid layout.
📄 阅读: references/grid-layout.md
  • 行与列尺寸调整(自动调整、自适应)
  • 用于分组列头的堆叠头部
  • 合并范围(合并单元格)
  • 网格边框与线条
  • 布局自定义与间距
适用场景: 配置行高、实现堆叠头部、合并单元格、自定义网格布局。

Navigation and Scrolling

导航与滚动

📄 Read: references/navigation-and-scrolling.md
  • Navigation bar configuration
  • Scrolling options and behavior
  • Keyboard navigation
  • Current cell navigation
  • ScrollControlIntoView methods
When to read: Configuring navigation behavior, customizing keyboard shortcuts, or implementing programmatic navigation.
📄 阅读: references/navigation-and-scrolling.md
  • 导航栏配置
  • 滚动选项与行为
  • 键盘导航
  • 当前单元格导航
  • ScrollControlIntoView方法
适用场景: 配置导航行为、自定义快捷键、实现程序化导航。

Clipboard Operations

剪贴板操作

📄 Read: references/clipboard-operations.md
  • Copy/paste operations
  • Clipboard formats (Text, CSV, HTML)
  • Cut operations
  • Clipboard customization
  • CopyPaste events
When to read: Implementing copy/paste functionality, customizing clipboard formats, or handling clipboard events.
📄 阅读: references/clipboard-operations.md
  • 复制/粘贴操作
  • 剪贴板格式(文本、CSV、HTML)
  • 剪切操作
  • 剪贴板自定义
  • CopyPaste事件
适用场景: 实现复制/粘贴功能、自定义剪贴板格式、响应剪贴板事件。

Exporting Data

数据导出

📄 Read: references/exporting.md
  • Excel export with ExcelExportingOptions
  • PDF export with PdfExportingOptions
  • CSV export
  • HTML export
  • Word export
  • Export options and customization
When to read: Implementing data export features, customizing export formats, or configuring export options.
📄 阅读: references/exporting.md
  • 基于ExcelExportingOptions的Excel导出
  • 基于PdfExportingOptions的PDF导出
  • CSV导出
  • HTML导出
  • Word导出
  • 导出选项与自定义
适用场景: 实现数据导出功能、自定义导出格式、配置导出选项。

Printing

打印

📄 Read: references/printing.md
  • Print configuration and setup
  • Print preview
  • Print settings (margins, orientation, scaling)
  • Custom print layouts
  • PrintDocument integration
When to read: Implementing print functionality, customizing print layouts, or configuring print settings.
📄 阅读: references/printing.md
  • 打印配置与设置
  • 打印预览
  • 打印设置(边距、方向、缩放)
  • 自定义打印布局
  • PrintDocument集成
适用场景: 实现打印功能、自定义打印布局、配置打印设置。

Performance Optimization

性能优化

📄 Read: references/performance.md
  • Virtualization for large datasets
  • Handling millions of records
  • Performance optimization tips
  • Best practices for data binding
  • Memory management
When to read: Optimizing grid performance, handling large datasets, or troubleshooting performance issues.
📄 阅读: references/performance.md
  • 面向大数据集的虚拟化
  • 处理百万级记录
  • 性能优化技巧
  • 数据绑定最佳实践
  • 内存管理
适用场景: 优化网格性能、处理大数据集、排查性能问题。

Events Reference

事件参考

📄 Read: references/events.md
  • Data-related events (QueryValue, SaveValue)
  • UI interaction events (CellClick, CellDoubleClick)
  • Grouping events (GroupExpanding, GroupExpanded)
  • Sorting events (SortedColumns.Changing/Changed)
  • Filtering events (RecordFilters.Changing/Changed)
  • Editing events (CurrentCellStartEditing, EditingComplete)
  • Complete event reference with examples
When to read: Handling grid events, implementing event-driven logic, or responding to user interactions.
📄 阅读: references/events.md
  • 数据相关事件(QueryValue、SaveValue)
  • UI交互事件(CellClick、CellDoubleClick)
  • 分组事件(GroupExpanding、GroupExpanded)
  • 排序事件(SortedColumns.Changing/Changed)
  • 过滤事件(RecordFilters.Changing/Changed)
  • 编辑事件(CurrentCellStartEditing、EditingComplete)
  • 完整事件参考与示例
适用场景: 处理网格事件、实现事件驱动逻辑、响应用户交互。

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • Expression fields for calculated columns
  • Data validation rules
  • Find and replace functionality
  • Serialization (Binary, SOAP, XML)
  • Touch support for tablets
  • Zooming capabilities
When to read: Implementing calculated columns, validation rules, find/replace, serialization, or touch support.
📄 阅读: references/advanced-features.md
  • 用于计算列的表达式字段
  • 数据校验规则
  • 查找替换功能
  • 序列化(二进制、SOAP、XML)
  • 平板设备触控支持
  • 缩放能力
适用场景: 实现计算列、校验规则、查找替换、序列化、触控支持。

Troubleshooting

故障排查

📄 Read: references/troubleshooting.md
  • Common issues and solutions
  • Performance troubleshooting
  • Data binding issues
  • UI rendering problems
  • Best practices and guidelines
When to read: Debugging issues, resolving errors, or optimizing implementation.
📄 阅读: references/troubleshooting.md
  • 常见问题与解决方案
  • 性能排查
  • 数据绑定问题
  • UI渲染问题
  • 最佳实践与指导规范
适用场景: 调试问题、解决错误、优化实现。

Quick Start Example

快速入门示例

Here's a minimal example to get started with GridGroupingControl:
csharp
using Syncfusion.Windows.Forms.Grid.Grouping;
using System.Data;

// Create the control
GridGroupingControl gridGroupingControl1 = new GridGroupingControl();
gridGroupingControl1.Dock = DockStyle.Fill;
this.Controls.Add(gridGroupingControl1);

// Create sample data
DataTable dataTable = new DataTable("Employees");
dataTable.Columns.Add("ID", typeof(int));
dataTable.Columns.Add("Name", typeof(string));
dataTable.Columns.Add("Department", typeof(string));
dataTable.Columns.Add("Salary", typeof(decimal));

dataTable.Rows.Add(1, "John Smith", "Sales", 50000);
dataTable.Rows.Add(2, "Sarah Jones", "Marketing", 55000);
dataTable.Rows.Add(3, "Mike Wilson", "Sales", 52000);
dataTable.Rows.Add(4, "Lisa Brown", "Marketing", 58000);
dataTable.Rows.Add(5, "Tom Davis", "IT", 65000);

// Bind data source
gridGroupingControl1.DataSource = dataTable;

// Enable grouping with GroupDropArea
gridGroupingControl1.ShowGroupDropArea = true;

// Add a group by Department
gridGroupingControl1.TableDescriptor.GroupedColumns.Add("Department");

// Add a summary to show total salary per group
GridSummaryColumnDescriptor summaryColumn = new GridSummaryColumnDescriptor();
summaryColumn.MappingName = "Salary";
summaryColumn.SummaryType = SummaryType.DoubleAggregate;
summaryColumn.Format = "{Sum:C}";
summaryColumn.Name = "TotalSalary";

GridSummaryRowDescriptor summaryRow = new GridSummaryRowDescriptor();
summaryRow.SummaryColumns.Add(summaryColumn);
gridGroupingControl1.TableDescriptor.SummaryRows.Add(summaryRow);

// Enable sorting
gridGroupingControl1.TableOptions.AllowSortColumns = true;
This creates a grouped grid with department grouping and salary summaries.
以下是GridGroupingControl的最小实现示例:
csharp
using Syncfusion.Windows.Forms.Grid.Grouping;
using System.Data;

// 创建控件
GridGroupingControl gridGroupingControl1 = new GridGroupingControl();
gridGroupingControl1.Dock = DockStyle.Fill;
this.Controls.Add(gridGroupingControl1);

// 创建示例数据
DataTable dataTable = new DataTable("Employees");
dataTable.Columns.Add("ID", typeof(int));
dataTable.Columns.Add("Name", typeof(string));
dataTable.Columns.Add("Department", typeof(string));
dataTable.Columns.Add("Salary", typeof(decimal));

dataTable.Rows.Add(1, "John Smith", "Sales", 50000);
dataTable.Rows.Add(2, "Sarah Jones", "Marketing", 55000);
dataTable.Rows.Add(3, "Mike Wilson", "Sales", 52000);
dataTable.Rows.Add(4, "Lisa Brown", "Marketing", 58000);
dataTable.Rows.Add(5, "Tom Davis", "IT", 65000);

// 绑定数据源
gridGroupingControl1.DataSource = dataTable;

// 启用分组与分组拖放区域
gridGroupingControl1.ShowGroupDropArea = true;

// 按部门字段添加分组
gridGroupingControl1.TableDescriptor.GroupedColumns.Add("Department");

// 添加汇总展示每个分组的薪资总和
GridSummaryColumnDescriptor summaryColumn = new GridSummaryColumnDescriptor();
summaryColumn.MappingName = "Salary";
summaryColumn.SummaryType = SummaryType.DoubleAggregate;
summaryColumn.Format = "{Sum:C}";
summaryColumn.Name = "TotalSalary";

GridSummaryRowDescriptor summaryRow = new GridSummaryRowDescriptor();
summaryRow.SummaryColumns.Add(summaryColumn);
gridGroupingControl1.TableDescriptor.SummaryRows.Add(summaryRow);

// 启用排序
gridGroupingControl1.TableOptions.AllowSortColumns = true;
以上代码会创建一个按部门分组、带薪资汇总的分组网格。

Common Patterns

常用模式

Master-Detail Pattern with Nested Tables

嵌套表主从模式

csharp
// Assuming Orders and OrderDetails are related tables in a DataSet
DataSet dataSet = GetOrdersDataSet(); // Your data source

// Bind to parent table
gridGroupingControl1.DataSource = dataSet;
gridGroupingControl1.DataMember = "Orders";

// Nested tables are automatically detected from DataSet relations
// Customize child table appearance
GridRelationDescriptor relation = gridGroupingControl1.TableDescriptor.Relations[0];
relation.ChildTableDescriptor.Appearance.AlternateRecordFieldCell.BackColor = Color.LightBlue;
csharp
// 假设Orders和OrderDetails是DataSet中的关联表
DataSet dataSet = GetOrdersDataSet(); // 你的数据源

// 绑定父表
gridGroupingControl1.DataSource = dataSet;
gridGroupingControl1.DataMember = "Orders";

// 嵌套表会自动从DataSet的关系中检测到
// 自定义子表外观
GridRelationDescriptor relation = gridGroupingControl1.TableDescriptor.Relations[0];
relation.ChildTableDescriptor.Appearance.AlternateRecordFieldCell.BackColor = Color.LightBlue;

Dynamic Filtering Pattern

动态过滤模式

csharp
using Syncfusion.GridHelperClasses;

// Wire dynamic filter
GridDynamicFilter dynamicFilter = new GridDynamicFilter();
dynamicFilter.WireGrid(gridGroupingControl1);

// Enable filter bar
gridGroupingControl1.TopLevelGroupOptions.ShowFilterBar = true;

// Enable filtering for specific columns
foreach (GridColumnDescriptor column in gridGroupingControl1.TableDescriptor.Columns)
{
    column.AllowFilter = true;
}
csharp
using Syncfusion.GridHelperClasses;

// 绑定动态过滤
GridDynamicFilter dynamicFilter = new GridDynamicFilter();
dynamicFilter.WireGrid(gridGroupingControl1);

// 启用过滤栏
gridGroupingControl1.TopLevelGroupOptions.ShowFilterBar = true;

// 为所有列启用过滤
foreach (GridColumnDescriptor column in gridGroupingControl1.TableDescriptor.Columns)
{
    column.AllowFilter = true;
}

Excel-Like Filtering Pattern

类Excel过滤模式

csharp
using Syncfusion.GridHelperClasses;

// Create and wire Excel filter
GridExcelFilter excelFilter = new GridExcelFilter();
excelFilter.AllowSearch = true; // Enable search in filter dropdown
excelFilter.AllowResize = true; // Allow resizing filter popup
excelFilter.EnableNumberFilter = true; // Enable number filters
excelFilter.EnableDateFilter = true; // Enable date filters
excelFilter.AllowFilterByColor = true; // Enable filter by cell color

excelFilter.WireGrid(gridGroupingControl1);
csharp
using Syncfusion.GridHelperClasses;

// 创建并绑定Excel过滤
GridExcelFilter excelFilter = new GridExcelFilter();
excelFilter.AllowSearch = true; // 启用过滤下拉框搜索
excelFilter.AllowResize = true; // 允许调整过滤弹窗大小
excelFilter.EnableNumberFilter = true; // 启用数字过滤
excelFilter.EnableDateFilter = true; // 启用日期过滤
excelFilter.AllowFilterByColor = true; // 启用按单元格颜色过滤

excelFilter.WireGrid(gridGroupingControl1);

Programmatic Grouping Pattern

程序化分组模式

csharp
// Multi-level grouping
gridGroupingControl1.TableDescriptor.GroupedColumns.Add("Country");
gridGroupingControl1.TableDescriptor.GroupedColumns.Add("City");

// Customize group options
gridGroupingControl1.TopLevelGroupOptions.ShowCaption = true;
gridGroupingControl1.TopLevelGroupOptions.ShowGroupHeader = true;
gridGroupingControl1.TopLevelGroupOptions.ShowGroupFooter = true;

// Customize caption text with tokens
gridGroupingControl1.ChildGroupOptions.CaptionText = 
    "{CategoryName}: {Category} ({RecordCount} items)";
csharp
// 多级分组
gridGroupingControl1.TableDescriptor.GroupedColumns.Add("Country");
gridGroupingControl1.TableDescriptor.GroupedColumns.Add("City");

// 自定义分组选项
gridGroupingControl1.TopLevelGroupOptions.ShowCaption = true;
gridGroupingControl1.TopLevelGroupOptions.ShowGroupHeader = true;
gridGroupingControl1.TopLevelGroupOptions.ShowGroupFooter = true;

// 使用占位符自定义标题文本
gridGroupingControl1.ChildGroupOptions.CaptionText = 
    "{CategoryName}: {Category} ({RecordCount} items)";

Conditional Formatting Pattern

条件格式模式

csharp
// Apply conditional formatting based on cell value
gridGroupingControl1.QueryCellStyleInfo += (sender, e) =>
{
    if (e.TableCellIdentity.TableCellType == GridTableCellType.RecordFieldCell)
    {
        if (e.TableCellIdentity.Column.Name == "Salary")
        {
            decimal salary = Convert.ToDecimal(e.Style.CellValue);
            if (salary > 60000)
            {
                e.Style.BackColor = Color.LightGreen;
                e.Style.Font.Bold = true;
            }
            else if (salary < 40000)
            {
                e.Style.BackColor = Color.LightCoral;
            }
        }
    }
};
csharp
// 基于单元格值应用条件格式
gridGroupingControl1.QueryCellStyleInfo += (sender, e) =>
{
    if (e.TableCellIdentity.TableCellType == GridTableCellType.RecordFieldCell)
    {
        if (e.TableCellIdentity.Column.Name == "Salary")
        {
            decimal salary = Convert.ToDecimal(e.Style.CellValue);
            if (salary > 60000)
            {
                e.Style.BackColor = Color.LightGreen;
                e.Style.Font.Bold = true;
            }
            else if (salary < 40000)
            {
                e.Style.BackColor = Color.LightCoral;
            }
        }
    }
};

Summary Pattern

汇总模式

csharp
// Add multiple summaries for a group
GridSummaryRowDescriptor summaryRow = new GridSummaryRowDescriptor();
summaryRow.ShowSummaryInRow = false; // Show in separate columns

// Count summary
GridSummaryColumnDescriptor countColumn = new GridSummaryColumnDescriptor(
    "Count", SummaryType.Count, "ID", "{Count}");
summaryRow.SummaryColumns.Add(countColumn);

// Average summary
GridSummaryColumnDescriptor avgColumn = new GridSummaryColumnDescriptor(
    "Average", SummaryType.DoubleAggregate, "Salary", "Avg: {Average:C}");
summaryRow.SummaryColumns.Add(avgColumn);

// Total summary
GridSummaryColumnDescriptor sumColumn = new GridSummaryColumnDescriptor(
    "Total", SummaryType.DoubleAggregate, "Salary", "Total: {Sum:C}");
summaryRow.SummaryColumns.Add(sumColumn);

gridGroupingControl1.TableDescriptor.SummaryRows.Add(summaryRow);
csharp
// 为分组添加多个汇总
GridSummaryRowDescriptor summaryRow = new GridSummaryRowDescriptor();
summaryRow.ShowSummaryInRow = false; // 在独立列中展示

// 计数汇总
GridSummaryColumnDescriptor countColumn = new GridSummaryColumnDescriptor(
    "Count", SummaryType.Count, "ID", "{Count}");
summaryRow.SummaryColumns.Add(countColumn);

// 平均值汇总
GridSummaryColumnDescriptor avgColumn = new GridSummaryColumnDescriptor(
    "Average", SummaryType.DoubleAggregate, "Salary", "Avg: {Average:C}");
summaryRow.SummaryColumns.Add(avgColumn);

// 总和汇总
GridSummaryColumnDescriptor sumColumn = new GridSummaryColumnDescriptor(
    "Total", SummaryType.DoubleAggregate, "Salary", "Total: {Sum:C}");
summaryRow.SummaryColumns.Add(sumColumn);

gridGroupingControl1.TableDescriptor.SummaryRows.Add(summaryRow);

Key Properties

核心属性

Core Properties

基础属性

PropertyTypeDescription
DataSource
objectGets or sets the data source for the grid
DataMember
stringGets or sets the data member within the data source
ShowGroupDropArea
boolShows or hides the group drop area for drag-drop grouping
TableDescriptor
GridTableDescriptorProvides access to table configuration and columns
TableOptions
GridTableOptionsStyleInfoConfigures table-level options
TopLevelGroupOptions
GridGroupOptionsStyleInfoConfigures options for top-level groups
ChildGroupOptions
GridGroupOptionsStyleInfoConfigures options for child groups
属性类型描述
DataSource
object获取或设置网格的数据源
DataMember
string获取或设置数据源中的数据成员
ShowGroupDropArea
bool展示或隐藏用于拖拽分组的分组拖放区域
TableDescriptor
GridTableDescriptor提供表格配置和列的访问入口
TableOptions
GridTableOptionsStyleInfo配置表格级别的选项
TopLevelGroupOptions
GridGroupOptionsStyleInfo配置顶级分组的选项
ChildGroupOptions
GridGroupOptionsStyleInfo配置子分组的选项

Collection Properties

集合属性

PropertyTypeDescription
TableDescriptor.GroupedColumns
SortColumnDescriptorCollectionColumns by which data is grouped
TableDescriptor.SortedColumns
SortColumnDescriptorCollectionColumns by which data is sorted
TableDescriptor.RecordFilters
RecordFilterDescriptorCollectionProgrammatic record filters
TableDescriptor.SummaryRows
GridSummaryRowDescriptorCollectionSummary row definitions
TableDescriptor.Columns
GridColumnDescriptorCollectionColumn descriptors
TableDescriptor.Relations
GridRelationDescriptorCollectionChild table relations
属性类型描述
TableDescriptor.GroupedColumns
SortColumnDescriptorCollection数据分组依据的列集合
TableDescriptor.SortedColumns
SortColumnDescriptorCollection数据排序依据的列集合
TableDescriptor.RecordFilters
RecordFilterDescriptorCollection程序化记录过滤规则集合
TableDescriptor.SummaryRows
GridSummaryRowDescriptorCollection汇总行定义集合
TableDescriptor.Columns
GridColumnDescriptorCollection列描述符集合
TableDescriptor.Relations
GridRelationDescriptorCollection子表关系集合

Key Events

核心事件

Data Events

数据事件

  • QueryValue
    - Raised when grid needs to retrieve unbound cell values
  • SaveValue
    - Raised when grid needs to save unbound cell values
  • SourceListListChanged
    - Raised when bound data source changes
  • QueryValue
    - 网格需要获取非绑定单元格值时触发
  • SaveValue
    - 网格需要保存非绑定单元格值时触发
  • SourceListListChanged
    - 绑定的数据源发生变更时触发

UI Events

UI事件

  • QueryCellStyleInfo
    - Raised to customize cell appearance dynamically
  • TableControlCellClick
    - Raised when a cell is clicked
  • TableControlCellDoubleClick
    - Raised when a cell is double-clicked
  • TableControlCurrentCellActivated
    - Raised when a cell becomes current
  • QueryCellStyleInfo
    - 动态自定义单元格外观时触发
  • TableControlCellClick
    - 单元格被点击时触发
  • TableControlCellDoubleClick
    - 单元格被双击时触发
  • TableControlCurrentCellActivated
    - 单元格成为当前激活单元格时触发

Grouping Events

分组事件

  • GroupExpanding
    /
    GroupExpanded
    - Raised when groups expand
  • GroupCollapsing
    /
    GroupCollapsed
    - Raised when groups collapse
  • GroupedColumns.Changing
    /
    Changed
    - Raised when grouping changes
  • GroupExpanding
    /
    GroupExpanded
    - 分组展开时触发
  • GroupCollapsing
    /
    GroupCollapsed
    - 分组收起时触发
  • GroupedColumns.Changing
    /
    Changed
    - 分组规则变更时触发

Sorting Events

排序事件

  • SortedColumns.Changing
    /
    Changed
    - Raised when sorting changes
  • TableControlQueryAllowSortColumn
    - Raised to control column sorting
  • SortedColumns.Changing
    /
    Changed
    - 排序规则变更时触发
  • TableControlQueryAllowSortColumn
    - 控制列是否可排序时触发

Filtering Events

过滤事件

  • RecordFilters.Changing
    /
    Changed
    - Raised when filters change
  • GridExcelFilter.RecordFiltersItemChanging
    /
    Changed
    - Excel filter events
  • RecordFilters.Changing
    /
    Changed
    - 过滤规则变更时触发
  • GridExcelFilter.RecordFiltersItemChanging
    /
    Changed
    - Excel过滤相关事件

Editing Events

编辑事件

  • TableControlCurrentCellStartEditing
    - Raised when cell editing begins
  • TableControlCurrentCellEditingComplete
    - Raised when cell editing completes
  • TableControlCurrentCellValidating
    - Raised to validate cell values
  • TableControlCurrentCellStartEditing
    - 单元格开始编辑时触发
  • TableControlCurrentCellEditingComplete
    - 单元格编辑完成时触发
  • TableControlCurrentCellValidating
    - 校验单元格值时触发

Common Use Cases

常见使用场景

Business Intelligence Dashboards

商业智能仪表盘

Display complex data with multi-level grouping, drill-down capabilities, and aggregate summaries for business analytics and reporting.
展示带多级分组、下钻能力和聚合汇总的复杂数据,用于业务分析和报表展示。

Data Management Applications

数据管理应用

Build CRUD applications with master-detail forms, inline editing, validation, and advanced filtering for data management.
构建带主从表单、行内编辑、校验和高级过滤的CRUD应用,用于数据管理。

Hierarchical Data Visualization

层级数据可视化

Display organizational structures, product categories, or any hierarchical data with nested groups and expandable sections.
展示组织结构、产品分类或任意层级数据,支持嵌套分组和可展开区块。

Reporting Applications

报表应用

Generate rich reports with grouping, summaries, conditional formatting, and export to multiple formats (Excel, PDF, Word).
生成带分组、汇总、条件格式的丰富报表,支持导出为多种格式(Excel、PDF、Word)。

Data Analysis Tools

数据分析工具

Implement interactive data exploration with dynamic grouping, sorting, filtering, and summary calculations.
实现交互式数据探索,支持动态分组、排序、过滤和汇总计算。

Architecture Notes

架构说明

Engine Architecture

引擎架构

GridGroupingControl uses a unique engine-based architecture that separates data management (Engine) from display (TableControl). This enables:
  • Multiple views of the same data
  • Efficient data virtualization
  • Flexible grouping and sorting
  • Independent nested table handling
GridGroupingControl采用独特的基于引擎的架构,将数据管理(引擎)与展示(TableControl)分离。这一设计实现了:
  • 同一数据的多视图展示
  • 高效的数据虚拟化
  • 灵活的分组与排序
  • 独立的嵌套表处理

Display Elements

展示元素

The grid organizes content into display elements:
  • Records - Individual data rows
  • Groups - Collections of records with matching category values
  • CaptionRows - Group header rows
  • SummaryRows - Aggregate summary rows
  • FilterBarCell - Filter input cells
网格将内容组织为不同的展示元素:
  • 记录(Records) - 单独的数据行
  • 分组(Groups) - 具有相同分类值的记录集合
  • 标题行(CaptionRows) - 分组头部行
  • 汇总行(SummaryRows) - 聚合汇总行
  • 过滤栏单元格(FilterBarCell) - 过滤输入单元格

Table Hierarchy

表格层级

  • GridTable - Top-level table instance
  • GridNestedTable - Child table in master-detail relationship
  • TopLevelGroup - Root group containing all records
  • Groups - Nested group collections
  • GridTable - 顶级表格实例
  • GridNestedTable - 主从关系中的子表
  • TopLevelGroup - 包含所有记录的根分组
  • Groups - 嵌套分组集合

Best Practices

最佳实践

  1. Data Binding: Use strongly-typed collections implementing IBindingList for automatic change notifications
  2. Performance: Enable virtualization for large datasets (handled automatically)
  3. Grouping: Limit initial grouping levels to 2-3 for better user experience
  4. Filtering: Use GridExcelFilter for user-friendly filtering experience
  5. Summaries: Place summaries strategically in captions or footers based on use case
  6. Styling: Use QueryCellStyleInfo for dynamic styling instead of setting styles for all cells
  7. Events: Minimize work in frequently-fired events like QueryCellStyleInfo
  8. Memory: Dispose of GridGroupingControl properly when form closes
  1. 数据绑定: 使用实现了IBindingList的强类型集合,可获得自动变更通知能力
  2. 性能: 大数据集启用虚拟化(默认自动处理)
  3. 分组: 初始分组层级限制为2-3级,可获得更好的用户体验
  4. 过滤: 使用GridExcelFilter获得用户友好的过滤体验
  5. 汇总: 根据使用场景将汇总合理放置在标题或底部
  6. 样式: 使用QueryCellStyleInfo实现动态样式,避免为所有单元格单独设置样式
  7. 事件: 减少在高频触发事件(如QueryCellStyleInfo)中的处理逻辑
  8. 内存: 窗体关闭时正确释放GridGroupingControl资源

Related Components

相关组件

  • GridControl - Standard non-grouping grid for simpler scenarios
  • GridDataBoundGrid - Lightweight data-bound grid
  • DataGrid - Standard .NET DataGrid control
Use GridGroupingControl when you need grouping, summaries, and hierarchical features. Use simpler grids for basic data display.
  • GridControl - 适用于简单场景的标准非分组网格
  • GridDataBoundGrid - 轻量级数据绑定网格
  • DataGrid - 标准.NET DataGrid控件
当你需要分组、汇总和层级功能时使用GridGroupingControl,基础数据展示可使用更简单的网格组件。

Documentation Links

文档链接


Next Steps: For detailed implementation guidance, navigate to the specific reference files above based on your requirements. Start with getting-started.md for initial setup.

后续步骤: 如需详细的实现指导,可根据你的需求跳转到上述对应的参考文件。初始配置可从getting-started.md开始。