Sorting APIs

状态 (State)

排序状态以以下形式存储在表格中：

export type SortDirection = 'asc' | 'desc'

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

export type SortingState = ColumnSort[]

export type SortingTableState = {
  sorting: SortingState
}

排序函数 (Sorting Functions)

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

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

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

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

使用排序函数 (Using Sorting Functions)

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

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

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

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

列定义选项 (Column Def Options)

sortingFn

sortingFn?: SortingFn | keyof SortingFns | keyof BuiltInSortingFns

与此列一起使用的排序函数。

选项：

引用内置排序函数的字符串。
自定义排序函数。

sortDescFirst

sortDescFirst?: boolean

设置为 true，使此列上的排序切换从降序方向开始。

enableSorting

enableSorting?: boolean

启用/禁用此列的排序功能。

enableMultiSort

enableMultiSort?: boolean

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

invertSorting

invertSorting?: boolean

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

sortUndefined

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

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

注意: 'first' 和 'last' 选项是 v8.16.0 中的新增功能。

列 API (Column API)

getAutoSortingFn

getAutoSortingFn: () => SortingFn<TData>

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

getAutoSortDir

getAutoSortDir: () => SortDirection

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

getSortingFn

getSortingFn: () => SortingFn<TData>

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

getNextSortingOrder

getNextSortingOrder: () => SortDirection | false

返回下一个排序顺序。

getCanSort

getCanSort: () => boolean

返回此列是否可以排序。

getCanMultiSort

getCanMultiSort: () => boolean

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

getSortIndex

getSortIndex: () => number

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

getIsSorted

getIsSorted: () => false | SortDirection

返回此列是否已排序。

getFirstSortDir

getFirstSortDir: () => SortDirection

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

clearSorting

clearSorting: () => void

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

toggleSorting

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

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

getToggleSortingHandler

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

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

表格选项 (Table Options)

sortingFns

sortingFns?: Record<string, SortingFn>

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

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

manualSorting?: boolean

启用表格的手动排序。如果此项为 true，则你需要在使用数据之前对其进行排序。这在你进行服务器端排序时很有用。

onSortingChange

onSortingChange?: OnChangeFn<SortingState>

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

enableSorting

enableSorting?: boolean

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

enableSortingRemoval

enableSortingRemoval?: boolean

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

如果为 true，则更改排序顺序将循环为：“无” -> “降序” -> “升序” -> “无” -> ...
如果为 false，则更改排序顺序将循环为：“无” -> “降序” -> “升序” -> “降序” -> “升序” -> ...

enableMultiRemove

enableMultiRemove?: boolean

启用/禁用移除多重排序的能力。

enableMultiSort

enableMultiSort?: boolean

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

sortDescFirst

sortDescFirst?: boolean

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

getSortedRowModel

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

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

maxMultiSortColCount

maxMultiSortColCount?: number

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

isMultiSortEvent

isMultiSortEvent?: (e: unknown) => boolean

传入一个自定义函数，该函数将用于确定是否应触发多重排序事件。它将传递来自排序切换处理程序的事件，并应在事件应触发多重排序时返回 true。

表格 API (Table API)

setSorting

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

设置或更新 state.sorting 状态。

resetSorting

resetSorting: (defaultState?: boolean) => void

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

getPreSortedRowModel

getPreSortedRowModel: () => RowModel<TData>

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

getSortedRowModel

getSortedRowModel: () => RowModel<TData>

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

Global Filtering APIs

Grouping APIs