tanstack-table

TanStack Table

当工作涉及 TanStack Table v9 时使用此技能，尤其是 @tanstack/react-table、表格功能组合、复杂数据网格行为，或从 v8 API 迁移时。

工作流

1. 更改代码前，确认本地版本和目标 API：
   • @tanstack/react-table、@tanstack/table-core、可选的 @tanstack/react-table-devtools、可选的 @tanstack/react-store、可选的 @tanstack/react-virtual，以及 React 版本。
   • 应用是否使用稳定版 v9（latest 为 9.2.x）。较旧的应用可能仍锁定在 v8；不要混用 v8 和 v9 API。
   • 当前的表格创建方式：useTable、createTableHook、stockFeatures 或临时使用的 useLegacyTable。
   • tableFeatures() 中注册了哪些功能，以及实际需要哪些行模型工厂。
2. 对于迁移、新功能 API 或软件包不匹配情况，查阅最新文档。从 source-map.md 开始。
3. 关于安装、核心设置、列、渲染和行模型，请参阅 setup-core.md。
4. 关于 v8 到 v9 的迁移、useLegacyTable、状态所有权、外部 atoms、选择器、表格上下文和 React Compiler 注意事项，请参阅 state-and-migration.md。
5. 关于排序、筛选、分面、分页、选择、固定、调整大小、分组、聚合、单元格选择和跨列，请参阅 features.md。
6. 关于服务端模式、TanStack Query、虚拟化、开发者工具、工作线程行模型、性能、无障碍和测试，请参阅 production-patterns.md。

实现判断

• 对于一次性表格，优先使用 useTable 并显式配置 tableFeatures()。多个表格共享功能、默认值或标准化组件时，使用 createTableHook。仅当暂时不必考虑 tree-shaking 时，才将 stockFeatures 用作包含所有功能的快捷方案。
• 只注册表格所需的功能。核心行模型会自动提供；客户端筛选、排序、分组、展开、分面和分页需要匹配的行模型工厂。
• 在注册表插槽中优先单独导入 filterFn_*、sortFn_* 和 aggregationFn_* 条目。完整的 filterFns / sortFns / aggregationFns 对象仍然可用，但会打包所有内置项。
• 在多次渲染之间保持 data、columns 和可复用列辅助函数稳定。
• 不要从行、单元格、列或表头实例中解构方法；应直接在实例上调用这些方法。
• 单元格和表头应使用 table.FlexRender 或 v9 的 FlexRender 组件。
• 对于驱动服务端查询、持久化或跨组件 UI 的状态，优先使用外部 atoms。对于简单的迁移工作，经典的 state 加 onXChange 模式仍然适用。
• 如果服务端已返回处理后的数据，请使用 manualSorting、manualFiltering、manualPagination 和 manualGrouping。确保所有表格操作都针对相同的数据范围。
• v9 兼容 React Compiler；移除 v8 的 'use no memo' 变通方案。仅接收稳定 row / cell / column / header 对象的嵌套组件，必须通过 Subscribe / useSelector 订阅它们要渲染的状态。
• 仅将 useLegacyTable 视为临时迁移桥接方案。它会捆绑所有功能、保持完整状态订阅，并且不支持 v9 的主要可组合性优势。
• 列固定使用逻辑上的 start / end 区域（而非 left / right）。聚合是独立的 rowAggregationFeature，与 columnGroupingFeature 无关。

验证

优先使用仓库现有的检查。对于有意义的 TanStack Table 更改，请纳入相关检查子集：

• 包/版本检查，证明使用到的 v9 API 可用。
• 类型检查，覆盖功能注册、列定义、状态切片和行模型槽位。
• 针对排序、筛选、分页、选择、单元格选择、展开、固定、调整大小、跨列跨行以及服务端查询集成的定向交互测试。
• 浏览器冒烟测试，检查渲染标记、键盘/焦点行为、粘性或虚拟化布局，以及调整大小/滚动性能。
• 对大型表格、虚拟化或列调整大小相关更改进行生产构建或性能分析。