分组 API

状态

分组状态在表格中以以下结构存储

tsx

export type GroupingState = string[]

export type GroupingTableState = {
  grouping: GroupingState
}

export type GroupingState = string[]

export type GroupingTableState = {
  grouping: GroupingState
}

聚合函数

表格核心内置了以下聚合函数

sum
- 计算一组行的值的总和
min
- 查找一组行的最小值
max
- 查找一组行的最大值
extent
- 查找一组行的最小值和最大值
mean
- 计算一组行的平均值
median
- 查找一组行的中位数
unique
- 查找一组行的唯一值
uniqueCount
- 查找一组行中唯一值的数量
count
- 计算一组中的行数

每个分组函数都接收

一个用于检索分组行的叶子节点值的函数
一个用于检索分组行的直接子节点值的函数

并应返回一个值（通常是原始值）来构建聚合行模型。

这是每个聚合函数的类型签名

tsx

export type AggregationFn<TData extends AnyData> = (
  getLeafRows: () => Row<TData>[],
  getChildRows: () => Row<TData>[]
) => any

export type AggregationFn<TData extends AnyData> = (
  getLeafRows: () => Row<TData>[],
  getChildRows: () => Row<TData>[]
) => any

使用聚合函数

可以通过将以下内容传递给 columnDefinition.aggregationFn 来使用/引用/定义聚合函数

一个字符串，引用一个内置的聚合函数
一个字符串，引用通过 tableOptions.aggregationFns 选项提供的自定义聚合函数
直接提供给 columnDefinition.aggregationFn 选项的一个函数

可用于 columnDef.aggregationFn 的聚合函数的最终列表使用以下类型

tsx

export type AggregationFnOption<TData extends AnyData> =
  | 'auto'
  | keyof AggregationFns
  | BuiltInAggregationFn
  | AggregationFn<TData>

export type AggregationFnOption<TData extends AnyData> =
  | 'auto'
  | keyof AggregationFns
  | BuiltInAggregationFn
  | AggregationFn<TData>

列定义选项

aggregationFn

tsx

aggregationFn?: AggregationFn | keyof AggregationFns | keyof BuiltInAggregationFns

aggregationFn?: AggregationFn | keyof AggregationFns | keyof BuiltInAggregationFns

此列使用的聚合函数。

选项

一个字符串，引用一个内置的聚合函数)
一个自定义聚合函数

aggregatedCell

tsx

aggregatedCell?: Renderable<
  {
    table: Table<TData>
    row: Row<TData>
    column: Column<TData>
    cell: Cell<TData>
    getValue: () => any
    renderValue: () => any
  }
>

aggregatedCell?: Renderable<
  {
    table: Table<TData>
    row: Row<TData>
    column: Column<TData>
    cell: Cell<TData>
    getValue: () => any
    renderValue: () => any
  }
>

如果单元格是聚合单元格，则为该列显示的每个单元格。如果提供了函数，则会传入一个包含单元格上下文的 props 对象，并且应返回适配器属性的类型（确切类型取决于所使用的适配器）。

enableGrouping

tsx

enableGrouping?: boolean

enableGrouping?: boolean

启用/禁用此列的分组。

getGroupingValue

tsx

getGroupingValue?: (row: TData) => any

getGroupingValue?: (row: TData) => any

指定用于对该列的行进行分组的值。如果未指定此选项，则将改用从 accessorKey / accessorFn 派生的值。

列 API

aggregationFn

tsx

aggregationFn?: AggregationFnOption<TData>

aggregationFn?: AggregationFnOption<TData>

该列解析后的聚合函数。

getCanGroup

tsx

getCanGroup: () => boolean

getCanGroup: () => boolean

返回该列是否可以被分组。

getIsGrouped

tsx

getIsGrouped: () => boolean

getIsGrouped: () => boolean

返回该列当前是否被分组。

getGroupedIndex

tsx

getGroupedIndex: () => number

getGroupedIndex: () => number

返回该列在分组状态中的索引。

toggleGrouping

tsx

toggleGrouping: () => void

toggleGrouping: () => void

切换该列的分组状态。

getToggleGroupingHandler

tsx

getToggleGroupingHandler: () => () => void

getToggleGroupingHandler: () => () => void

返回一个用于切换该列分组状态的函数。这对于将其传递给按钮的 onClick prop 非常有用。

getAutoAggregationFn

tsx

getAutoAggregationFn: () => AggregationFn<TData> | undefined

getAutoAggregationFn: () => AggregationFn<TData> | undefined

返回该列自动推断的聚合函数。

getAggregationFn

tsx

getAggregationFn: () => AggregationFn<TData> | undefined

