排序 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
}

排序函数

以下排序函数是内置在表格核心中的

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

每个排序函数都会接收两个行和一个列 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

此列要使用的排序函数。

选项

一个字符串，引用一个内置排序函数)
一个自定义排序函数

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，则更改排序顺序将循环，例如：“无”->“降序”->“升序”->“无”->...
如果 false，则更改排序顺序将循环，例如：“无”->“降序”->“升序”->“降序”->“升序”->...

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