TanStack表格 v8
自动
框架
版本
菜单
开始使用
核心指南
功能指南
核心 API
功能 API
企业版
示例

列筛选 API

Can-Filter

列是否可以进行列筛选取决于以下因素

  • 该列已使用有效的 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) => {
  // 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/react-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
}

列定义选项

filterFn

tsx
filterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

filterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

用于此列的筛选函数。

选项

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

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

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>

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

在 GitHub 上编辑
单元格
列分面
订阅 Bytes

您的每周 JavaScript 新闻。每周一免费发送给超过 10 万名开发者。

Bytes

无垃圾邮件。随时取消订阅。