排序 API

状态

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

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
}

排序函数

表格核心内置了以下排序函数

字母数字
- 按混合字母数字值排序，不区分大小写。速度较慢，但如果您的字符串包含需要自然排序的数字，则更准确。
字母数字区分大小写
- 按混合字母数字值排序，区分大小写。速度较慢，但如果您的字符串包含需要自然排序的数字，则更准确。
文本
- 按文本/字符串值排序，不区分大小写。速度更快，但如果您的字符串包含需要自然排序的数字，则不太准确。
文本区分大小写
- 按文本/字符串值排序，区分大小写。速度更快，但如果您的字符串包含需要自然排序的数字，则不太准确。
日期时间
- 按时间排序，如果您的值是 Date 对象，请使用此项。
基本
- 使用基本/标准的 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 来使用/引用/定义

引用内置排序函数的字符串
引用通过 tableOptions.sortingFns 选项提供的自定义排序函数的字符串
直接提供给 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

反转此列的排序顺序。这对于具有反向最佳/最差比例的值很有用，其中数字越小越好，例如排名（第 1 名、第 2 名、第 3 名）或类似高尔夫的评分

sortUndefined

tsx

sortUndefined?: 'first' | 'last' | false | -1 | 1 // defaults to 1

sortUndefined?: 'first' | 'last' | false | -1 | 1 // defaults to 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

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

getPreSortedRowModel

tsx

getPreSortedRowModel: () => RowModel<TData>

getPreSortedRowModel: () => RowModel<TData>

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

getSortedRowModel

tsx

getSortedRowModel: () => RowModel<TData>

getSortedRowModel: () => RowModel<TData>

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

状态

排序函数

使用排序函数

列定义选项

sortingFn

sortDescFirst

enableSorting

enableMultiSort

invertSorting

sortUndefined

列 API

getAutoSortingFn

getAutoSortDir

getSortingFn

getNextSortingOrder

getCanSort

getCanMultiSort

getSortIndex

getIsSorted

getFirstSortDir

clearSorting

toggleSorting

getToggleSortingHandler

表格选项

sortingFns

manualSorting

onSortingChange

enableSorting

enableSortingRemoval

enableMultiRemove

enableMultiSort

sortDescFirst

getSortedRowModel

maxMultiSortColCount

isMultiSortEvent

表格 API

setSorting

resetSorting

getPreSortedRowModel

getSortedRowModel

订阅 Bytes

订阅 Bytes