列筛选 API | TanStack Table Docs

可筛选

列是否能够进行列筛选取决于以下因素：

列定义时带有有效的 accessorKey/accessorFn。
column.enableColumnFilter 未设置为 false
options.enableColumnFilters 未设置为 false
options.enableFilters 未设置为 false

状态

筛选器状态使用以下结构存储在表格中：

tsx

export interface ColumnFiltersTableState {
  columnFilters: ColumnFiltersState
}

export type ColumnFiltersState = ColumnFilter[]

export interface ColumnFilter {
  id: string
  value: unknown
}

export interface ColumnFiltersTableState {
  columnFilters: ColumnFiltersState
}

export type ColumnFiltersState = ColumnFilter[]

export interface ColumnFilter {
  id: string
  value: unknown
}

筛选函数

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

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

每个筛选函数都会收到：

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

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

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

tsx

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>
>

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 上的此可选“悬挂”方法允许筛选函数在将筛选值传递给筛选函数之前对其进行转换/清理/格式化。

filterFn.autoRemove

任何给定 filterFn 上的此可选“悬挂”方法都会传递一个筛选值，并期望在应从筛选器状态中删除筛选值时返回 true。例如，某些布尔型筛选器可能希望在筛选值设置为 false 时从表格状态中删除筛选值。

使用筛选函数

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

引用内置筛选函数的 string
直接提供给 columnDefinition.filterFn 选项的函数

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

tsx

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

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

筛选元数据

筛选数据通常可以公开有关数据的其他信息，这些信息可用于帮助将来对相同数据进行其他操作。这个概念的一个很好的例子是一个排名系统，例如 match-sorter 的排名系统，它可以同时对数据进行排名、筛选和排序。虽然像 match-sorter 这样的实用程序对于单维筛选+排序任务非常有意义，但构建表格的解耦筛选/排序体系结构使得它们使用起来非常困难且缓慢。

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

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

tsx

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
}

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
}

列定义选项

filterFn

tsx

filterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

filterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

用于此列的筛选函数。

选项：

引用内置筛选函数的 string
自定义筛选函数

enableColumnFilter

tsx

enableColumnFilter?: boolean

enableColumnFilter?: boolean

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

列 API

getCanFilter

tsx

getCanFilter: () => boolean

getCanFilter: () => boolean

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

getFilterIndex

tsx

getFilterIndex: () => number

getFilterIndex: () => number

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

getIsFiltered

tsx

getIsFiltered: () => boolean

getIsFiltered: () => boolean

返回列当前是否已筛选。

getFilterValue

tsx

getFilterValue: () => unknown

getFilterValue: () => unknown

返回列的当前筛选值。

setFilterValue

tsx

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

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

一个设置列当前筛选值的函数。您可以向其传递一个值或一个更新程序函数，以对现有值执行不可变性安全操作。

getAutoFilterFn

tsx

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

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

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

getFilterFn

tsx

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

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

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

行 API

columnFilters

tsx

columnFilters: Record<string, boolean>

columnFilters: Record<string, boolean>

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

columnFiltersMeta

tsx

columnFiltersMeta: Record<string, any>

columnFiltersMeta: Record<string, any>

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

表格选项

filterFns

tsx

filterFns?: Record<string, FilterFn>

filterFns?: Record<string, FilterFn>

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

tsx

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) => {
      // 返回筛选后的行
    },
  },
})

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

tsx

filterFromLeafRows?: boolean

filterFromLeafRows?: boolean

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

maxLeafRowFilterDepth

tsx

maxLeafRowFilterDepth?: number

maxLeafRowFilterDepth?: number

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

这对于您希望无论应用的筛选器如何，行的整个子层次结构都可见的情况非常有用。

enableFilters

tsx

enableFilters?: boolean

enableFilters?: boolean

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

manualFiltering

tsx

manualFiltering?: boolean

manualFiltering?: boolean

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

onColumnFiltersChange

tsx

onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>

onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>

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

enableColumnFilters

tsx

enableColumnFilters?: boolean

enableColumnFilters?: boolean

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

getFilteredRowModel

tsx

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

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

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

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

示例：

tsx

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


  getFilteredRowModel: getFilteredRowModel(),
})

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


  getFilteredRowModel: getFilteredRowModel(),
})

表格 API

setColumnFilters

tsx

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

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

设置或更新 state.columnFilters 状态。

resetColumnFilters

tsx

resetColumnFilters: (defaultState?: boolean) => void

resetColumnFilters: (defaultState?: boolean) => void

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

getPreFilteredRowModel

tsx

getPreFilteredRowModel: () => RowModel<TData>

getPreFilteredRowModel: () => RowModel<TData>

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

getFilteredRowModel

tsx

getFilteredRowModel: () => RowModel<TData>

getFilteredRowModel: () => RowModel<TData>

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