TanStack Table v9 状态管理完全指南:Octane 适配器下的原子化 Table State
TanStack Table v9 状态管理完全指南:Octane 适配器下的原子化 Table State
本指南以
docs/framework/octane/guide/table-state.md为骨架,结合仓库内 packages/octane-table 与 packages/table-core 的源码实现展开,系统讲解 TanStack Table v9 中表格状态(Table State)的原子化模型、读取与订阅方式、受控模式以及类型系统,并给出可直接运行的服务端分页、选择性订阅等实战方案。
如果把 TanStack Table 压缩成一句话,那就是:TanStack Table 是一个面向表格状态的大型状态管理协调器。理解表状态是如何构建、读取、订阅和写入的,是理解整个框架如何运作、以及如何以最佳方式使用它的基础。本文将以 Octane 适配器(@tanstack/octane-table)为视角,从状态模型、读取路径、写入路径、受控模式到 TypeScript 类型逐层拆解。
你真的需要自己管理外部状态吗?
大多数情况下,你不需要自己管理表格状态。只要你不向 initialState、atoms、state 以及任何 on[State]Change 表选项传入内容,TanStack Table 就会在内部自主管理状态。
但总会有一些场景需要你定制与内部表状态的交互方式,甚至把状态提升到自己的作用域中(例如把分页、排序放进服务端请求的 query key)。TanStack Table 允许你按需**读取(read)、订阅(subscribe)或拥有(own)**应用中真正关心的状态切片。本文会解释:
- v9 中表状态如何在 TanStack Store 之上工作;
- 如何读取状态(一次性取值 vs 响应式订阅);
- 何时使用外部原子(external atoms)或外部状态(external state)。
v9 的状态模型:从整体 store 到独立原子
TanStack Table v9 围绕 TanStack Store 彻底重构了状态管理。TanStack Store 采用 alien-signals 实现,支持高性能的派生状态。对表格而言,这意味着表格可以从相互独立的状态原子(atoms)派生出一个完整的状态 store,而 Octane 组件可以只订阅它真正需要的那些表状态片段。
一个表格实例(table instance)暴露了以下几个状态表面:
| 表面 | 类型 | 含义 |
|---|---|---|
table.baseAtoms |
可写原子集合 | 由解析后的初始状态创建的内部可写原子,是"内部自有状态"的低层写入面 |
table.atoms |
只读派生原子集合 | 按注册的状态切片逐一暴露的只读派生原子,如 table.atoms.rowSelection |
table.store |
只读扁平 Store | 把所有已注册的 table.atoms 组装到一起,派生出的扁平 TanStack Store |
table.state |
适配器选择结果 | Octane 适配器选中的状态,其类型与取值来自 useTable 第二个参数传入的 selector |
从源码看,这一模型在 constructTable.ts 中落地:先由每个 feature 的 getInitialState 合并用户 initialState 得到 table.initialState,随后遍历状态键为每个切片创建一个可写原子并登记到 table.baseAtoms,再由这些 base atoms 派生只读的 table.atoms 与扁平 table.store。
与旧版本最本质的差异是:表状态现在是原子化的。Octane 可以订阅全部选中状态、选中的部分状态,甚至单个原子(如 table.atoms.rowSelection)。粒度由你决定,渲染成本也因此可以被精确控制。
Feature 驱动:只有注册了功能,才有对应状态
状态切片只为注册进 features 的功能创建。这让 TanStack Table 保持 tree-shakeable(可摇树优化),也让 TypeScript 对状态的推断更加精确。
例如,features 中包含 rowPaginationFeature 时,TypeScript 才会暴露分页状态 API 和 table.atoms.pagination;如果 features 不包含它,那么 pagination 就不应该出现在 table.atoms、table.store.state、table.state、initialState、state 或 atoms 中的任何一处:
const features = tableFeatures({
rowPaginationFeature,
rowSortingFeature,
paginatedRowModel: createPaginatedRowModel(),
sortedRowModel: createSortedRowModel(),
sortFns,
})
const table = useTable({
features,
columns,
data,
})
table.atoms.pagination.get()
table.atoms.sorting.get()
// table.atoms.rowSelection // 未注册 rowSelectionFeature 时这里是 TypeScript 错误
这套基于 feature 的类型约束同样适用于内置功能与自定义 feature 提供的状态。从 coreTablesFeature.types.ts 中的声明(readonly atoms: Atoms<TFeatures>、readonly baseAtoms: BaseAtoms<TFeatures>)可以看出,atoms 与 baseAtoms 的类型都直接以 TFeatures 泛型为参数——这正是"未注册即不存在"这一约束的静态层保证。
读取表状态:取值与订阅是两件事
读取表状态时要区分两个不同的问题:
- 你只是需要当前值?
- 还是希望当值变化时让 Octane 组件重新渲染?
取当前值用直接读取原子或 store;响应式渲染用 selector 订阅。 两者切勿混淆。
不订阅的一次性读取
最简洁、最高性能的读取方式是直接读取对应的原子:
const pagination = table.atoms.pagination.get()
const sorting = table.atoms.sorting.get()
也可以读取当前扁平 store 的快照:
const tableState = table.store.state
const pagination = table.store.state.pagination
注意:这些读取不是 Octane 订阅。在渲染期间调用 table.atoms.pagination.get() 或 table.store.state.pagination 读到的只是当前值,未来该值变化时组件不会自动重渲染(除非有其他因素触发渲染)。如果 UI 需要响应表状态变化保持实时,请使用 useTable 的状态选择、table.Subscribe,或 TanStack Store 的 useSelector。
用 useTable 响应式读取
useTable 的第二个参数是一个 TanStack Store selector。默认情况下,该 selector 相当于选中全部已注册表状态,因此 table.state 包含完整状态,组件会在任一被选中状态变化时重新渲染。
传入自定义 selector 可以让 table.state 只包含你关心的、需要触发重渲染的状态值。Octane 适配器会对选中的值做浅比较(shallow compare)。
const table = useTable(
{
features,
columns,
data,
},
(state) => ({
pagination: state.pagination,
}),
)
table.state.pagination
源码印证:在 useTable.tsrx 中,useTable 通过 useSelector(rootSource, selector, { compare: shallow }) 完成选择,选择结果即暴露为 table.state。这意味着 selector 选得越窄,父组件重渲染触发面就越小。
对于大型表格,还可以让父表格组件完全退出表状态重渲染,把订阅下放到树中的更低层级:
const table = useTable(
{
features,
columns,
data,
},
() => null,
)
这种模式下,父组件不会因表状态变化而重渲染;把响应式读取放进真正需要它们的 UI 位置,也就是 table.Subscribe 内部。
用 Selector 与 table.Subscribe 优化重渲染
当你想让表状态引发的重渲染精确发生在 Octane 组件树中的某个特定位置时,使用 table.Subscribe。这对大型或渲染成本高昂的表格很有价值——但它通常是在默认 useTable selector 已经造成肉眼可见的性能问题之后才需要考虑的手段,先默认,后优化。
不带 source prop 时,table.Subscribe 订阅 table.store 并要求提供 selector;带 source prop 时,它可以直接订阅单个原子或 store,例如 table.atoms.rowSelection:
const table = useTable(
{
features,
columns,
data,
},
() => null,
)
<table.Subscribe
selector={(state) => ({
columnFilters: state.columnFilters,
globalFilter: state.globalFilter,
pagination: state.pagination,
})}
>
{() => <SubscribedRows table={table} />}
</table.Subscribe>
function SubscribedRows({ table }) @{
<tbody>
@for (const row of table.getRowModel().rows; key row.id) {
<tr>...</tr>
}
</tbody>
}
也可以直接订阅单个原子并从中选取一个值:
<table.Subscribe
source={table.atoms.rowSelection}
selector={(rowSelection) => rowSelection[row.id]}
>
{(isSelected) => (
<input
type="checkbox"
checked={!!isSelected}
onClick={row.getToggleSelectedHandler()}
/>
)}
</table.Subscribe>
table.Subscribe 的实现见 Subscribe.tsrx:它本质上是把 useSelector(配合 shallow 比较)包进一个 Octane 组件,子节点可以是接收选中值的函数。useTable 返回的 table.Subscribe 已预绑定 table.store,所以可以省略 source。
更进阶的订阅模式需要理解哪些表格 API 依赖哪些状态切片:例如一个行模型可能同时依赖过滤、排序与分页,而一个行选择复选框只需要某一行的一个选择值。默认 selector 起步,在渲染成本真正吃紧处再用 selector 与 table.Subscribe 精细化。
设置表状态:API 优先,原子直写兜底
你几乎不应该直接设置表状态。 TanStack Table 的 feature 为操作自身状态暴露了专用 API,这些 API 是最安全的修改途径——因为它们会保持该功能自身的规则和相关联动更新。
例如,使用分页 API 而不是手动改分页状态:
table.nextPage()
table.previousPage()
table.setPageIndex(0)
table.setPageSize(25)
同样的思路适用于所有 feature:用 table.setSorting(...)、table.setColumnFilters(...)、column.toggleVisibility()、row.toggleSelected() 等 API,而不是手工编辑底层状态对象。
- 只想设置起始值 → 用
initialState; - 想把某个状态切片重置回初始值 → 用该 feature 的 reset API。
如果确实需要直接写某个内部自有状态切片,低层写入面是对应的 base atom:
table.baseAtoms.pagination.set((old) => ({
...old,
pageIndex: 0,
}))
直接写 base atom 应该很少见。如果某个切片由传入 atoms 的外部原子拥有,就应写入那个外部原子——此时 table.atoms.pagination 读取的是外部原子,而不是内部 base atom。这一点在 coreTablesFeature.types.ts 中有明确注释:优先级为 options.atoms[key] > options.state[key] > baseAtoms[key]。
自定义初始状态(initialState)
如果只是定制某些表状态的起始值,使用 initialState——你仍然不需要自己管理这些状态。
initialState 只作用于已注册的状态切片。它既用来创建表格的初始状态,也供 reset API(如 table.resetSorting()、table.resetPagination())使用。注意:之后修改 initialState 对象不会重置表状态。
const table = useTable({
features,
columns,
data,
initialState: {
sorting: [
{
id: 'age',
desc: true,
},
],
pagination: {
pageIndex: 0,
pageSize: 25,
},
},
})
[!NOTE] 不要在同一状态切片上同时提供多个所有权来源,除非你有意让其中一个胜出。对
pagination这类切片,建议从initialState.pagination、atoms.pagination、state.pagination中只选一个作为唯一事实来源。外部原子的优先级高于外部state;外部state会同步进表格的内部 base atom。
源码层面,constructTable.ts 中 initialState 的合并逻辑是:每个 feature 依次通过 feature.getInitialState?.(initialState) 贡献默认值,最终整体执行 cloneState(initialState),确保初始状态是独立副本、不会被后续修改污染。
重置到初始状态
feature 的 reset API 默认重置到 table.initialState。许多 reset API 还接受 true 参数,表示重置为该 feature 的空白/默认状态:
table.resetSorting()
table.resetPagination()
table.resetPagination(true)
切片级 reset API(如 resetPagination())通过该 feature 的状态更新器更新,因此可以更新外部拥有的原子。而核心的 table.reset() API 重置的是内部 base atoms,所以不要把它当作重置外部原子所拥有状态的主要手段。
受控状态:外部原子 vs 外部状态
如果需要在应用的其他部分方便地访问表状态,可以控制单个状态切片。v9 中推荐使用外部原子(external atoms),因为它保持了原子化状态模型,并让 Octane 只订阅它需要的切片。
外部原子(External Atoms)
当应用应该拥有一个或多个表状态切片时使用外部原子。用 TanStack Store 的 useCreateAtom 创建稳定的可写原子,通过表格的 atoms 选项传入,然后可以在应用任意位置用 useSelector 订阅它。
这在服务端数据获取场景下尤其有用:分页、排序或过滤经常要进入 query key,外部原子让应用与表格共享这些值,而无需把整个表状态都提升到 Octane 状态里:
import { useCreateAtom, useSelector } from '@tanstack/octane-store'
import { useEffect, useState } from 'octane'
import {
rowPaginationFeature,
tableFeatures,
useTable,
type PaginationState,
} from '@tanstack/octane-table'
const features = tableFeatures({
rowPaginationFeature,
// 无需 paginatedRowModel:手动服务端分页用不到它
})
function App() @{
const paginationAtom = useCreateAtom<PaginationState>({
pageIndex: 0,
pageSize: 10,
})
const pagination = useSelector(paginationAtom)
const [result, setResult] = useState({ rows: [], rowCount: 0 })
useEffect(() => {
let cancelled = false
fetchData(pagination).then((nextResult) => {
if (!cancelled) setResult(nextResult)
})
return () => {
cancelled = true
}
}, [pagination])
const table = useTable({
features,
columns,
data: result.rows,
rowCount: result.rowCount,
atoms: {
pagination: paginationAtom,
},
manualPagination: true,
})
// 表格分页 API 会直接更新 paginationAtom
}
使用 atoms 选项时,不需要再添加对应的 on[State]Change 选项。例如传了 atoms.pagination,表格分页 API 就会直接更新该原子。
外部状态(External State)
经典的 state + on[State]Change 模式仍然受支持。它便于简单集成或从 v8 代码迁移,但粒度不如外部原子精细——Octane 状态更新会重渲染拥有该状态的组件,且这种渲染无法像原子订阅那样通过把订阅放到树中更低位置来规避。
用外部状态控制切片时,需要同时传入状态值和对应回调:
const [sorting, setSorting] = useState<SortingState>([])
const [pagination, setPagination] = useState<PaginationState>({
pageIndex: 0,
pageSize: 10,
})
const table = useTable({
features,
columns,
data,
state: {
sorting,
pagination,
},
onSortingChange: setSorting,
onPaginationChange: setPagination,
})
v8 风格的 onStateChange(单个全局状态回调)在 v9 中已经移除,useTable 不再支持它。请使用与 state.<slice> 配对的逐切片 on[State]Change 回调,或通过 atoms 选项使用外部原子。如果你确实需要观察每一次状态变化,可以直接订阅 table.store。
渲染与提交时机(Render and Commit Timing)
在 Octane 渲染期间,useTable 会立即暂存最新的 options,因此同一渲染内的表格读取看到的是最新数据、列、回调和受控状态;但它不会在组件渲染过程中把受控状态发布到 table.store。
Octane 接受渲染后,一个 layout effect 会把该快照标记为已提交,并发布捕获到的受控状态。被挂起或放弃的渲染因此不会泄漏推测性状态:owner 组件会丢弃匹配的提交后通知(因为它已经渲染过该快照),而独立挂载的 table.Subscribe 消费者仍然会在绘制(paint)前收到更新。
这段行为对应 useTable.tsrx 中的实现:renderSnapshot 取自渲染阶段源,useLayoutEffect 中调用 rootSource.markCommitted(renderSnapshot) 与 table_publishExternalState(...);其提交基线语义在 renderPhaseReactivity.ts 中实现——只有 markCommitted() 会推进提交基线,未提交的快照不会改变通知行为。
该提交行为只适用于受控的 state 选项。外部原子始终是直接的事实来源,表格 API 对它们的写入是同步的。
on[State]Change 回调
当通过 state 选项控制对应切片时,on[State]Change 回调非常有用。它们的工作方式与 Octane 状态 setter 一致:updater 可以是原始值,也可以是接收旧值并返回新值的函数。
如果提供了 on[State]Change 回调,就同时要在 state 中提供对应值。例如 onSortingChange 应与 state.sorting 配对:
const [sorting, setSorting] = useState<SortingState>([])
const table = useTable({
features,
columns,
data,
state: {
sorting,
},
onSortingChange: setSorting,
})
如果需要在回调中追加逻辑,请先判断传入的 updater 是函数还是值:
const [pagination, setPagination] = useState<PaginationState>({
pageIndex: 0,
pageSize: 10,
})
const table = useTable({
features,
columns,
data,
state: {
pagination,
},
onPaginationChange: (updater) => {
setPagination((old) => {
const next = updater instanceof Function ? updater(old) : updater
// 副作用或校验可以写在这里
return next
})
},
})
状态类型:让 TypeScript 为状态护航
TanStack Table 中大多数复杂状态都有自己的 TypeScript 类型,可以直接导入使用。这对 Octane 状态、外部原子以及操作表状态的辅助函数都非常有用:
import {
useTable,
type PaginationState,
type RowSelectionState,
type SortingState,
type TableState,
} from '@tanstack/octane-table'
const [sorting, setSorting] = useState<SortingState>([
{
id: 'age',
desc: true,
},
])
TableState<typeof features> 会根据该表格注册的 features 推断:
const features = tableFeatures({
rowPaginationFeature,
rowSortingFeature,
})
type MyTableState = TableState<typeof features>
当为单个切片创建局部状态或外部原子时,优先使用功能专属状态类型,如 SortingState、PaginationState 或 RowSelectionState——它们比完整的 TableState 更精确、更便于复用。
从示例快速上手
如果想直接看可运行的实现,仓库提供了与本指南一一对应的示例:
- basic-use-table:最基础的
useTable用法(默认 selector(state) => state),见 main.tsrx,可对照了解features、columns、data与渲染骨架; - basic-external-atoms:外部原子受控分页;
- basic-external-state:经典
state+on[State]Change受控模式; - basic-subscribe:
table.Subscribe局部订阅。
小结:先默认,再优化,最后才接管
TanStack Table v9 的表状态管理可以概括为三个递进层次:
- 默认内部管理——什么都不传,表格自己管好自己;
- 读取与订阅——用
table.atoms.x.get()/table.store.state取值,用useTable的 selector 或table.Subscribe控制重渲染粒度; - 受控接管——外部原子(
atoms选项,推荐)或外部状态(state+on[State]Change,兼容 v8 迁移)按需接管切片。
无论处于哪一层,initialState 都只负责起始值,feature API 始终是修改状态的首选入口,baseAtoms 直写是极少使用的兜底。理解这四类状态表面(baseAtoms / atoms / store / state)以及它们之间的优先级与同步规则,你就能在保持表格高性能的前提下,把状态精确地放在它该在的地方。