TanStackTable v8
自动
框架
版本
菜单
入门
核心指南
功能指南
核心 API
功能 API
企业版
示例

全局筛选指南

示例

想要直接跳到实现部分吗？请查看以下示例：

API

全局筛选 API

全局筛选指南

筛选有两种类型：列筛选和全局筛选。

本指南将重点介绍全局筛选，这是一种应用于所有列的筛选器。

客户端筛选与服务器端筛选

如果您有大型数据集，您可能不希望将所有数据加载到客户端浏览器中进行筛选。在这种情况下，您很可能需要实现服务器端筛选、排序、分页等。

然而，正如分页指南中所讨论的那样，许多开发人员低估了可以在客户端加载而不会影响性能的行数。TanStack table 示例通常经过测试，可以处理多达 100,000 行或更多行，并且在客户端筛选、排序、分页和分组方面具有不错的性能。这并不一定意味着您的应用程序能够处理那么多行，但是如果您的表格最多只有几千行，您也许可以利用 TanStack table 提供的客户端筛选、排序、分页和分组功能。

TanStack Table 可以处理数千行客户端数据并保持良好性能。在仔细考虑之前，不要排除客户端筛选、分页、排序等功能。

每个用例都不同，具体取决于表格的复杂性、列数、每个数据片段的大小等。需要注意的主要瓶颈是：

  1. 您的服务器能否在合理的时间（和成本）内查询所有数据？
  2. 获取的总大小是多少？（如果您没有很多列，这可能不会像您想象的那么糟糕。）
  3. 如果一次加载所有数据，客户端浏览器是否会使用过多的内存？

如果您不确定，可以先从客户端筛选和分页开始，然后在数据增长时切换到服务器端策略。

手动服务器端全局筛选

如果您已决定需要实现服务器端全局筛选而不是使用内置的客户端全局筛选，请按以下步骤操作。

手动服务器端全局筛选不需要 getFilteredRowModel 表格选项。相反，您传递给表格的 data 应已筛选。但是，如果您已传递 getFilteredRowModel 表格选项，则可以通过将 manualFiltering 选项设置为 true 来告诉表格跳过它。

jsx
const table = useReactTable({
  data,
  columns,
  // getFilteredRowModel: getFilteredRowModel(), // 手动服务器端全局筛选不需要
  manualFiltering: true,
})

const table = useReactTable({
  data,
  columns,
  // getFilteredRowModel: getFilteredRowModel(), // 手动服务器端全局筛选不需要
  manualFiltering: true,
})

注意：使用手动全局筛选时，本指南其余部分讨论的许多选项将不起作用。当 manualFiltering 设置为 true 时，表格实例不会对传递给它的行应用任何全局筛选逻辑。相反，它将假定行已筛选，并将按原样使用您传递给它的数据。

客户端全局筛选

如果您正在使用内置的客户端全局筛选，首先需要在表格选项中传递一个 getFilteredRowModel 函数。

jsx
import { useReactTable, getFilteredRowModel } from '@tanstack/react-table'
//...
const table = useReactTable({
  // 其他选项...
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(), // 客户端全局筛选需要
})

import { useReactTable, getFilteredRowModel } from '@tanstack/react-table'
//...
const table = useReactTable({
  // 其他选项...
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(), // 客户端全局筛选需要
})

全局筛选函数

globalFilterFn 选项允许您指定将用于全局筛选的筛选函数。筛选函数可以是一个引用内置筛选函数的字符串，一个引用通过 tableOptions.filterFns 选项提供的自定义筛选函数的字符串，或一个自定义筛选函数。

jsx
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  globalFilterFn: 'text' // 内置筛选函数
})

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  globalFilterFn: 'text' // 内置筛选函数
})

默认情况下，有 10 个内置筛选函数可供选择：

  • includesString - 不区分大小写的字符串包含
  • includesStringSensitive - 区分大小写的字符串包含
  • equalsString - 不区分大小写的字符串相等
  • equalsStringSensitive - 区分大小写的字符串相等
  • arrIncludes - 数组中的项包含
  • arrIncludesAll - 数组中包含所有项
  • arrIncludesSome - 数组中包含某些项
  • equals - 对象/引用相等 Object.is/===
  • weakEquals - 弱对象/引用相等 ==
  • inNumberRange - 数字范围包含

您还可以将自己的自定义筛选函数定义为 globalFilterFn 表格选项。

