TanStack Table Filtering 指南:全局搜索、列过滤与客户端排序

学习 TanStack Table filtering,涵盖全局搜索、列过滤与客户端排序,并讨论服务端边界,附 SaaS 模板决策清单。

Huifer
Huifer
October 31, 202610 min read
其他语言:Deutsch · English

本文由 Huifer 撰写

我在生产环境中用 TanStack Table 构建管理后台表格,过滤是用户最先使用的功能。当我添加全局搜索、列过滤和客户端排序时,首先要判断哪些数据是我在浏览器里已经拥有的,哪些是必须由服务器作答的数据。明确这条边界,正是让一个快速过滤框区别于「每次按键都发一次请求」的表格的关键。

官方参考: TanStack · TanStack Table filters guide · TanStack Table API reference · TanStack Query · web.dev performance · Cloudflare Workers · MDN

最后更新:2026-10-31 · Changelog

TanStack Table Filtering:全局搜索、列过滤与客户端排序

TanStack Table filtering 的工作原理是:表格读取你的列 schema 和过滤定义,然后计算哪些行符合条件。你可以通过 TableOptions 配置全局过滤(一个跨所有列的搜索框)、列过滤(按列设定的条件)以及排序(按列决定顺序)。本指南面向需要在现有应用中实现过滤、或希望挑选一个数据表已内置该行为的 SaaS 模板的 React 开发者。如果周边的技术栈和数据层也很重要,你可以先比较 SaaS 模板与脚手架,再动手写过滤代码。

TL;DR

  • 列过滤通过 <input/>(或 select)来修改某一列的过滤值;getFilteredRowModel() 负责应用结果。
  • 全局过滤借助 filterFns 和列级 filterFn 选项,让一段搜索文本跨过所有参与搜索的列。
  • 当完整数据集已经加载时,把过滤和排序放在客户端;当行被分页或受权限约束时,就转到服务端。
  • 对大型本地数据集,把客户端过滤与排序组合进一个 memoized 的 useMemo 管线中。
  • 不要盲信模糊匹配/高亮:要核对行数与 null 处理,因为 TanStack Table 对 undefined 和 null 的对待方式不同。

独立回答: TanStack Table 为你提供过滤与排序所需的状态、列选项和行模型,但它并不负责拉取数据。你需要配置 enableColumnFilters、globalFilterFn、列级 filterFn 以及 sorting 选项,然后提供 getFilteredRowModel() 和 getSortedRowModel()。当行数据位于 API 之后时,用服务端驱动的参数取代客户端行模型,并把数据获取放到 TanStack Query 这样的状态容器中。

为什么过滤和排序是用户最先注意到的两个功能

一个数据密集的界面,评判标准是用户能多快找到他在意的那一行。在我自己的后台表格里,搜索和列过滤把定位某条记录的时间从滚动浏览缩短到输入一次查询。TanStack Table filters guide 说得对:过滤是行模型(row-model)层面的问题,与行如何到达浏览器是两回事。排序也属于同一类——它只是把已经可用的行重新排序。当你理解了这一点,就不会再把搜索当作「一次查询调用」,而是当作「客户端行模型的职责范围」。

“headless”对过滤到底意味着什么

Headless 意味着该库暴露的是状态 + 逻辑,而不包含任何标记。渲染输入框的是你;决定列过滤 UI 何时出现的是你。这恰恰是优点:你自己渲染的原生 <input type="search"> 既可访问,也留在你的设计系统之内。随后 TanStack Table 会在每次 filterValue 变化时重新运行行模型,并暴露 instance.filteredRows 与 instance.getRowMeta(),供你展示需要统计的数字。

真实表格里的前后对比

之前: 我在 <select> 里放了一个文本查询,每次变化都重新拉取整个 API 响应,遇到分页重置时产生 200–400 毫秒的感知卡顿和结果不一致。 之后: 我在已加载的页面上加了客户端 globalFilter 配合 getFilteredRowModel(),让每次按键即时返回结果,再把排序放进一个 useMemo。 结果: 过滤框响应迅速,只有用户主动翻页或改一个真正存在于服务端的列过滤时,我才会发一次服务器请求。我没有给本指南附上基准数据;这些是实现预期,不是实测延迟声明。

设置列过滤与全局搜索

列过滤按表和按列开启。你可以用 ColumnFiltersState 同时控制 UI 和值类型。全局搜索是一段文本,与你在 filterFn 列选项中选中的那些列做比较。两者并存:全局搜索是宽的,列过滤是窄的。

用受控输入启用列过滤

tsx
import { useReactTable, getCoreRowModel, getFilteredRowModel, ColumnFiltersState } from '@tanstack/react-table'

