TanStack Table 是一个无头（headless）数据表格库，本条目聚焦其 v8 版本在 React 中的使用，并给出面向 Cloudflare Workers + D1 的服务端分页、过滤、排序与虚拟化方案。它本身不提供 UI，只负责表格状态与数据模型，由开发者自行渲染表格结构。
用途 用于构建数据表格，尤其是需要服务端分页、过滤、排序以及大数据量虚拟化的场景。资料同时覆盖 Cloudflare Workers + D1 的服务端实现模式。
主要能力
- 核心表格模型：通过 useReactTable 与 getCoreRowModel 构建基础表格。
- 服务端模式：配合 Cloudflare D1 的 SQL 查询实现分页、过滤、排序，并通过 manualPagination、manualFiltering、manualSorting 标志交由服务端处理。
- 虚拟化：使用 @tanstack/react-virtual 仅渲染可见行，适用于 1000+ 行数据。
- 列/行固定：支持将列固定在左/右、行固定在顶/底。
- 行展开：支持嵌套子行（subRows）与自定义详情行。
- 行分组：按列值分组，并支持 sum、min、max、extent、mean、median、unique、uniqueCount、count 等内置聚合函数。
使用方式 安装： npm install @tanstack/react-table@latest npm install @tanstack/react-virtual@latest # For virtualization
基础设置中强调必须对 data/columns 做 memoize 以防止无限重渲染。服务端模式示例包含 Workers API（functions/api/users.ts）的 onRequestGet 实现，以及客户端使用 TanStack Query + Table 的写法，其中要求把全部状态（pagination、columnFilters、sorting）放入 query key。虚拟化示例使用 useVirtualizer，并设置 count、getScrollElement、estimateSize、overscan。列/行固定通过 enableColumnPinning、enableRowPinning 与 initialState.columnPinning 配置，并可用 column.pin('left')、row.pin('top') 等方法切换。行展开需 getExpandedRowModel 与 getSubRows。行分组需 getGroupedRowModel 与 getExpandedRowModel，并在列上配置 aggregationFn 与 aggregatedCell。
适用场景
- 需要服务端分页/过滤/排序的表格应用。
- 部署在 Cloudflare Workers + D1 上的数据表格。
- 需要虚拟化的大数据量表格（1000+ 行）。
- 需要列固定、行展开或行分组的复杂表格。
限制与已知问题 资料列出 12 类问题及规避方法：
- 无限重渲染：data 或 columns 引用每次渲染都变化，需用 useMemo 或定义在组件外。
- 查询与表格状态不同步：query key 缺少表格状态，需包含全部状态。
- 服务端功能不生效：缺少 manual* 标志，需设置 manualPagination、manualFiltering、manualSorting 并提供 pageCount。
- TypeScript “Cannot Find Module”：createColumnHelper 应从 @tanstack/react-table 导入，而非 @tanstack/table-core。
- 服务端排序不工作：排序状态未进入 query key/API 参数，需加入并设置 manualSorting 与 onSortingChange。
- 1000+ 行性能差：使用 TanStack Virtual 或服务端分页。
- React 编译器不兼容（React 19+）：在组件顶部加 "use no memo" 指令；该问题也影响列可见性与行选择，完整修复将在 v9。
- 服务端分页行选择缺陷：toggleAllRowsSelected(false) 只取消当前页，需手动清空选择状态。
- 客户端 onPaginationChange 返回错误 pageIndex：客户端模式存在状态跟踪缺陷，可改用 manualPagination。
- 数据移除后行选择未清理：需手动清理选择状态或使用 table.resetRowSelection(true)。
- React DevTool 下性能下降（资料在此处截断，未提供完整内容）。
- 虚拟化在隐藏容器（Tabs/Modals）中的问题：隐藏时虚拟化仍执行布局计算，导致无限重渲染、滚动位置错误或空表；可通过 enabled 条件或条件渲染规避。
其他已知问题：列固定与列分组同时使用时，固定父分组列会导致定位错误与表头重复（GitHub Issue #5397），建议不对分组列启用固定；行分组在中大型数据集上性能显著下降，50k 行渲染时间可能从不到 1 秒增至 30-40 秒（GitHub Issue #5926），建议服务端分组、分页或对 10k+ 行禁用分组。
版本信息 @tanstack/react-table@8.21.3，@tanstack/react-virtual@3.13.18。最后更新：2026-01-09。