全局筛选 API | TanStack Table Docs

可筛选

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

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

状态

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

tsx

export interface GlobalFilterTableState {
  globalFilter: any
}

export interface GlobalFilterTableState {
  globalFilter: any
}

筛选函数

您可以将用于列筛选的相同筛选函数用于全局筛选。有关筛选函数的更多信息，请参阅列筛选。

使用筛选函数

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

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

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

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/[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
}

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
}

列定义选项

enableGlobalFilter

tsx

enableGlobalFilter?: boolean

enableGlobalFilter?: boolean

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

列 API

getCanGlobalFilter

tsx

getCanGlobalFilter: () => boolean

getCanGlobalFilter: () => boolean

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

行 API

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/table-core' {
  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/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

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 用于筛选数据。如果您的表格需要动态支持客户端和服务器端筛选，这可能很有用。

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(),
})

globalFilterFn

tsx

globalFilterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

globalFilterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

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

选项：

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

onGlobalFilterChange

tsx

onGlobalFilterChange?: OnChangeFn<GlobalFilterState>

onGlobalFilterChange?: OnChangeFn<GlobalFilterState>

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

enableGlobalFilter

tsx

enableGlobalFilter?: boolean

enableGlobalFilter?: boolean

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

getColumnCanGlobalFilter

tsx

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

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

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

表格 API

getPreFilteredRowModel

tsx

getPreFilteredRowModel: () => RowModel<TData>

getPreFilteredRowModel: () => RowModel<TData>

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

getFilteredRowModel

tsx

getFilteredRowModel: () => RowModel<TData>

getFilteredRowModel: () => RowModel<TData>

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

setGlobalFilter

tsx

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

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

设置或更新 state.globalFilter 状态。

resetGlobalFilter

tsx

resetGlobalFilter: (defaultState?: boolean) => void

resetGlobalFilter: (defaultState?: boolean) => void

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

getGlobalAutoFilterFn

tsx

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

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

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

getGlobalFilterFn

tsx

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

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

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