[]
GcExcel Java 支持对数据透视表字段进行分组,实现更高效的数据汇总。你可以按日期或时间单位对日期字段分组、将数值字段划分为区间,还能把选中项归为自定义类别。
调用 IPivotField 接口的 group 方法即可对数据透视表字段执行分组操作。GcExcel 还支持重命名分组项,不再需要分组时也可以取消分组。在刷新数据透视表、更新内容、调整布局,以及导入导出 JSON、SJS、XLSX 文件后,分组信息会予以保留。
重要说明:
如果数据透视缓存包含计算项,则不支持对该缓存内的字段进行分组。
刷新后若源数据类型发生变更,原有分组可能无法继续保留。例如:原本纯日期字段变为混合数据字段时,日期分组会被移除,该字段不再满足分组条件。
当多个数据透视表共用同一个 IPivotCache 时,分组改动会同步作用于所有依赖该缓存的数据透视表。
借助日期分组,可以按照一个或多个时间单位(秒、分钟、小时、日、月、季度、年)整理日期字段。你也可以自定义区间,例如7天间隔(用于周维度分析)或是适配业务场景的其他时间跨度。启用分组后,GcExcel Java 会为选定的时间单位生成分组字段。例如:将订单日期(Order Date)字段按年和季度分组,会新增年份(订单日期)与季度(订单日期)这类分组字段。
你可以通过 PivotFieldDateGroupOptions 的 setStart、setEnd、setAutoStart、setAutoEnd 方法控制分组范围。若使用按日分组,可通过 setDays 方法指定每组包含的天数。
参考下方示例代码,实现按年、月对日期字段分组:
// 创建新工作簿
Workbook workbook = new Workbook();
workbook.getOptions().getData().setAutomaticGroupDateTimeInPivotTable(false);
// 设置数据源
Object[][] sourceData = new Object[][] {
{ "Order ID", "Product", "Order Date", "Sales" },
{ 1001, "Apple", java.time.LocalDateTime.of(2024, 1, 5, 0, 0), 120d },
{ 1002, "Banana", java.time.LocalDateTime.of(2024, 1, 12, 0, 0), 95d },
{ 1003, "Carrot", java.time.LocalDateTime.of(2024, 2, 3, 0, 0), 150d },
{ 1004, "Dates", java.time.LocalDateTime.of(2024, 2, 18, 0, 0), 90d },
{ 1005, "Eggplant", java.time.LocalDateTime.of(2024, 3, 6, 0, 0), 180d },
{ 1006, "Fig", java.time.LocalDateTime.of(2024, 3, 21, 0, 0), 160d },
{ 1007, "Grapes", java.time.LocalDateTime.of(2025, 1, 9, 0, 0), 140d },
{ 1008, "Honey", java.time.LocalDateTime.of(2025, 2, 15, 0, 0), 210d },
{ 1009, "Ice Tea", java.time.LocalDateTime.of(2025, 3, 11, 0, 0), 80d },
};
IWorksheet worksheet = workbook.getWorksheets().get(0);
worksheet.getRange("G1:J10").setValue(sourceData);
worksheet.getRange("I2:I10").setNumberFormat("m/d/yyyy");
worksheet.getRange("J2:J10").setNumberFormat("$#,##0.00");
// 添加数据透视表
IPivotCache pivotcache = workbook.getPivotCaches().create(worksheet.getRange("G1:J10"));
IPivotTable pivottable = worksheet.getPivotTables().add(
pivotcache,
worksheet.getRange("A1"),
"dateGroupPivot"
);
IPivotField fieldOrderDate = pivottable.getPivotFields().get("Order Date");
fieldOrderDate.setOrientation(PivotFieldOrientation.RowField);
IPivotField fieldSales = pivottable.getPivotFields().get("Sales");
fieldSales.setOrientation(PivotFieldOrientation.DataField);
fieldSales.setNumberFormat("$#,##0.00");
// 将“Order Date”字段按年、月分组
PivotFieldDateGroupOptions options = new PivotFieldDateGroupOptions();
options.setGroupBy(java.util.Arrays.asList(
PivotFieldDateGroupBy.Months,
PivotFieldDateGroupBy.Years
));
fieldOrderDate.group(options);
worksheet.getRange("A:J").getEntireColumn().autoFit();
// 保存为Excel文件
workbook.save("DateGroup.xlsx");输出效果如下图所示:

如果你需要按固定时长汇总日期数据(例如以7天为周期做周维度分析),可以使用按日分组。
参考下方示例代码,将日期字段划分为7天区间分组:
// 创建新工作簿
Workbook workbook = new Workbook();
workbook.getOptions().getData().setAutomaticGroupDateTimeInPivotTable(false);
// 设置数据源
Object[][] sourceData = new Object[][] {
{ "Order ID", "Product", "Order Date", "Sales" },
{ 1001, "Apple", java.time.LocalDateTime.of(2024, 1, 2, 0, 0), 120d },
{ 1002, "Banana", java.time.LocalDateTime.of(2024, 1, 5, 0, 0), 95d },
{ 1003, "Carrot", java.time.LocalDateTime.of(2024, 1, 9, 0, 0), 150d },
{ 1004, "Dates", java.time.LocalDateTime.of(2024, 1, 12, 0, 0), 90d },
{ 1005, "Eggplant", java.time.LocalDateTime.of(2024, 1, 16, 0, 0), 180d },
{ 1006, "Fig", java.time.LocalDateTime.of(2024, 1, 19, 0, 0), 160d },
{ 1007, "Grapes", java.time.LocalDateTime.of(2024, 1, 24, 0, 0), 140d },
{ 1008, "Honey", java.time.LocalDateTime.of(2024, 1, 27, 0, 0), 210d },
{ 1009, "Ice Tea", java.time.LocalDateTime.of(2024, 1, 30, 0, 0), 80d },
};
IWorksheet worksheet = workbook.getWorksheets().get(0);
worksheet.getRange("G1:J10").setValue(sourceData);
worksheet.getRange("I2:I10").setNumberFormat("m/d/yyyy");
worksheet.getRange("J2:J10").setNumberFormat("$#,##0.00");
// 添加数据透视表
IPivotCache pivotcache = workbook.getPivotCaches().create(worksheet.getRange("G1:J10"));
IPivotTable pivottable = worksheet.getPivotTables().add(
pivotcache,
worksheet.getRange("A1"),
"dayGroupPivot"
);
IPivotField fieldOrderDate = pivottable.getPivotFields().get("Order Date");
fieldOrderDate.setOrientation(PivotFieldOrientation.RowField);
IPivotField fieldSales = pivottable.getPivotFields().get("Sales");
fieldSales.setOrientation(PivotFieldOrientation.DataField);
fieldSales.setNumberFormat("$#,##0.00");
// 将“Order Date”字段按7天区间分组
PivotFieldDateGroupOptions options = new PivotFieldDateGroupOptions();
options.setGroupBy(java.util.Collections.singletonList(PivotFieldDateGroupBy.Days));
options.setDays(7);
options.setStart(java.time.LocalDateTime.of(2024, 1, 1, 0, 0));
options.setEnd(java.time.LocalDateTime.of(2024, 1, 31, 0, 0));
options.setAutoStart(false);
options.setAutoEnd(false);
fieldOrderDate.group(options);
worksheet.getRange("A:J").getEntireColumn().autoFit();
// 保存为Excel文件
workbook.save("DayGroup.xlsx");输出效果如下图所示:

