分组指南

示例

想要直接跳到实现部分吗？请查看以下示例：

grouping

API

分组 API

有 3 个表格功能可以重新排序列，它们按以下顺序发生：

列固定 - 如果固定，列将分为左侧、中间（未固定）和右侧固定列。
手动列排序 - 应用手动指定的列顺序。
分组 - 如果启用了分组，分组状态处于活动状态，并且 tableOptions.groupedColumnMode 设置为 'reorder' | 'remove'，则分组的列将重新排序到列流的开头。

TanStack table 中的分组是一项应用于列的功能，允许您根据特定列对表格行进行分类和组织。当您拥有大量数据并希望根据某些标准将其分组时，这非常有用。

要使用分组功能，您需要使用分组行模型。此模型负责根据分组状态对行进行分组。

tsx

import { getGroupedRowModel } from '@tanstack/react-table'

const table = useReactTable({
  // 其他选项...
  getGroupedRowModel: getGroupedRowModel(),
})

import { getGroupedRowModel } from '@tanstack/react-table'

const table = useReactTable({
  // 其他选项...
  getGroupedRowModel: getGroupedRowModel(),
})

当分组状态处于活动状态时，表格会将匹配的行添加为分组行的子行。分组行将添加到与第一个匹配行相同索引处的表格行中。匹配的行将从表格行中删除。要允许用户展开和折叠分组行，可以使用展开功能。

tsx

import { getGroupedRowModel, getExpandedRowModel} from '@tanstack/react-table'

const table = useReactTable({
  // 其他选项...
  getGroupedRowModel: getGroupedRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
})

import { getGroupedRowModel, getExpandedRowModel} from '@tanstack/react-table'

const table = useReactTable({
  // 其他选项...
  getGroupedRowModel: getGroupedRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
})

分组状态

分组状态是一个字符串数组，其中每个字符串是要分组的列的 ID。数组中字符串的顺序决定了分组的顺序。例如，如果分组状态为 ['column1', 'column2']，则表格将首先按 column1 分组，然后在每个组内按 column2 分组。您可以使用 setGrouping 函数控制分组状态：

tsx

table.setGrouping(['column1', 'column2']);

table.setGrouping(['column1', 'column2']);

您还可以使用 resetGrouping 函数将分组状态重置为其初始状态：

tsx

table.resetGrouping();

table.resetGrouping();

默认情况下，当对列进行分组时，它会移动到表格的开头。您可以使用 groupedColumnMode 选项控制此行为。如果将其设置为“reorder”，则分组的列将移动到表格的开头。如果将其设置为“remove”，则分组的列将从表格中删除。如果将其设置为 false，则分组的列将不会移动或删除。

tsx

const table = useReactTable({
  // 其他选项...
  groupedColumnMode: 'reorder',
})

const table = useReactTable({
  // 其他选项...
  groupedColumnMode: 'reorder',
})

聚合

对行进行分组时，可以使用 aggregationFn 选项按列聚合分组行中的数据。这是一个字符串，是聚合函数的 ID。您可以使用 aggregationFns 选项定义聚合函数。

tsx

const column = columnHelper.accessor('key', {
  aggregationFn: 'sum',
})

const column = columnHelper.accessor('key', {
  aggregationFn: 'sum',
})

在上面的示例中，sum 聚合函数将用于聚合分组行中的数据。默认情况下，数字列将使用 sum 聚合函数，而非数字列将使用 count 聚合函数。您可以通过在列定义中指定 aggregationFn 选项来覆盖此行为。

有几个内置的聚合函数可供使用：

sum - 对分组行中的值求和。
count - 计算分组行中的行数。
min - 查找分组行中的最小值。
max - 查找分组行中的最大值。
extent - 查找分组行中值的范围（最小值和最大值）。
mean - 查找分组行中值的平均值。
median - 查找分组行中值的中位数。
unique - 返回分组行中唯一值的数组。
uniqueCount - 计算分组行中唯一值的数量。

自定义聚合

对行进行分组时，可以使用 aggregationFns 选项聚合分组行中的数据。这是一个记录，其中键是聚合函数的 ID，值是聚合函数本身。然后，您可以在列的 aggregationFn 选项中引用这些聚合函数。

tsx

const table = useReactTable({
  // 其他选项...
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // 返回聚合值
    },
  },
})

const table = useReactTable({
  // 其他选项...
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // 返回聚合值
    },
  },
})

在上面的示例中，myCustomAggregation 是一个自定义聚合函数，它接受列 ID、叶行和子行，并返回聚合值。然后，您可以在列的 aggregationFn 选项中使用此聚合函数：

tsx

const column = columnHelper.accessor('key', {
  aggregationFn: 'myCustomAggregation',
})

const column = columnHelper.accessor('key', {
  aggregationFn: 'myCustomAggregation',
})

手动分组

如果您正在进行服务器端分组和聚合，可以使用 manualGrouping 选项启用手动分组。当此选项设置为 true 时，表格将不会使用 getGroupedRowModel() 自动对行进行分组，而是希望您在将行传递给表格之前手动对行进行分组。

tsx

const table = useReactTable({
  // 其他选项...
  manualGrouping: true,
})

const table = useReactTable({
  // 其他选项...
  manualGrouping: true,
})

注意： 目前还没有很多已知的方法可以轻松地使用 TanStack Table 进行服务器端分组。您需要进行大量自定义单元格渲染才能使其正常工作。

分组更改处理程序

如果您想自己管理分组状态，可以使用 onGroupingChange 选项。此选项是一个在分组状态更改时调用的函数。您可以通过 tableOptions.state.grouping 选项将管理的状态传递回表格。

tsx

const [grouping, setGrouping] = useState<string[]>([])

const table = useReactTable({
  // 其他选项...
  state: {
    grouping: grouping,
  },
  onGroupingChange: setGrouping
})

const [grouping, setGrouping] = useState<string[]>([])

const table = useReactTable({
  // 其他选项...
  state: {
    grouping: grouping,
  },
  onGroupingChange: setGrouping
})