排序 API | TanStack Table Docs

状态

排序状态使用以下结构存储在表格中：

tsx

export type SortDirection = 'asc' | 'desc'

export type ColumnSort = {
  id: string
  desc: boolean
}

export type SortingState = ColumnSort[]

export type SortingTableState = {
  sorting: SortingState
}

export type SortDirection = 'asc' | 'desc'

export type ColumnSort = {
  id: string
  desc: boolean
}

export type SortingState = ColumnSort[]

export type SortingTableState = {
  sorting: SortingState
}

排序函数

以下排序函数内置于表格核心中：

alphanumeric
- 按混合字母数字值排序，不区分大小写。速度较慢，但如果字符串包含需要自然排序的数字，则更准确。
alphanumericCaseSensitive
- 按混合字母数字值排序，区分大小写。速度较慢，但如果字符串包含需要自然排序的数字，则更准确。
text
- 按文本/字符串值排序，不区分大小写。速度较快，但如果字符串包含需要自然排序的数字，则不太准确。
textCaseSensitive
- 按文本/字符串值排序，区分大小写。速度较快，但如果字符串包含需要自然排序的数字，则不太准确。
datetime
- 按时间排序，如果值为 Date 对象，则使用此函数。
basic
- 使用基本/标准 a > b ? 1 : a < b ? -1 : 0 比较进行排序。这是最快的排序函数，但可能不是最准确的。

每个排序函数接收 2 行和一个列 ID，并期望使用列 ID 比较这两行以按升序返回 -1、0 或 1。这是一个速查表：

返回值	升序
-1	a < b
0	a === b
1	a > b

这是每个排序函数的类型签名：

tsx

export type SortingFn<TData extends AnyData> = {
  (rowA: Row<TData>, rowB: Row<TData>, columnId: string): number
}

export type SortingFn<TData extends AnyData> = {
  (rowA: Row<TData>, rowB: Row<TData>, columnId: string): number
}

使用排序函数

通过将以下内容传递给 columnDefinition.sortingFn，可以使用/引用/定义排序函数：

引用内置排序函数的 string
引用通过 tableOptions.sortingFns 选项提供的自定义排序函数的 string
直接提供给 columnDefinition.sortingFn 选项的函数

columnDef.sortingFn 可用的排序函数的最终列表使用以下类型：

tsx

export type SortingFnOption<TData extends AnyData> =
  | 'auto'
  | SortingFns
  | BuiltInSortingFns
  | SortingFn<TData>

export type SortingFnOption<TData extends AnyData> =
  | 'auto'
  | SortingFns
  | BuiltInSortingFns
  | SortingFn<TData>

列定义选项

sortingFn

tsx

sortingFn?: SortingFn | keyof SortingFns | keyof BuiltInSortingFns

sortingFn?: SortingFn | keyof SortingFns | keyof BuiltInSortingFns

用于此列的排序函数。

选项：

引用内置排序函数的 string
自定义排序函数

sortDescFirst

tsx

sortDescFirst?: boolean

sortDescFirst?: boolean

设置为 true，此列上的排序切换将以降序开始。

enableSorting

tsx

enableSorting?: boolean

enableSorting?: boolean

启用/禁用此列的排序。

enableMultiSort

tsx

enableMultiSort?: boolean

enableMultiSort?: boolean

启用/禁用此列的多重排序。

invertSorting

tsx

invertSorting?: boolean

invertSorting?: boolean

反转此列的排序顺序。这对于具有反向最佳/最差等级的值（其中较小的数字更好，例如排名（第一、第二、第三）或类似高尔夫的评分）非常有用。

sortUndefined

tsx

sortUndefined?: 'first' | 'last' | false | -1 | 1 // 默认为 1

sortUndefined?: 'first' | 'last' | false | -1 | 1 // 默认为 1

'first'
- 未定义的值将被推到列表的开头
'last'
- 未定义的值将被推到列表的末尾
false
- 未定义的值将被视为并列，需要按下一列筛选器或原始索引（以适用者为准）进行排序
-1
- 未定义的值将按较高优先级（升序）排序（如果升序，未定义将出现在列表的开头）
1
- 未定义的值将按较低优先级（降序）排序（如果升序，未定义将出现在列表的末尾）

注意：'first' 和 'last' 选项是 v8.16.0 中的新增选项

列 API

getAutoSortingFn

tsx

getAutoSortingFn: () => SortingFn<TData>

getAutoSortingFn: () => SortingFn<TData>

返回根据列值自动推断的排序函数。

getAutoSortDir

tsx

getAutoSortDir: () => SortDirection

getAutoSortDir: () => SortDirection

返回根据列值自动推断的排序方向。

getSortingFn

tsx

getSortingFn: () => SortingFn<TData>

getSortingFn: () => SortingFn<TData>

返回用于此列的已解析排序函数。

getNextSortingOrder

tsx

getNextSortingOrder: () => SortDirection | false

getNextSortingOrder: () => SortDirection | false

返回下一个排序顺序。

getCanSort

tsx

getCanSort: () => boolean

getCanSort: () => boolean

返回此列是否可以排序。

getCanMultiSort

tsx

getCanMultiSort: () => boolean

getCanMultiSort: () => boolean

返回此列是否可以多重排序。

getSortIndex

tsx

