Global Filtering APIs

全局筛选能力 (Can-Filter Globally)

一列是否可以进行全局筛选，由以下条件决定：

该列已使用有效的 accessorKey / accessorFn 定义。
如果提供了 options.getColumnCanGlobalFilter，它将为给定的列返回 true。如果未提供，则如果第一行中的值是 string 或 number 类型，则假定该列可以进行全局筛选。
column.enableColumnFilter 未设置为 false。
options.enableColumnFilters 未设置为 false。
options.enableFilters 未设置为 false。

状态 (State)

筛选状态以以下形式存储在表格中：

export interface GlobalFilterTableState {
  globalFilter: any
}

筛选函数 (Filter Functions)

你可以使用与列筛选器相同的筛选函数进行全局筛选。请参阅 列筛选 部分以了解更多有关筛选函数的信息。

使用筛选函数 (Using Filter Functions)

可以通过将以下内容传递给 options.globalFilterFn 来使用/引用/定义筛选函数：

引用内置筛选函数的字符串。
直接提供给 options.globalFilterFn 选项的函数。

可用于 tableOptions.globalFilterFn 选项的筛选函数的最终列表使用以下类型：

export type FilterFnOption<TData extends AnyData> =
  | 'auto'
  | BuiltInFilterFn
  | FilterFn<TData>

筛选元数据 (Filter Meta)

筛选数据通常可以揭示有关数据的额外信息，这些信息可用于辅助将来对相同数据的操作。此概念的一个很好的例子是像 match-sorter 这样的排名系统，它同时对数据进行排名、筛选和排序。虽然像 match-sorter 这样的实用程序对于一维筛选+排序任务很有意义，但构建表格的解耦筛选/排序架构使得它们非常难以使用且速度慢。

为了使排名/筛选/排序系统与表格配合使用，filterFns 可以选择性地用筛选元数据值标记结果，该值可用于以后根据需要对数据进行排序/分组等。这是通过调用提供给自定义 filterFn 的 addMeta 函数来完成的。

下面是使用我们自己的 match-sorter-utils 包（match-sorter 的实用程序分支）来对数据进行排名、筛选和排序的示例：

import { sortingFns } from '@tanstack/[adapter]-table'
import { rankItem, compareItems } from '@tanstack/match-sorter-utils'

const fuzzyFilter = (row, columnId, value, addMeta) => {
  // 对项进行排名
  const itemRank = rankItem(row.getValue(columnId), value)
  // 存储排名信息
  addMeta(itemRank)
  // 返回项是否应包含在筛选后的行中/排除
  return itemRank.passed
}

const fuzzySort = (rowA, rowB, columnId) => {
  let dir = 0
  // 仅在列具有排名信息时按排名排序
  if (rowA.columnFiltersMeta[columnId]) {
    dir = compareItems(
      rowA.columnFiltersMeta[columnId]!,
      rowB.columnFiltersMeta[columnId]!
    )
  }
  // 在项排名相等时提供字母数字回退
  return dir === 0 ? sortingFns.alphanumeric(rowA, rowB, columnId) : dir
}

列定义选项 (Column Def Options)

enableGlobalFilter

enableGlobalFilter?: boolean

启用/禁用此列的全局筛选器。

列 API (Column API)

getCanGlobalFilter

getCanGlobalFilter: () => boolean

返回列是否可以进行全局筛选。设置为 false 可禁用全局筛选期间对列的扫描。

行 API (Row API)

columnFiltersMeta

columnFiltersMeta: Record<string, any>

行的列筛选器元数据映射。此对象跟踪筛选过程中可选提供的行的任何筛选元数据。

表格选项 (Table Options)

filterFns

filterFns?: Record<string, FilterFn>

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

declare module '@tanstack/table-core' {
  interface FilterFns {
    myCustomFilter: FilterFn<unknown>
  }
}

const column = columnHelper.data('key', {
  filterFn: 'myCustomFilter',
})

const table = useReactTable({
  columns: [column],
  filterFns: {
    myCustomFilter: (rows, columnIds, filterValue) => {
      // 返回筛选后的行
    },
  },
})

filterFromLeafRows

filterFromLeafRows?: boolean

默认情况下，筛选是从父行向下进行的（因此如果父行被筛选掉，其所有子行也将被筛选掉）。将此选项设置为 true 将导致筛选从叶行向上进行（这意味着只要其子行或孙子行之一也被包含，父行就将包含在内）。

maxLeafRowFilterDepth

maxLeafRowFilterDepth?: number

默认情况下，对所有行（最大深度为 100）进行筛选，无论它们是根级父行还是父行的子叶行。将此选项设置为 0 将导致筛选仅应用于根级父行，所有子行保持未筛选。类似地，将此选项设置为 1 将导致筛选仅应用于深度为 1 的子叶行，依此类推。

这对于你希望行的整个子层次结构无论应用何种筛选器都可见的情况很有用。

enableFilters

enableFilters?: boolean

启用/禁用表格的所有筛选器。

manualFiltering

manualFiltering?: boolean

禁用 getFilteredRowModel 用于筛选数据。这在你需要动态支持客户端和服务器端筛选的表格中可能很有用。

getFilteredRowModel

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

如果提供，此函数 每个表格调用一次，并且应返回一个 新函数，该函数将在筛选时计算并返回表格的行模型。

对于服务器端筛选，此函数不必要，可以忽略，因为服务器应该已经返回筛选后的行模型。
对于客户端筛选，此函数是必需的。任何表格适配器的 { getFilteredRowModel } 导出都提供了一个默认实现。

示例：

import { getFilteredRowModel } from '@tanstack/[adapter]-table'
  getFilteredRowModel: getFilteredRowModel(),
})

globalFilterFn

globalFilterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

用于全局筛选的筛选函数。

选项：

引用内置筛选函数的字符串。
引用通过 tableOptions.filterFns 选项提供的自定义筛选函数的字符串。
自定义筛选函数。

onGlobalFilterChange

onGlobalFilterChange?: OnChangeFn<GlobalFilterState>

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

enableGlobalFilter

enableGlobalFilter?: boolean

启用/禁用表格的全局筛选器。

getColumnCanGlobalFilter

getColumnCanGlobalFilter?: (column: Column<TData>) => boolean

如果提供，此函数将使用列调用，并应返回 true 或 false 以指示此列是否应用于全局筛选。这在列可能包含非 string 或 number 类型（例如 undefined）数据时很有用。

表格 API (Table API)

getPreFilteredRowModel

getPreFilteredRowModel: () => RowModel<TData>

返回在应用任何列筛选之前表格的行模型。

getFilteredRowModel

getFilteredRowModel: () => RowModel<TData>

返回在应用列筛选之后表格的行模型。

setGlobalFilter

setGlobalFilter: (updater: Updater<any>) => void

设置或更新 state.globalFilter 状态。

resetGlobalFilter

resetGlobalFilter: (defaultState?: boolean) => void

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

getGlobalAutoFilterFn

getGlobalAutoFilterFn: (columnId: string) => FilterFn<TData> | undefined

目前，此函数返回内置的 includesString 筛选函数。在未来版本中，它可能会根据所提供数据的性质返回更动态的筛选函数。

getGlobalFilterFn

getGlobalFilterFn: (columnId: string) => FilterFn<TData> | undefined

返回表格的全局筛选函数（用户定义或自动，取决于配置）。

Global Faceting APIs

Sorting APIs