export function UsersTable({ data }: { data: User[] }) {
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])

  const table = useReactTable({
    data,
    columns,
    state: { columnFilters },
    onColumnFiltersChange: setColumnFilters,
    getCoreRowModel: getCoreRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    // enable column filter UI only where you allow it
    enableColumnFilters: true,
  })

  const nameFilter = table.getColumn('name')

  return (
    <div>
      <input
        placeholder="Filter by name"
        value={(nameFilter?.getFilterValue() as string) ?? ''}
        onChange={(e) => nameFilter?.setFilterValue(e.target.value)}
      />
      <table>
        {table.getHeaderGroups().map((hg) => (
          <tr key={hg.id}>
            {hg.headers.map((h) => h.isPlaceholder ? null : <th key={h.id}>{h.column.columnDef.header}</th>)}
          </tr>
        ))}
        {table.getRowModel().rows.map((row) => (
          <tr key={row.id}>{row.getVisibleCells().map((cell) => <td key={cell.id}>{cell.getValue()}</td>)}</tr>
        ))}
      </table>
    </div>
  )
}

让它生效的三个部分是 onColumnFiltersChange、getFilteredRowModel(),以及通过 column.setFilterValue() 读写过滤值。如果忘了 getFilteredRowModel(),列过滤状态会变化,但行永远不会被重新计算。

跨多个列做全局搜索

tsx
import { useReactTable, getCoreRowModel, getFilteredRowModel, getSortedRowModel } from '@tanstack/react-table'

const columns = [
  { accessorKey: 'name', filterFn: 'includesString' },
  { accessorKey: 'email', filterFn: 'includesString' },
  { accessorKey: 'status', filterFn: 'equalsString' },
]

export function SearchableTable({ data }: { data: User[] }) {
  const [globalFilter, setGlobalFilter] = useState('')

  const table = useReactTable({
    data,
    columns,
    state: { globalFilter },
    onGlobalFilterChange: setGlobalFilter,
    globalFilterFn: 'includesString',
    getCoreRowModel: getCoreRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    getSortedRowModel: getSortedRowModel(),
  })

  return (
    <input
      value={globalFilter}
      onChange={(e) => setGlobalFilter(e.target.value)}
      placeholder="Search all columns"
    />
  )
}

列级 filterFn 决定全局文本扫描哪些列。'includesString' 区分大小写匹配;只有大小写确实紧要时才用 'includesStringSensitive'。默认的 globalFilterFn 是 auto,会挑选一个适配类型的函数——方便,但不如显式声明来得可预测。

客户端 vs. 服务端过滤的边界

这是 TanStack Table 实现里最有价值的一个决策,而 TanStack Table filters guide 明确说明两种模式都存在。客户端过滤之所以有效,是因为 getFilteredRowModel() 作用于内存中的行。服务端过滤则意味着表格向 API 发送 filtering 查询参数,并渲染返回的内容——也就是说,过滤用的行模型在客户端基本成了空操作。

决策清单

关注点客户端过滤服务端过滤
数据集规模能从容放进内存大规模、已分页,或按租户隔离
搜索延迟即时(无网络)取决于 API 往返耗时
与列表页的一致性足够好与后端真源规则一致
权限 / 租户隔离规则若在服务端则有风险当行按归属权过滤时为必须
跨全集排序只能排已加载的行在完整后端数据集上排序
典型用途覆盖已抓取页面的后台面板企业数据表、审计日志、仪表盘

当我把过滤保持在客户端时,我也会通过一次 useReactTable 调用把两种行模型组合到一起,从而保持排序也在客户端:getFilteredRowModel() 放在 getSortedRowModel() 之前,这样过滤和排序都在各自的元数据有效处运行。在单屏内对一个小的可见页面排序没问题;对 20 万行的导出排序则属于服务器。

组合过滤、排序与分页

tsx
const table = useReactTable({
  data,
  columns,
  state: { columnFilters, sorting },
  onColumnFiltersChange: setColumnFilters,
  onSortingChange: setSorting,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getSortedRowModel: getSortedRowModel(),
  getPaginationRowModel: getPaginationRowModel(),
  initialState: { pagination: { pageSize: 25 } },
})

行模型在 options 对象里的顺序就是它们组合的顺序。对常见场景要保持这一精确顺序:先过滤,再排序,最后分页。如果你把 getPaginationRowModel() 移到过滤之前,页面会先分块,你的过滤永远只能看到一页——这是一种会产出「缺失」行的隐蔽 bug。

自定义过滤函数与 null 值陷阱

TanStack Table 内置了一组 filterFn(includesString、equalsString、inNumberRange、arrIncludes、equals 等)。当默认值不适用时,你可以定义针对每行返回布尔值的自定义函数。我最常踩的坑是 null 处理:TanStack Table 的内置函数对 null 和 undefined 的对待不同,所以一整列都是 null 时,该列可能悄无声息地从搜索结果里消失。

一个对 null 安全的大小写不敏感 contains 过滤器

