SuperAPI AI 工具集

tanstack-lit-table-table-state

前端与建站

查看项目

更新于 10-16 00:02

技能介绍

该技能建立在 @tanstack/table-core 与本包入门技能之上,聚焦 TanStack Table 的状态协调模型。核心观点:表格本质是状态协调器,除非其他子系统需要读取、持久化或驱动状态,否则应保持状态内部化。table.baseAtoms 是从解析后的初始状态初始化的内部可写 atom;table.atoms 是各注册切片当前所有者的只读派生 atom;table.store 将它们合并为一个只读扁平 store;table.state 仅是 controller.table 第二个参数所选出的值。TableController 订阅 state/options 并请求宿主更新。状态按功能划分:若 options、atoms 或类型中缺少分页,需注册 rowPaginationFeature。features、columns、data 引用应在 render() 调用间保持稳定,不要在 controller.table 选项中内联创建数组或派生行。

用法上,通过 controller.table(options, selector) 定义 table.state 形状,选择器复用时保持稳定;用 table.atoms.pagination.get() 在事件处理器中读取当前切片;需要模板区域响应式更新时,用 table.subscribe(table.store, selector, render) 创建窄响应式孤岛,并保持选择器引用稳定。

状态所有权每个切片只能有一个所有者:优先内部状态与功能 API;initialState 用于起始/重置值,之后修改不会重置当前状态;共享状态优先用稳定的外部 TanStack Store atom,功能 API 会直接写入,此时省略 on[State]Change;简单受控状态用 state.<slice> 响应式宿主属性加匹配回调,需把原始值与解析后的 updater 函数都写回属性。外部 atom 优先于外部 state,后者同步进内部 base atom,不要配置多个所有者。全局 v8 onStateChange 已移除,需观察全部状态变化时订阅 table.store。

初始化、更新与重置优先使用 setSorting、nextPage、toggleVisibility、toggleSelected 等功能方法;直接写 baseAtoms 是内部状态的罕见逃生舱。table.resetSorting()、table.resetPagination()、table.resetPagination(true) 等功能重置默认使用 table.initialState,传 true 则请求功能默认值并可更新外部所有者;核心 table.reset() 只重置内部 base atom。

常见错误:提供 onPaginationChange 却省略 state.pagination 会冻结受控状态;把 store 快照缓存到 render 外并期望其变化是误把快照当订阅;在渲染树中创建不稳定选择器闭包会破坏更新门控。API 发现可查看 node_modules/@tanstack/lit-table/dist/TableController.d.ts 与 table-core 的 table 目录。