分组指南

示例

想直接看实现？可以参考以下示例

分组

API

分组 API

有 3 种表格功能可以重新排序列，它们的顺序如下：

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

TanStack 表中的分组功能适用于列，允许您根据特定列对表行进行分类和组织。当您拥有大量数据并希望根据某些标准将它们分组时，此功能非常有用。

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

tsx

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

const table = useReactTable({
  // other options...
  getGroupedRowModel: getGroupedRowModel(),
})

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

const table = useReactTable({
  // other options...
  getGroupedRowModel: getGroupedRowModel(),
})

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

tsx

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

const table = useReactTable({
  // other options...
  getGroupedRowModel: getGroupedRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
})

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

const table = useReactTable({
  // other options...
  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({
  // other options...
  groupedColumnMode: 'reorder',
})

const table = useReactTable({
  // other options...
  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({
  // other options...
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // return the aggregated value
    },
  },
})

const table = useReactTable({
  // other options...
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // return the aggregated value
    },
  },
})

在上面的示例中，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({
  // other options...
  manualGrouping: true,
})

const table = useReactTable({
  // other options...
  manualGrouping: true,
})

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

分组更改处理程序

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

tsx

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

const table = useReactTable({
  // other options...
  state: {
    grouping: grouping,
  },
  onGroupingChange: setGrouping
})

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

const table = useReactTable({
  // other options...
  state: {
    grouping: grouping,
  },
  onGroupingChange: setGrouping
})

分组指南

示例

API

分组指南

分组状态

聚合

自定义聚合

手动分组

分组更改处理程序

订阅 Bytes

订阅 Bytes