日期分组会根据选定的日期/时间单位生成新字段。默认情况下,如果基础字段放置在行区域或列区域,GcExcel Java 会自动将生成的分组字段添加至同一布局区域。
你可以使用 PivotFieldDateGroupOptions 的 setAddGeneratedFieldsToLayout 方法控制该行为,默认值为 true。若基础字段不在行、列区域内,该方法不生效,不会新增生成字段到布局。
如果你不希望分组完成后自动把生成字段插入数据透视表布局,可以将该方法设置为 false。
注意:当多个数据透视表共用同一个 IPivotCache 时,该配置十分有用。可以避免在当前透视表对字段分组时,改动其他透视表的布局。
// 将“Order Date”按年、月分组,但不自动将生成字段添加到布局
PivotFieldDateGroupOptions options = new PivotFieldDateGroupOptions();
options.setGroupBy(java.util.Arrays.asList(
PivotFieldDateGroupBy.Years,
PivotFieldDateGroupBy.Months
));
options.setAddGeneratedFieldsToLayout(false);
fieldOrderDate.group(options);GcExcel Java 还支持通过 setAutomaticGroupDateTimeInPivotTable 方法实现日期自动分组,该方法默认值为 true。启用后,创建或刷新数据透视表、把日期字段放置在行/列区域时,会自动创建日期分组,行为与Excel保持兼容。
重要说明:
日期分组仅可用于纯日期字段。若字段包含混合类型或非日期数据,调用 group 方法会抛出异常。
同一日期字段多次分组时,之前的分组不会保留,仅最后一次分组生效。例如:先按年、月分组,之后再次按年、季度分组,最终只会保留年和季度字段。
数值分组能够依据起始值、终止值与间隔,将数值字段划分成多个区间。
数值分组会在原始基础字段上把数值划分到不同区间桶,不会生成额外的分组字段。区间标签由基础字段以及配置的起止范围、间隔自动生成。
你可以调用 PivotFieldNumberGroupOptions 的 setStart、setEnd、setAutoStart、setAutoEnd 方法控制分组区间。
参考下方示例代码,实现数值字段区间分组:
// 创建新工作簿
Workbook workbook = new Workbook();
// 设置数据源
Object[][] sourceData = new Object[][] {
{ "Order ID", "Product", "Shipping Fee", "Sales" },
{ 1001, "Apple", 18d, 120d },
{ 1002, "Banana", 42d, 95d },
{ 1003, "Carrot", 68d, 150d },
{ 1004, "Dates", 85d, 90d },
{ 1005, "Eggplant", 110d, 180d },
{ 1006, "Fig", 135d, 160d },
{ 1007, "Grapes", 170d, 140d },
{ 1008, "Honey", 205d, 210d },
{ 1009, "Ice Tea", 28d, 80d },
};
IWorksheet worksheet = workbook.getWorksheets().get(0);
worksheet.getRange("G1:J10").setValue(sourceData);
worksheet.getRange("I2:J10").setNumberFormat("$#,##0.00");
// 添加数据透视表
IPivotCache pivotcache = workbook.getPivotCaches().create(worksheet.getRange("G1:J10"));
IPivotTable pivottable = worksheet.getPivotTables().add(
pivotcache,
worksheet.getRange("A1"),
"numberGroupPivot"
);
IPivotField fieldShippingFee = pivottable.getPivotFields().get("Shipping Fee");
fieldShippingFee.setOrientation(PivotFieldOrientation.RowField);
IPivotField fieldSales = pivottable.getPivotFields().get("Sales");
fieldSales.setOrientation(PivotFieldOrientation.DataField);
fieldSales.setNumberFormat("$#,##0.00");
// 将“Shipping Fee”字段按数值区间分组
// 定义分组范围:0 ~ 250,间隔50
PivotFieldNumberGroupOptions options = new PivotFieldNumberGroupOptions();
options.setStart(0d);
options.setEnd(250d);
options.setAutoStart(false);
options.setAutoEnd(false);
options.setInterval(50d);
fieldShippingFee.group(options);
worksheet.getRange("A:J").getEntireColumn().autoFit();
// 保存为Excel文件
workbook.save("NumberGroup.xlsx");输出效果如下图所示:

