全局筛选 API

Can-Filter

列是否可以被全局筛选取决于以下条件

该列已定义有效的 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
}

筛选函数

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

使用筛选函数

筛选函数可以通过将以下内容传递给 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

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

Can-Filter

状态

筛选函数

使用筛选函数

筛选元数据

列定义选项

enableGlobalFilter

列 API

getCanGlobalFilter

行 API

columnFiltersMeta

表格选项

filterFns

filterFromLeafRows

maxLeafRowFilterDepth

enableFilters

manualFiltering

getFilteredRowModel

globalFilterFn

onGlobalFilterChange

enableGlobalFilter

getColumnCanGlobalFilter

表格 API

getPreFilteredRowModel

getFilteredRowModel

setGlobalFilter

resetGlobalFilter

getGlobalAutoFilterFn

getGlobalFilterFn

订阅 Bytes

订阅 Bytes