全局过滤指南

过滤分为 2 种类型：列过滤和全局过滤。

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

客户端与服务端过滤

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

然而，正如在分页指南中讨论的那样，许多开发人员低估了客户端可以加载多少行数据而不会造成性能下降。TanStack Table 示例通常经过测试，可以处理多达 100,000 行或更多的数据，客户端在过滤、排序、分页和分组方面表现出良好的性能。这不一定意味着您的应用程序能够处理那么多行数据，但如果您的表格最多只有几千行，您或许可以利用 TanStack Table 提供的客户端过滤、排序、分页和分组功能。

TanStack Table 可以处理数千行客户端数据，并保持良好的性能。不要在没有经过深思熟虑的情况下排除客户端过滤、分页、排序等。

每个用例都不同，并且取决于表格的复杂性、您拥有的列数、每条数据的大小等等。需要注意的主要瓶颈是

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

如果您不确定，您可以始终从客户端过滤和分页开始，然后在未来随着数据的增长切换到服务端策略。

手动服务端全局过滤

如果您已决定需要实现服务端全局过滤，而不是使用内置的客户端全局过滤，那么以下是如何操作的方法。

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

jsx

const table = useReactTable({
  data,
  columns,
  // getFilteredRowModel: getFilteredRowModel(), // not needed for manual server-side global filtering
  manualFiltering: true,
})

const table = useReactTable({
  data,
  columns,
  // getFilteredRowModel: getFilteredRowModel(), // not needed for manual server-side global filtering
  manualFiltering: true,
})

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

客户端全局过滤

如果您正在使用内置的客户端全局过滤，首先您需要将 getFilteredRowModel 函数传递给表格选项。

jsx

import { useReactTable, getFilteredRowModel } from '@tanstack/react-table'
//...
const table = useReactTable({
  // other options...
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(), // needed for client-side global filtering
})

import { useReactTable, getFilteredRowModel } from '@tanstack/react-table'
//...
const table = useReactTable({
  // other options...
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(), // needed for client-side global filtering
})

全局过滤器函数

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

jsx

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  globalFilterFn: 'text' // built-in filter function
})

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  globalFilterFn: 'text' // built-in filter function
})

默认情况下，有 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({
  // other options...
  state: {
    globalFilter,
  },
  onGlobalFilterChange: setGlobalFilter
})

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

const table = useReactTable({
  // other options...
  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) => {
  // custom filter logic
}

const table = useReactTable({
  // other options...
  globalFilterFn: customFilterFn
})

const customFilterFn = (rows, columnId, filterValue) => {
  // custom filter logic
}

const table = useReactTable({
  // other options...
  globalFilterFn: customFilterFn
})

初始全局过滤器状态

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

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

jsx

const [globalFilter, setGlobalFilter] = useState("search term") //recommended to initialize globalFilter state here

const table = useReactTable({
  // other options...
  initialState: {
    globalFilter: 'search term', // if not managing globalFilter state, set initial state here
  }
  state: {
    globalFilter, // pass our managed globalFilter state to the table
  }
})

const [globalFilter, setGlobalFilter] = useState("search term") //recommended to initialize globalFilter state here

const table = useReactTable({
  // other options...
  initialState: {
    globalFilter: 'search term', // if not managing globalFilter state, set initial state here
  }
  state: {
    globalFilter, // pass our managed globalFilter state to the table
  }
})

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

禁用全局过滤

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

禁用全局过滤将导致 column.getCanGlobalFilter API 为该列返回 false。

jsx

const columns = [
  {
    header: () => 'Id',
    accessorKey: 'id',
    enableGlobalFilter: false, // disable global filtering for this column
  },
  //...
]
//...
const table = useReactTable({
  // other options...
  columns,
  enableGlobalFilter: false, // disable global filtering for all columns
})

const columns = [
  {
    header: () => 'Id',
    accessorKey: 'id',
    enableGlobalFilter: false, // disable global filtering for this column
  },
  //...
]
//...
const table = useReactTable({
  // other options...
  columns,
  enableGlobalFilter: false, // disable global filtering for all columns
})

全局过滤指南

示例

API