SuperAPI AI 工具集

syncfusion-winforms-grouping

数据与分析

查看项目

更新于 10-16 03:00

技能介绍

用途

该技能实现 Syncfusion Grouping Engine(Essential Grouping)。这是一个 100% 原生 .NET 数据管理框架,为表格数据提供排序、分组、过滤和汇总能力,且不依赖任何特定 UI 组件,面向 Windows Forms 应用设计。适用于需要对表格数据进行灵活组织的场景,例如按属性排序、按属性层级分组、按复杂表达式过滤、对数据进行聚合汇总、添加计算字段,以及从任意 IList 数据源(ArrayList、List、BindingList 等)管理数据,也用于展示分组/汇总信息而不依赖 UI 控件。

主要能力

  • 排序:支持按单一或多个属性排序,使用标准或自定义比较逻辑,可指定升序/降序,可通过 IComparer 接口和 SortColumnDescriptor.Comparer 属性实现自定义排序。
  • 分组:通过 TableDescriptor.GroupedColumns 按属性进行层级分组,形成嵌套组;通过 Table.TopLevelGroup 访问分组,可递归遍历 Groups 和 Records,按键值获取特定分组。分组会带来自动排序的副作用。
  • 过滤:使用 RecordFilterDescriptor 搭配表达式过滤记录,通过 Table.FilteredRecords 访问结果。支持逻辑运算符(AND、OR、NOT)、比较运算符(=、<、>、<=、>=、<>)、字符串运算符(LIKE、MATCH、IN、BETWEEN),以及多条件组合过滤。
  • 表达式与汇总:通过 ExpressionFieldDescriptor 创建计算字段(使用属性名的代数表达式),添加到 TableDescriptor.ExpressionFields,并用 Record.GetValue() 取值;通过 SummaryDescriptor 创建聚合(如 Int32Aggregate、DoubleAggregate 等),用 GetSummary() 按分组获取汇总值。
  • 数据绑定:支持用公共属性创建自定义对象,构建 ArrayList 和 IList 数据源,使用 Engine.SetSourceList() 设置数据源,遍历 Table.Records 集合,用 Record.GetData() 访问记录数据。
  • 核心数据结构优势:平衡二叉树实现,插入、删除、移动操作为 O(Log n);缓存父级信息以便快速定位和汇总查询;支持递归多级嵌套分组。

使用方式

先创建 Engine 并调用 SetSourceList() 设置数据源,再通过 TableDescriptor 配置分组、排序、过滤、汇总与表达式字段,然后遍历 Table(Records、FilteredRecords、TopLevelGroup)和 Group(Groups、Records、Name、GetSummary)以及 Record(GetData、GetValue)读取数据。关键属性包括:Engine.Table、Engine.TableDescriptor、Engine.SetSourceList(IList);TableDescriptor.GroupedColumns、SortedColumns、RecordFilters、Summaries、ExpressionFields;Table.Records、FilteredRecords、TopLevelGroup;Group.Groups、Records、Name、GetSummary(string);Record.GetData()、GetValue(string)。

常见模式:过滤后分组工作流(先设置数据源,再添加 RecordFilterDescriptor 过滤,然后添加 GroupedColumns 分组);多级分组(依次添加多个分组列并递归处理嵌套组);动态表达式字段(添加 ExpressionFieldDescriptor 并在过滤中使用,再用 GetValue 取值);自定义排序(实现 IComparer 并赋给 SortedColumns 的 Comparer)。

文档导航包括:references/getting-started.md(安装位置与部署要求、创建 Windows Forms 应用、程序集引用与依赖、Copy Local 属性、部署场景与 GAC、DLL 需求)、references/data-binding.md、references/grouping-data.md、references/sorting.md、references/filtering.md、references/expressions-and-summaries.md。

适用场景

  • 按区域与产品分类生成销售报表并添加销售汇总。
  • 低库存过滤(如 [StockLevel] < [ReorderLevel] AND [Active] = 1)并按紧急度排序。
  • 客户分析:用计算字段得出客户价值并过滤高价值客户,再按客户层级分组。
  • 基于时间的分析:用 BETWEEN 过滤日期范围,并用计算字段按月份分组。
  • 从任意 IList 数据源管理表格数据,构建需要灵活数据组织的桌面数据驱动应用。

限制与注意事项

  • 分组后可能出现空组(过滤后尤其明显),遍历前应检查 Records.Count。
  • 表达式存在类型匹配要求:数值比较用 =,字符串比较用 LIKE 或 MATCH,汇总类型需匹配属性数据类型(如 Int32Aggregate 与 DoubleAggregate)。
  • 递归导航时,每一层级只有 group.Groups 或 group.Records 之一包含元素,需先判断。
  • 过滤表达式语法:属性名必须用方括号包裹如 [PropertyName];字符串字面量用单引号如 'value';IN 运算符列表中的空格有意义,应写为 {value1,value2} 而非 {value1, value2}。
  • 内存管理:Grouping Engine 维护内部数据结构,使用完毕应调用 Dispose() 释放资源。
  • 最佳实践:先调用 SetSourceList() 再配置分组/排序/过滤;有过滤时访问 Table.FilteredRecords 而非 Table.Records;汇总类型与属性类型匹配;复杂表达式影响性能,尽量保持简单;用 GetData() 访问记录数据时检查 null;不再使用时释放 Engine;部署前验证过滤表达式语法以避免运行时错误。
  • 平台说明:Grouping Engine 可独立运行或与 GridGroupingControl 配合,无 UI 依赖,针对桌面应用场景优化。

快速开始示例

代码示例展示了定义自定义数据对象(含 Product、Category、Quantity、Price),用 ArrayList 填充数据,创建 Engine 并 SetSourceList,按 Category 分组,添加 Quantity 的 Int32Aggregate 汇总,然后遍历分组并用 GetSummary 获取汇总、用 GetData 显示记录。

安装位置、部署要求、程序集引用与依赖、价格与收费信息:暂未提供。