Column Filtering APIs

可筛选性 (Can-Filter)

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

该列已使用有效的 accessorKey / accessorFn 定义。
column.enableColumnFilter 未设置为 false。
options.enableColumnFilters 未设置为 false。
options.enableFilters 未设置为 false。

状态 (State)

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

export interface ColumnFiltersTableState {
  columnFilters: ColumnFiltersState
}

export type ColumnFiltersState = ColumnFilter[]

export interface ColumnFilter {
  id: string
  value: unknown
}

筛选函数 (Filter Functions)

以下筛选函数内置于表格核心：

includesString：不区分大小写的字符串包含。
includesStringSensitive：区分大小写的字符串包含。
equalsString：不区分大小写的字符串相等。
equalsStringSensitive：区分大小写的字符串相等。
arrIncludes：数组中的项目包含。
arrIncludesAll：数组中包含所有项目。
arrIncludesSome：数组中包含部分项目。
equals：对象/引用相等性 Object.is / ===。
weakEquals：弱对象/引用相等性 ==。
inNumberRange：数字范围包含。

每个筛选函数接收：

要筛选的行。
用于检索行值的 columnId。
筛选值。

如果行应包含在筛选后的行中，则应返回 true；如果应删除，则返回 false。

这是每个筛选函数的类型签名：

export type FilterFn<TData extends AnyData> = {
  (
    row: Row<TData>,
    columnId: string,
    filterValue: any,
    addMeta: (meta: any) => void
  ): boolean
  resolveFilterValue?: TransformFilterValueFn<TData>
  autoRemove?: ColumnFilterAutoRemoveTestFn<TData>
  addMeta?: (meta?: any) => void
}

export type TransformFilterValueFn<TData extends AnyData> = (
  value: any,
  column?: Column<TData>
) => unknown

export type ColumnFilterAutoRemoveTestFn<TData extends AnyData> = (
  value: any,
  column?: Column<TData>
) => boolean

export type CustomFilterFns<TData extends AnyData> = Record<
  string,
  FilterFn<TData>
>

filterFn.resolveFilterValue

此可选的 “挂载” 方法允许筛选函数在将筛选值传递给筛选函数之前对其进行转换/清理/格式化。

filterFn.autoRemove

此可选的 “挂载” 方法接收一个筛选值，并期望在筛选值应从筛选状态中移除时返回 true。例如，某些布尔型筛选器可能希望在筛选值设置为 false 时从表格状态中移除筛选值。

使用筛选函数 (Using Filter Functions)

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

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

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

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/react-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)

filterFn

filterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

与此列一起使用的筛选函数。

选项：

引用内置筛选函数的 字符串。
自定义筛选函数。

enableColumnFilter

enableColumnFilter?: boolean

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

列 API (Column API)

getCanFilter

getCanFilter: () => boolean

返回列是否可以进行列筛选。

getFilterIndex

getFilterIndex: () => number

返回表格 state.columnFilters 数组中列筛选器的索引（包括 -1）。

getIsFiltered

getIsFiltered: () => boolean

返回列当前是否已筛选。

getFilterValue

getFilterValue: () => unknown

返回列的当前筛选值。

setFilterValue

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

一个函数，用于设置列的当前筛选值。你可以传入一个值或一个更新函数，以便对现有值进行不可变安全操作。

getAutoFilterFn

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

根据列的第一个已知值返回列的自动计算筛选函数。

getFilterFn

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

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

行 API (Row API)

columnFilters

columnFilters: Record<string, boolean>

行的列筛选器映射。此对象根据列 ID 跟踪行是否通过/未通过特定筛选器。

columnFiltersMeta

columnFiltersMeta: Record<string, any>

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

表格选项 (Table Options)

filterFns

filterFns?: Record<string, FilterFn>

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

declare module '@tanstack/[adapter]-table' {
  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 用于筛选数据。这在你需要动态支持客户端和服务器端筛选的表格中可能很有用。

onColumnFiltersChange

onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>

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

enableColumnFilters

enableColumnFilters?: boolean

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

getFilteredRowModel

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

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

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

示例：

import { getFilteredRowModel } from '@tanstack/[adapter]-table'

  getFilteredRowModel: getFilteredRowModel(),
})

表格 API (Table API)

setColumnFilters

setColumnFilters: (updater: Updater<ColumnFiltersState>) => void

设置或更新 state.columnFilters 状态。

resetColumnFilters

resetColumnFilters: (defaultState?: boolean) => void

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

getPreFilteredRowModel

getPreFilteredRowModel: () => RowModel<TData>

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

getFilteredRowModel

getFilteredRowModel: () => RowModel<TData>

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

Cell APIs

Column Faceting APIs