列过滤 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

用于此列的过滤函数。

选项

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

行的列过滤器映射。此对象跟踪行是否通过/失败其 column 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>

返回应用列过滤后表格的行模型。

Can-Filter

状态

过滤函数

filterFn.resolveFilterValue

filterFn.autoRemove

使用过滤函数

过滤元数据

列定义选项

filterFn

enableColumnFilter

列 API

getCanFilter

getFilterIndex

getIsFiltered

getFilterValue

setFilterValue

getAutoFilterFn

getFilterFn

行 API

columnFilters

columnFiltersMeta

表格选项

filterFns

filterFromLeafRows

maxLeafRowFilterDepth

enableFilters

manualFiltering

onColumnFiltersChange

enableColumnFilters

getFilteredRowModel

表格 API

setColumnFilters

resetColumnFilters

getPreFilteredRowModel

getFilteredRowModel

订阅 Bytes

订阅 Bytes