tsx
const customContains: FilterFn<User> = (row, columnId, filterValue) => {
  const value: unknown = row.getValue(columnId)
  if (filterValue == null || filterValue === '') return true
  if (value == null) return false
  return String(value)
    .toLowerCase()
    .includes(String(filterValue).toLowerCase())
}

在列定义里用 filterFn: customContains 挂载它,或者在表格 options 的 filterFns 下全局注册。因为 filterValue 从你的输入里作为字符串而来,所以要显式做类型转换——一个到达时是 "42" 的数字列过滤需要 Number(),否则永远匹配不上。我会把自定义函数的作用域收窄,并记录可接受的值类型,这样下一个读 schema 的人不会感到意外。

性能考量与服务端逃生出口

过滤几百行微不足道。在单次渲染中过滤几万行时,你就必须对每一次按键的成本诚实。getFilteredRowModel() 每次过滤变化都会重新运行;对小列表没问题,但对大型本地数据集,我会把数据 + 过滤状态包进单个 useMemo,让原始表格留在热循环之外。web.dev performance guide 是理解该模式背后的渲染与记忆化原理的好参考。

何时把过滤推到服务端

当以下任一成立时,就把过滤移到服务端:数据集已分页、行的访问按租户受权限隔离、过滤涉及客户端根本不具备的 join、或者你需要一个稳定的总计数。在服务端模型里,columnFilters 变成查询参数(?name__contains=...),而 TanStack Table 的 onColumnFiltersChange 就是那座桥——在路由或查询键带着需求到达 API 的同时,保持 UI 有状态。我会把这一点与 TanStack Query 搭配使用,让查询键包含过滤值,导航时也能恢复它们。

哪个模板适合这个用例?

免费获得过滤、排序和分页,是开发者选择脚手架而不是从头手写一张表的原因之一。与其把所有读者都导向同一个页面,不如让决策匹配周边技术栈:如果你在评估全栈起点,SaaS 脚手架对比 展示了开箱即用的数据层行为;如果你特别想要一个 starter 内预先配置好的 TanStack 数据表,TanStack 模板目录 是更合适的去处。至于定价与许可的取舍,模板定价与许可条款 页面详述了你要付什么、可以怎么用。

做出选择前: 确认模板的表格是在已加载页面上做客户端过滤(代价是管理后台仪表盘的典型做法),还是通过数据层做服务端过滤,并确认你预期的数据量与该模型相符。我不会为了照抄一个 feature flag 就转向服务端过滤;要基于你的数据集和逐行权限需求来决策。

相关阅读: Tanstack Db 1 0 Rc1 Whats New And Upgrade Guide · Tanstack Table Audit Log D1 Cursors · Tanstack Start Guide 20260711 Comprehensive

FAQ

TanStack Table 会自动过滤服务器响应吗? 不会。过滤作用在你交给行模型的行上。如果你的数据来自 API,要么完整抓取后在客户端过滤,要么把过滤状态发给服务器,再仅对返回的页面应用 getFilteredRowModel()。

全局过滤和列过滤有什么区别? 全局过滤是一段文本值,跨你通过 filterFn 和共享的 globalFilterFn 选中的列做比较。列过滤是逐列的 filterValue,各自带自己的函数,通常由每个表头下方的专用输入驱动。

为什么我的过滤显示无结果? 最常见的原因包括缺少 getFilteredRowModel()、在 getPaginationRowModel() 之前就应用了列过滤导致只扫描到一页,或者类型不匹配——过滤以字符串到达,而 accessor 返回的是数字或 null。

我该对全局搜索做防抖吗? 只有当每次按键都会触发一次服务器请求时才需要。对已加载数据的纯客户端过滤来说,防抖只会增加延迟而毫无收益。如果该值供查询键使用,就对这个防抖进行分页,让 URL 与抓取保持同步。

客户端排序对所有行都准确吗? 只对加载进表格的那些行准确。getSortedRowModel() 给当前数据集排序;一页数据排的是那一页,而不是整个后端。要拿到完全的准确性,就在服务端排序,并通过查询参数驱动 sorting。

披露与局限性: 我在生产环境使用 TanStack Table,但并未给本指南附上实测基准。上述过滤、排序与性能预期来自 TanStack 官方文档以及我自己的用法,属于实现指引;在你自己验证之前,请把行数、延迟和 null 行为相关的声明当作估算值。行数会随数据集体量、浏览器和网络而变。特定模板中按功能可用性之类的细节为用户提供或 [needs source],请对照最新发布说明确认。所有文件路径和 filterFn 名称反映的是撰写时的 TanStack Table API;如果有所漂移,请以最新文档为准。本文不存在实质性商业关联。

总结: 对已经占有的数据,就在客户端用 getFilteredRowModel() 和 getSortedRowModel() 过滤;一旦行被分页、受权限约束或来自 join,就推到服务端。在你自己动手之前,先比较模板如何处理这条边界。