全局过滤 API

可以过滤

列是否可以被**全局**过滤取决于以下条件：

该列被定义了一个有效的 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) => {
  // Rank the item
  const itemRank = rankItem(row.getValue(columnId), value)

  // Store the ranking info
  addMeta(itemRank)

  // Return if the item should be filtered in/out
  return itemRank.passed
}

const fuzzySort = (rowA, rowB, columnId) => {
  let dir = 0

  // Only sort by rank if the column has ranking information
  if (rowA.columnFiltersMeta[columnId]) {
    dir = compareItems(
      rowA.columnFiltersMeta[columnId]!,
      rowB.columnFiltersMeta[columnId]!
    )
  }

  // Provide an alphanumeric fallback for when the item ranks are equal
  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) => {
  // Rank the item
  const itemRank = rankItem(row.getValue(columnId), value)

  // Store the ranking info
  addMeta(itemRank)

  // Return if the item should be filtered in/out
  return itemRank.passed
}

const fuzzySort = (rowA, rowB, columnId) => {
  let dir = 0

  // Only sort by rank if the column has ranking information
  if (rowA.columnFiltersMeta[columnId]) {
    dir = compareItems(
      rowA.columnFiltersMeta[columnId]!,
      rowB.columnFiltersMeta[columnId]!
    )
  }

  // Provide an alphanumeric fallback for when the item ranks are equal
  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) => {
      // return the filtered rows
    },
  },
})

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) => {
      // return the filtered rows
    },
  },
})

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

返回表格的全局过滤函数（根据配置，可能是用户定义的或自动的）。

可以过滤

状态

过滤函数

使用过滤函数

过滤元数据

列定义选项

enableGlobalFilter

列 API

getCanGlobalFilter

行 API

columnFiltersMeta

表格选项

filterFns

filterFromLeafRows

maxLeafRowFilterDepth

enableFilters

manualFiltering

getFilteredRowModel

globalFilterFn

onGlobalFilterChange

enableGlobalFilter

getColumnCanGlobalFilter

表格 API

getPreFilteredRowModel

getFilteredRowModel

setGlobalFilter

resetGlobalFilter

getGlobalAutoFilterFn

getGlobalFilterFn

订阅 Bytes

订阅 Bytes