tanstack-table

TanStack Table

概述

TanStack Table 是一个无头表格库——它提供状态管理和逻辑，但不提供 UI。渲染由你负责；它负责处理排序、筛选、分页、选择等操作。

适用场景： 需要排序、筛选和分页的复杂数据表、服务端数据、大型数据集（1000 行以上并启用虚拟化）、行选择／展开／分组。

不适用场景： 简单的静态表格（直接使用 <table>）、仅用于展示的列表（使用列表组件）、类似电子表格的编辑（可考虑使用 AG Grid）。

快速参考

模式	API / 配置	要点
基本表格	useReactTable({ data, columns, getCoreRowModel })	对 data/columns 使用记忆化，避免重复渲染
列辅助工具	createColumnHelper<T>()	类型安全的列定义
列分组	columnHelper.group({ header, columns })	嵌套表头；不要固定分组列
排序	getSortedRowModel() + onSortingChange	服务端排序使用 manualSorting: true
筛选	getFilteredRowModel() + onColumnFiltersChange	服务端筛选使用 manualFiltering: true
分页	getPaginationRowModel() + onPaginationChange	manualPagination: true + pageCount
行选择	enableRowSelection + onRowSelectionChange	设置 getRowId，以便使用稳定的选择键
列可见性	onColumnVisibilityChange	使用 column.toggleVisibility() 切换
列固定	enableColumnPinning + initialState.columnPinning	不要固定分组列（已知问题）
行展开	getExpandedRowModel() + getSubRows	用于嵌套／树形数据
列调整大小	enableColumnResizing + columnResizeMode	实时调整使用 onChange，追求性能使用 onEnd
行分组	getGroupedRowModel() + aggregationFn	行数达到 10k 以上时性能会下降
服务端处理	manual*: true 标记 + 在 queryKey 中包含状态	将所有状态放入查询键，以便正确重新获取数据
无限滚动	useInfiniteQuery + 展平页面	与 TanStack Virtual 结合，获得最佳性能
虚拟化	@tanstack/react-virtual 中的 useVirtualizer	容器隐藏时（选项卡／模态框）禁用
React 19 编译器	'use no memo' 指令	在 v9 修复编译器兼容性之前必须使用

常见操作

任务	方法
排序列	column.toggleSorting()
筛选列	column.setFilterValue(value)
第一页	table.firstPage()
下一页	table.nextPage()
上一页	table.previousPage()
最后一页	table.lastPage()
跳转到指定页	table.setPageIndex(n)
选择行	row.toggleSelected()
隐藏列	column.toggleVisibility()
获取原始数据	row.original
固定列	column.pin('left')
调整列大小	header.getResizeHandler()
展开行	row.toggleExpanded()

行模型

导入	用途
getCoreRowModel	必需
getSortedRowModel	排序
getFilteredRowModel	筛选
getPaginationRowModel	分页
getExpandedRowModel	展开
getGroupedRowModel	分组
getFacetedRowModel	分面筛选计数
getFacetedUniqueValues	每个分面的唯一值
getFacetedMinMaxValues	每个分面的最小值／最大值

常见错误

错误	正确做法
数据／列引用不稳定	使用 useMemo 进行记忆化，或在组件外定义
服务端处理时缺少 manual* 标志	设置 manualPagination、manualSorting、manualFiltering
查询键缺少表格状态	在 queryKey 中包含分页、排序和筛选条件
从 @tanstack/table-core 导入	从 @tanstack/react-table 导入
使用 v7 的 useTable／Header／accessor	使用 v8 的 useReactTable／header／accessorKey
固定分组列	固定组内的单列，而不是父列
对 10k+ 行进行分组	使用服务端分组，或对大型数据集禁用分组
更改页面时列筛选器未清除	筛选条件更改时将 pageIndex 重置为 0
使用 React Compiler 时缺少 'use no memo'	在使用 useReactTable 的组件中添加该指令
行选择时缺少 getRowId	设置 getRowId: (row) => row.id，以确保选择键稳定
筛选值类型不匹配	保持值类型一致；使用 undefined 而非 null 清除值

委派

• 表格模式探索：使用 Explore agent
• 服务端集成审查：使用 Task agent
• 代码审查：委派给 code-reviewer agent

如果有 tanstack-query skill，将数据获取、缓存和无限查询模式委派给它。 如果有 tanstack-virtual skill，将独立的虚拟化模式委派给它。 如果有 tanstack-router skill，将服务端表格状态的 URL 搜索参数同步委派给它。 如果有 tanstack-start skill，将服务端数据加载的服务端函数委派给它。

参考资料

• 列定义、辅助函数、可见性和选择
• 筛选：列筛选、全局筛选、模糊筛选和分面筛选
• 使用 TanStack Query 的服务端模式
• 使用游标分页的无限滚动
• 可复用表格组件（Shadcn 样式）
• 大型数据集的虚拟化
• 列和行固定
• 行展开和分组
• 已知问题及解决方案（记录了 15 项）
• v7 到 v8 迁移指南