重要说明:
数值分组仅支持纯数值字段。字段包含非数字内容时执行分组会抛出异常。
同一数值字段多次分组,新配置会覆盖之前的区间定义。
为兼容Microsoft Excel,对已经完成数值区间分组的字段再次执行自定义分组不会生效。
你可以将选中的数据透视项组合,创建自定义分组。自定义分组会生成新的分组字段。创建分组时,可以使用 PivotFieldCustomGroupOptions 的 setName 方法指定自定义分组名称。自定义分组适用于所有类型字段,包括纯日期字段与数值字段。
如果新建自定义分组与已有分组选中项存在重叠,重叠部分将被新分组覆盖;选中范围互不重叠时,新分组项会添加至生成的分组字段中。
自定义分组支持嵌套分组,你可以基于已有的分组字段再次创建新分组。
和日期分组规则类似,若基础字段放置在行区域或列区域,生成字段是否自动加入布局由 setAddGeneratedFieldsToLayout 方法控制。
参考下方示例代码,对数据透视表字段中的选中项进行分组:
// 创建新工作簿
Workbook workbook = new Workbook();
// 设置数据源
Object[][] sourceData = new Object[][] {
{ "Order ID", "Product", "Region", "Sales" },
{ 1001, "Apple", "East", 120d },
{ 1002, "Banana", "North", 95d },
{ 1003, "Carrot", "South", 150d },
{ 1004, "Dates", "West", 90d },
{ 1005, "Eggplant", "East", 180d },
{ 1006, "Fig", "North", 160d },
{ 1007, "Grapes", "Central", 140d },
{ 1008, "Honey", "South", 210d },
{ 1009, "Ice Tea", "West", 80d },
};
IWorksheet worksheet = workbook.getWorksheets().get(0);
worksheet.getRange("G1:J10").setValue(sourceData);
worksheet.getRange("J2:J10").setNumberFormat("$#,##0.00");
// 添加数据透视表
IPivotCache pivotcache = workbook.getPivotCaches().create(worksheet.getRange("G1:J10"));
IPivotTable pivottable = worksheet.getPivotTables().add(
pivotcache,
worksheet.getRange("A1"),
"customGroupPivot"
);
IPivotField fieldRegion = pivottable.getPivotFields().get("Region");
fieldRegion.setOrientation(PivotFieldOrientation.RowField);
IPivotField fieldSales = pivottable.getPivotFields().get("Sales");
fieldSales.setOrientation(PivotFieldOrientation.DataField);
fieldSales.setNumberFormat("$#,##0.00");
// 在“Region”字段创建自定义分组
// 将“East”和“North”合并为新分组
PivotFieldCustomGroupOptions options = new PivotFieldCustomGroupOptions();
options.setName("Core Regions");
options.setItems(java.util.Arrays.asList("East", "North"));
fieldRegion.group(options);
// 修改透视表内该分组的显示标题
fieldRegion.getPivotItems().get("Core Regions").setCaption("Primary Regions");
worksheet.getRange("A:J").getEntireColumn().autoFit();
// 保存为Excel文件
workbook.save("CustomGroup.xlsx");输出效果如下图所示:

调用 IPivotItem 接口的 setCaption 方法,可以修改分组项的显示名称。
参考下方示例代码,重命名自定义分组生成的分组项:
IPivotItem item = pivotTable.getPivotFields()
.get("Product2")
.getPivotItems()
.get("Group1");
item.setCaption("Fresh Fruit");调用 IPivotField 接口的 ungroup 方法,可以解除数据透视表字段的分组。该方法可作用于原始基础字段,也可作用于生成的分组字段。GcExcel 会清除所有关联分组字段,恢复原始布局。
多个数据透视表共用同一个 IPivotCache 时,取消分组操作会同步更新所有依赖该缓存的数据透视表。
参考下方示例代码,移除数据透视表字段的分组:
orderDateField.ungroup();