模糊过滤指南

示例

想跳过直接看实现？请查看这些示例：

模糊过滤

模糊过滤指南

模糊过滤是一种允许您基于近似匹配来过滤数据的技术。当您想搜索与给定值相似而不是精确匹配的数据时，这会非常有用。

您可以通过定义一个自定义过滤函数来实现客户端模糊过滤。此函数应该接收行、列 ID 和过滤值，并返回一个布尔值，指示该行是否应包含在过滤后的数据中。

模糊过滤主要用于全局过滤，但您也可以将其应用于单个列。我们将讨论如何为这两种情况实现模糊过滤。

注意：您需要安装 @tanstack/match-sorter-utils 库才能使用模糊过滤。TanStack Match Sorter Utils 是 Kent C. Dodds 的 match-sorter 的一个分支。它被分支是为了更好地与 TanStack Table 的逐行过滤方法协同工作。

使用 match-sorter 库是可选的，但 TanStack Match Sorter Utils 库提供了一种很好的方式，既可以进行模糊过滤，又可以通过它返回的排名信息进行排序，这样就可以根据与搜索查询最接近的匹配项对行进行排序。

定义自定义模糊过滤函数

这是一个自定义模糊过滤函数的示例：

import { rankItem } from '@tanstack/match-sorter-utils';
import { FilterFn } from '@tanstack/table';

const fuzzyFilter: FilterFn<any> = (row, columnId, value, addMeta) => {
  // 对项进行排名
  const itemRank = rankItem(row.getValue(columnId), value)

  // 存储 itemRank 信息
  addMeta({ itemRank })

  // 返回该项是否应被过滤入/出
  return itemRank.passed
}

在此函数中，我们使用 @tanstack/match-sorter-utils 库中的 rankItem 函数对项进行排名。然后我们将排名信息存储在行的元数据中，并返回该项是否通过了排名标准。

将模糊过滤与全局过滤一起使用

要将模糊过滤与全局过滤一起使用，您可以在表格实例的 globalFilterFn 选项中指定模糊过滤函数：

const table = useReactTable({ // 或您的框架的等效函数
    columns,
    data,
    filterFns: {
      fuzzy: fuzzyFilter, // 定义为一个可在列定义中使用的过滤函数
    },
    globalFilterFn: 'fuzzy', // 将模糊过滤应用于全局过滤器（模糊过滤最常见的用例）
    getCoreRowModel: getCoreRowModel(),
    getFilteredRowModel: getFilteredRowModel(), // 客户端过滤
    getSortedRowModel: getSortedRowModel(), // 如果您也想使用排序，则需要客户端排序
})

将模糊过滤与列过滤一起使用

要将模糊过滤与列过滤一起使用，您应该首先在表格实例的 filterFns 选项中定义模糊过滤函数。然后，您可以在列定义的 filterFn 选项中指定模糊过滤函数：

const column = [
  {
    accessorFn: row => `${row.firstName} ${row.lastName}`,
    id: 'fullName',
    header: '全名',
    cell: info => info.getValue(),
    filterFn: 'fuzzy', // 使用我们的自定义模糊过滤函数
  },
  // 其他列...
];

在此示例中，我们将模糊过滤应用于结合了数据的 firstName 和 lastName 字段的列。

使用模糊过滤进行排序

将模糊过滤与列过滤一起使用时，您可能还希望根据排名信息对数据进行排序。您可以通过定义自定义排序函数来完成此操作：

import { compareItems } from '@tanstack/match-sorter-utils'
import { sortingFns } from '@tanstack/table'

const fuzzySort: SortingFn<any> = (rowA, rowB, columnId) => {
  let dir = 0
  // 仅当列具有排名信息时才按排名排序
  if (rowA.columnFiltersMeta[columnId]) {
    dir = compareItems(
      rowA.columnFiltersMeta[columnId]?.itemRank!,
      rowB.columnFiltersMeta[columnId]?.itemRank!
    )
  }
  // 当项排名相等时，提供字母数字的备用
  return dir === 0 ? sortingFns.alphanumeric(rowA, rowB, columnId) : dir
}

在此函数中，我们正在比较两行的排名信息。如果排名相等，我们则回退到字母数字排序。

然后，您可以在列定义的 sortFn 选项中指定此排序函数：

{
  accessorFn: row => `${row.firstName} ${row.lastName}`,
  id: 'fullName',
  header: '全名',
  cell: info => info.getValue(),
  filterFn: 'fuzzy', // 使用我们的自定义模糊过滤函数
  sortFn: 'fuzzySort', // 使用我们的自定义模糊排序函数
}

全局过滤指南

列分面指南