getAggregationFn: () => AggregationFn<TData> | undefined

返回该列的聚合函数。

行 API

groupingColumnId

tsx

groupingColumnId?: string

groupingColumnId?: string

如果此行被分组，则这是该行分组所依据的列的 ID。

groupingValue

tsx

groupingValue?: any

groupingValue?: any

如果此行被分组，则这是该组中所有行的 groupingColumnId 的唯一/共享值。

getIsGrouped

tsx

getIsGrouped: () => boolean

getIsGrouped: () => boolean

返回该行当前是否被分组。

getGroupingValue

tsx

getGroupingValue: (columnId: string) => unknown

getGroupingValue: (columnId: string) => unknown

返回任何行和列（包括叶子行）的分组值。

表格选项

aggregationFns

tsx

aggregationFns?: Record<string, AggregationFn>

aggregationFns?: Record<string, AggregationFn>

此选项允许您定义自定义聚合函数，这些函数可以通过其键在列的 aggregationFn 选项中进行引用。例如

tsx

declare module '@tanstack/table-core' {
  interface AggregationFns {
    myCustomAggregation: AggregationFn<unknown>
  }
}

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

const table = useReactTable({
  columns: [column],
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // return the aggregated value
    },
  },
})

declare module '@tanstack/table-core' {
  interface AggregationFns {
    myCustomAggregation: AggregationFn<unknown>
  }
}

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

const table = useReactTable({
  columns: [column],
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // return the aggregated value
    },
  },
})

manualGrouping

tsx

manualGrouping?: boolean

manualGrouping?: boolean

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

onGroupingChange

tsx

onGroupingChange?: OnChangeFn<GroupingState>

onGroupingChange?: OnChangeFn<GroupingState>

如果提供了此函数，则在分组状态更改时会调用它，您需要自己管理状态。您可以通过 tableOptions.state.grouping 选项将管理后的状态传递回表格。

enableGrouping

tsx

enableGrouping?: boolean

enableGrouping?: boolean

启用/禁用所有列的分组。

getGroupedRowModel

tsx

getGroupedRowModel?: (table: Table<TData>) => () => RowModel<TData>

getGroupedRowModel?: (table: Table<TData>) => () => RowModel<TData>

返回分组后的行模型，但未进一步处理。

groupedColumnMode

tsx

groupedColumnMode?: false | 'reorder' | 'remove' // default: `reorder`

groupedColumnMode?: false | 'reorder' | 'remove' // default: `reorder`

默认情况下，分组列会自动重新排序到列列表的开头。如果您宁愿删除它们或保持原样，请在此处设置适当的模式。

表格 API

setGrouping

tsx

setGrouping: (updater: Updater<GroupingState>) => void

setGrouping: (updater: Updater<GroupingState>) => void

设置或更新 state.grouping 状态。

resetGrouping

tsx

resetGrouping: (defaultState?: boolean) => void

resetGrouping: (defaultState?: boolean) => void

将**分组**状态重置为 initialState.grouping，或者可以传递 true 来强制默认的空白状态重置为 []。

getPreGroupedRowModel

tsx

getPreGroupedRowModel: () => RowModel<TData>

getPreGroupedRowModel: () => RowModel<TData>

返回应用任何分组之前的表格行模型。

getGroupedRowModel

tsx

getGroupedRowModel: () => RowModel<TData>

getGroupedRowModel: () => RowModel<TData>

返回应用分组之后的表格行模型。

单元格 API

getIsAggregated

tsx

getIsAggregated: () => boolean

getIsAggregated: () => boolean

返回单元格当前是否被聚合。

getIsGrouped

tsx

getIsGrouped: () => boolean

getIsGrouped: () => boolean

返回单元格当前是否被分组。

getIsPlaceholder

tsx

getIsPlaceholder: () => boolean

getIsPlaceholder: () => boolean

返回单元格当前是否为占位符。

状态

聚合函数

使用聚合函数

列定义选项

aggregationFn

aggregatedCell

enableGrouping

getGroupingValue

列 API

aggregationFn

getCanGroup

getIsGrouped

getGroupedIndex

toggleGrouping

getToggleGroupingHandler

getAutoAggregationFn

getAggregationFn

行 API

groupingColumnId

groupingValue

getIsGrouped

getGroupingValue

表格选项

aggregationFns

manualGrouping

onGroupingChange

enableGrouping

getGroupedRowModel

groupedColumnMode

表格 API

setGrouping

resetGrouping

getPreGroupedRowModel

getGroupedRowModel

单元格 API

getIsAggregated

getIsGrouped

getIsPlaceholder

订阅 Bytes

订阅 Bytes