Lzh on GitHub

状态 (State)

分组状态以以下形式存储在表格中：

export type GroupingState = string[]

export type GroupingTableState = {
  grouping: GroupingState
}

聚合函数 (Aggregation Functions)

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

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

每个分组函数接收：

  • 一个函数，用于检索组中叶子行的值。
  • 一个函数，用于检索组中直接子行的值。

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

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

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

使用聚合函数 (Using Aggregation Functions)

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

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

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

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

列定义选项 (Column Def Options)

aggregationFn

aggregationFn?: AggregationFn | keyof AggregationFns | keyof BuiltInAggregationFns

与此列一起使用的聚合函数。

选项：

  • 引用 内置聚合函数 的 字符串。
  • 自定义聚合函数。

aggregatedCell

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

如果单元格是聚合单元格，则用于显示列中每行的单元格。如果传递一个函数，它将传入一个包含单元格上下文的 props 对象，并应返回适用于你适配器的属性类型（具体类型取决于所使用的适配器）。

enableGrouping

enableGrouping?: boolean

启用/禁用此列的分组功能。

getGroupingValue

getGroupingValue?: (row: TData) => any

指定用于在此列上分组行的值。如果未指定此选项，将使用从 accessorKey / accessorFn 派生的值。

列 API (Column API)

aggregationFn

aggregationFn?: AggregationFnOption<TData>

列的已解析聚合函数。

getCanGroup

getCanGroup: () => boolean

返回列是否可以分组。

getIsGrouped

getIsGrouped: () => boolean

返回列当前是否已分组。

getGroupedIndex

getGroupedIndex: () => number

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

toggleGrouping

toggleGrouping: () => void

切换列的分组状态。

getToggleGroupingHandler

getToggleGroupingHandler: () => () => void

返回一个切换列分组状态的函数。这对于传递给按钮的 onClick 属性很有用。

getAutoAggregationFn

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

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

getAggregationFn

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

返回列的聚合函数。

行 API (Row API)

groupingColumnId

groupingColumnId?: string

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

groupingValue

groupingValue?: any

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

getIsGrouped

getIsGrouped: () => boolean

返回行当前是否已分组。

getGroupingValue

getGroupingValue: (columnId: string) => unknown

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

表格选项 (Table Options)

aggregationFns

aggregationFns?: Record<string, AggregationFn>

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

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) => {
      // 返回聚合值
    },
  },
})

manualGrouping

manualGrouping?: boolean

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

onGroupingChange

onGroupingChange?: OnChangeFn<GroupingState>

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

enableGrouping

enableGrouping?: boolean

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

getGroupedRowModel

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

在分组发生后返回行模型，但不再进一步。

groupedColumnMode

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

分组列默认会自动重新排序到列列表的开头。如果你更喜欢移除它们或保持原样，请在此处设置相应的模式。

表格 API (Table API)

setGrouping

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

设置或更新 state.grouping 状态。

resetGrouping

resetGrouping: (defaultState?: boolean) => void

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

getPreGroupedRowModel

getPreGroupedRowModel: () => RowModel<TData>

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

getGroupedRowModel

getGroupedRowModel: () => RowModel<TData>

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

单元格 API (Cell API)

getIsAggregated

getIsAggregated: () => boolean

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

getIsGrouped

getIsGrouped: () => boolean

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

getIsPlaceholder

getIsPlaceholder: () => boolean

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