用途:本技能建立在 table-core 与入门内容之上,讲解如何在 Preact 中读取与掌控 TanStack Table v9 的表状态。Preact 的选择模式类似 React,但导入与 store 绑定须保持 Preact 原生。
状态模型:TanStack Table 本质是状态协调器,状态默认应保持内部,除非其他子系统需要读取、持久化或驱动它。没有 initialState、atoms、state 或 on[State]Change 时,表格拥有全部已注册状态切片。table.baseAtoms 是由解析后初始状态初始化的内部可写 atom;table.atoms 是各切片当前所有者的只读派生 atom;table.store 是由这些 atom 组成的只读扁平 store;table.state 仅包含 useTable 第二个选择器的结果。只有已注册特性才贡献状态与类型,若分页 API 缺失应添加 rowPaginationFeature,而不是绕过缺失 API 强制转型。features、data、columns 应在多次渲染间保持稳定。
设置:useTable 接收选项与选择器,选择器决定重渲染与 table.state 的形状,省略则选择全部已注册切片。
核心模式:可用 table.Subscribe 配合 source 做细粒度订阅,例如订阅 rowSelection 并渲染选中数量。外部 atom 归属可用 @tanstack/preact-store 的 useCreateAtom 创建状态,再通过 atoms 传入 useTable。
状态归属选择:每个切片只用一个所有者。状态是表格局部时优先内部状态与特性 API;用 initialState 提供起始或重置值,之后再改它不会重置当前状态;需要共享时优先用稳定的 preact-store atom 放入 atoms,且不要再配 on[State]Change;简单受控状态用 state.<slice> 配合对应回调,需回填下一个值并处理值或更新函数语义。外部 atoms 优先于外部 state,外部 state 会同步进内部基础 atom,不要故意使用两个所有者。v8 的全局 onStateChange 已移除,应逐个控制切片或订阅 table.store。
初始化、更新与重置:写入优先用特性方法(setSorting、nextPage、toggleVisibility、toggleSelected)。仅在罕见低层场景才写 baseAtoms;若外部 atom 拥有该切片则写外部 atom。resetSorting、resetPagination 可重置切片,resetPagination(true) 重置为特性默认值。切片重置可能更新外部所有者,核心 table.reset() 只重置内部基础 atom。类型上单切片可 import PaginationState,需要完整推断状态时用 TableState<typeof features>。
常见错误:把快照当订阅读取错误,应从 table.state 读取,store 与 atom 的 .get() 只是快照;只控制回调而不提供受控值错误,回调必须写入该切片的受控值;渲染依赖被选择器裁掉错误,若渲染输出依赖选择状态,拥有该渲染边界的组件必须直接订阅它或通过 Subscribe 订阅。
API 发现:可查看 node_modules/@tanstack/preact-table/dist/useTable.d.ts 与 Subscribe.d.ts,并使用 @tanstack/preact-store 而非 React Store hooks。