全局筛选器状态

全局筛选器状态存储在表格的内部状态中，可以通过 table.getState().globalFilter 属性访问。如果您想在表格外部持久化全局筛选器状态，可以使用 onGlobalFilterChange 选项提供一个回调函数，每当全局筛选器状态更改时都会调用该函数。

jsx
const [globalFilter, setGlobalFilter] = useState<any>([])

const table = useReactTable({
  // 其他选项...
  state: {
    globalFilter,
  },
  onGlobalFilterChange: setGlobalFilter
})

const [globalFilter, setGlobalFilter] = useState<any>([])

const table = useReactTable({
  // 其他选项...
  state: {
    globalFilter,
  },
  onGlobalFilterChange: setGlobalFilter
})

全局筛选状态定义为一个具有以下形状的对象：

jsx
interface GlobalFilter {
  globalFilter: any
}

interface GlobalFilter {
  globalFilter: any
}

将全局筛选输入添加到 UI

TanStack table 不会向您的表格添加全局筛选输入 UI。您应该手动将其添加到 UI 中，以允许用户筛选表格。例如，您可以在表格上方添加一个输入 UI，以允许用户输入搜索词。

jsx
return (
  <div>
    <input
      value=""
      onChange={e => table.setGlobalFilter(String(e.target.value))}
      placeholder="Search..."
    />
  </div>
)

return (
  <div>
    <input
      value=""
      onChange={e => table.setGlobalFilter(String(e.target.value))}
      placeholder="Search..."
    />
  </div>
)

自定义全局筛选函数

如果要使用自定义全局筛选函数，可以定义该函数并将其传递给 globalFilterFn 选项。

注意： 将模糊筛选函数用于全局筛选通常是一个流行的想法。这在模糊筛选指南中进行了讨论。

jsx
const customFilterFn = (rows, columnId, filterValue) => {
  // 自定义筛选逻辑
}

const table = useReactTable({
  // 其他选项...
  globalFilterFn: customFilterFn
})

const customFilterFn = (rows, columnId, filterValue) => {
  // 自定义筛选逻辑
}

const table = useReactTable({
  // 其他选项...
  globalFilterFn: customFilterFn
})

初始全局筛选器状态

如果要在初始化表格时设置初始全局筛选器状态，可以将全局筛选器状态作为表格 initialState 选项的一部分传递。

但是，您也可以只在 state.globalFilter 选项中指定初始全局筛选器状态。

jsx
const [globalFilter, setGlobalFilter] = useState("search term") //建议在此处初始化 globalFilter 状态

const table = useReactTable({
  // 其他选项...
  initialState: {
    globalFilter: 'search term', // 如果不管理 globalFilter 状态，请在此处设置初始状态
  }
  state: {
    globalFilter, // 将我们管理的 globalFilter 状态传递给表格
  }
})

const [globalFilter, setGlobalFilter] = useState("search term") //建议在此处初始化 globalFilter 状态

const table = useReactTable({
  // 其他选项...
  initialState: {
    globalFilter: 'search term', // 如果不管理 globalFilter 状态，请在此处设置初始状态
  }
  state: {
    globalFilter, // 将我们管理的 globalFilter 状态传递给表格
  }
})

注意：不要同时使用 initialState.globalFilter 和 state.globalFilter，因为 state.globalFilter 中的初始化状态将覆盖 initialState.globalFilter。

禁用全局筛选

默认情况下，所有列都启用了全局筛选。您可以使用 enableGlobalFilter 表格选项禁用所有列的全局筛选。您还可以通过将 enableFilters 表格选项设置为 false 来关闭列筛选和全局筛选。

禁用全局筛选将导致该列的 column.getCanGlobalFilter API 返回 false。

jsx
const columns = [
  {
    header: () => 'Id',
    accessorKey: 'id',
    enableGlobalFilter: false, // 禁用此列的全局筛选
  },
  //...
]
//...
const table = useReactTable({
  // 其他选项...
  columns,
  enableGlobalFilter: false, // 禁用所有列的全局筛选
})

const columns = [
  {
    header: () => 'Id',
    accessorKey: 'id',
    enableGlobalFilter: false, // 禁用此列的全局筛选
  },
  //...
]
//...
const table = useReactTable({
  // 其他选项...
  columns,
  enableGlobalFilter: false, // 禁用所有列的全局筛选
})
在 GitHub 上编辑
列筛选
模糊筛选