SuperAPI AI 工具集

tanstack-svelte-table-table-state

前端与建站

查看项目

更新于 10-16 00:02

技能介绍

用途:在 @tanstack/table-core 与入门技能基础上,讲解 TanStack Table 在 Svelte 5 中的状态协调方式。核心心智模型是:Table 主要是状态协调器,除非其他系统需要读取、持久化或驱动状态,否则保持状态内部化。未提供 initialState、atoms、state 或 on[State]Change 时,表格拥有全部已注册切片。table.baseAtoms 是内部可写 atom,table.atoms 是只读派生 atom,table.store 是只读扁平 store。Svelte 适配器把 TanStack Store 的依赖追踪桥接到 rune:在模板、$derived、$derived.by 或 $effect 中调用 table.atoms.<slice>.get()、table.store.get() 及表格 API 会变为响应式,其他上下文只返回当前快照。只有注册的功能才创建状态与类型,缺少分页应注册 rowPaginationFeature,不要强转或加临时字段;功能与列保持稳定,变化的数据通过 getter 传入。

主要能力与用法:读取状态时优先用窄读取,如 const pagination = $derived(table.atoms.pagination.get()),table.store.get() 会因任意已注册状态变化而重跑,仅用于调试、持久化或需要完整状态的计算。受控切片使用 value-or-updater 语义,传入 getter 支持的 state.pagination 与 onPaginationChange。createTableState 可减少样板代码,返回读取函数与 setter,setter 可直接传给 onPaginationChange。每个切片只能有一个所有者:内部状态加功能 API、initialState(仅作起始/重置值)、Svelte $state 加回调、或 atoms 中的稳定外部 atom(不要再加回调)。外部 atom 优先于受控状态,受控状态同步进内部 base atom。全局 v8 onStateChange 已移除,需观察所有变化时订阅 table.store。表格外消费原始外部 atom 用 @tanstack/svelte-store 的 useSelector,表格 UI 内用 rune 感知的 table.atoms.<slice>.get()。

初始化、更新与重置:优先使用 setSorting、nextPage、toggleVisibility、toggleSelected 等功能 API,而非直接写状态;仅在罕见内部状态需求时写 base atom,atoms.<slice> 拥有时写外部 atom。功能重置默认用 table.initialState,传 true 请求功能默认值并可流向外部所有者;核心 table.reset() 只重置内部 base atom。

限制与常见错误:v9 中 createTable 与 createAppTable 只接受 options,table.state 不存在,subscribeTable 与 SubscribeSource 不再导出,应使用原生 Svelte 追踪读取与 $derived 投影。受控切片若未把每次更新写回所属 rune 会被冻结。在追踪上下文外读取只是快照。同一切片不要声明两个所有者。客户端行模型变化默认重置页码,需要时用 autoResetPageIndex: false 关闭。API 细节可查看 node_modules/@tanstack/svelte-table/dist 下的类型声明文件与对应核心功能源码。