getSortIndex: () => number

getSortIndex: () => number

返回此列排序在排序状态中的索引位置。

getIsSorted

tsx

getIsSorted: () => false | SortDirection

getIsSorted: () => false | SortDirection

返回此列是否已排序。

getFirstSortDir

tsx

getFirstSortDir: () => SortDirection

getFirstSortDir: () => SortDirection

返回对此列进行排序时应使用的第一个方向。

clearSorting

tsx

clearSorting: () => void

clearSorting: () => void

从此表格的排序状态中删除此列。

toggleSorting

tsx

toggleSorting: (desc?: boolean, isMulti?: boolean) => void

toggleSorting: (desc?: boolean, isMulti?: boolean) => void

切换此列的排序状态。如果提供了 desc，它将强制排序方向为该值。如果提供了 isMulti，它将对列进行附加的多重排序（如果已排序，则切换它）。

getToggleSortingHandler

tsx

getToggleSortingHandler: () => undefined | ((event: unknown) => void)

getToggleSortingHandler: () => undefined | ((event: unknown) => void)

返回一个可用于切换此列排序状态的函数。这对于将单击处理程序附加到列标题非常有用。

表格选项

sortingFns

tsx

sortingFns?: Record<string, SortingFn>

sortingFns?: Record<string, SortingFn>

此选项允许您定义自定义排序函数，这些函数可以在列的 sortingFn 选项中按其键引用。示例：

tsx

declare module '@tanstack/table-core' {
  interface SortingFns {
    myCustomSorting: SortingFn<unknown>
  }
}

const column = columnHelper.data('key', {
  sortingFn: 'myCustomSorting',
})

const table = useReactTable({
  columns: [column],
  sortingFns: {
    myCustomSorting: (rowA: any, rowB: any, columnId: any): number =>
      rowA.getValue(columnId).value < rowB.getValue(columnId).value ? 1 : -1,
  },
})

declare module '@tanstack/table-core' {
  interface SortingFns {
    myCustomSorting: SortingFn<unknown>
  }
}

const column = columnHelper.data('key', {
  sortingFn: 'myCustomSorting',
})

const table = useReactTable({
  columns: [column],
  sortingFns: {
    myCustomSorting: (rowA: any, rowB: any, columnId: any): number =>
      rowA.getValue(columnId).value < rowB.getValue(columnId).value ? 1 : -1,
  },
})

manualSorting

tsx

manualSorting?: boolean

manualSorting?: boolean

启用表格的手动排序。如果为 true，则您需要在将数据传递给表格之前对其进行排序。如果您正在进行服务器端排序，这很有用。

onSortingChange

tsx

onSortingChange?: OnChangeFn<SortingState>

onSortingChange?: OnChangeFn<SortingState>

如果提供，当 state.sorting 更改时，将使用 updaterFn 调用此函数。这会覆盖默认的内部状态管理，因此您需要在表格外部完全或部分地持久化状态更改。

enableSorting

tsx

enableSorting?: boolean

enableSorting?: boolean

启用/禁用表格的排序。

enableSortingRemoval

tsx

enableSortingRemoval?: boolean

enableSortingRemoval?: boolean

启用/禁用删除表格排序的功能。

如果为 true，则更改排序顺序将像这样循环：'none' -> 'desc' -> 'asc' -> 'none' -> ...
如果为 false，则更改排序顺序将像这样循环：'none' -> 'desc' -> 'asc' -> 'desc' -> 'asc' -> ...

enableMultiRemove

tsx

enableMultiRemove?: boolean

enableMultiRemove?: boolean

启用/禁用删除多重排序的功能。

enableMultiSort

tsx

enableMultiSort?: boolean

enableMultiSort?: boolean

启用/禁用表格的多重排序。

sortDescFirst

tsx

sortDescFirst?: boolean

sortDescFirst?: boolean

如果为 true，则所有排序都将默认为降序作为其第一个切换状态。

getSortedRowModel

tsx

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

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

此函数用于检索排序后的行模型。如果使用服务器端排序，则不需要此函数。要使用客户端排序，请将适配器中导出的 getSortedRowModel() 传递给表格或实现您自己的函数。

maxMultiSortColCount

tsx

maxMultiSortColCount?: number

maxMultiSortColCount?: number

设置可以多重排序的最大列数。

isMultiSortEvent

tsx

isMultiSortEvent?: (e: unknown) => boolean

isMultiSortEvent?: (e: unknown) => boolean

传递一个自定义函数，该函数将用于确定是否应触发多重排序事件。它会从排序切换处理程序接收事件，如果事件应触发多重排序，则应返回 true。

表格 API

setSorting

tsx

setSorting: (updater: Updater<SortingState>) => void

setSorting: (updater: Updater<SortingState>) => void

设置或更新 state.sorting 状态。

resetSorting

tsx

resetSorting: (defaultState?: boolean) => void

resetSorting: (defaultState?: boolean) => void

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

getPreSortedRowModel

tsx

getPreSortedRowModel: () => RowModel<TData>

getPreSortedRowModel: () => RowModel<TData>

返回应用任何排序之前的表格行模型。

getSortedRowModel

tsx

getSortedRowModel: () => RowModel<TData>

getSortedRowModel: () => RowModel<TData>

返回应用排序之后的表格行模型。