Preact 表格 Store 订阅模式深入解析SubscribePropsWithStore类型【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/table在 TanStack Table 的 Preact 适配器tanstack/preact-table中SubscribePropsWithStore是订阅完整表格状态full table state这一核心场景的类型契约。它定义了以table.store为数据源、以显式selector投影状态、并以children渲染函数消费选中值的完整 props 结构是构建精细化响应式表格 UI如行选择、分页、过滤等高性能交互的关键类型之一。读完本文你将掌握SubscribePropsWithStore的三个属性source/selector/children各自的作用与约束它与SubscribePropsWithSource系列类型的区别以及它在useTable与Subscribe组件中的真实调用方式与性能优化实践。类型定义速览SubscribePropsWithStore定义在 packages/preact-table/src/Subscribe.ts声明如下type SubscribePropsWithStore TFeatures extends TableFeatures, TSelected, { source: SubscribeSourceTableStateTFeatures selector: (state: TableStateTFeatures) TSelected children: ((state: TSelected) ComponentChildren) | ComponentChildren }对应生成的 API 文档位于 docs/framework/preact/reference/type-aliases/SubscribePropsWithStore.md。类型参数类型参数约束含义TFeaturesextends TableFeatures当前表格启用的功能集features如行选择、分页、过滤等用于推导TableState的具体形状TSelected无selector投影返回的选中值类型决定children渲染函数收到的参数类型三个必填属性属性类型说明sourceSubscribeSourceTableStateTFeatures订阅的数据源固定为完整表格状态table.storeselector(state) TSelected从完整TableState中投影出所需切片选中值变化浅比较时触发重渲染children((state) ComponentChildren) \| ComponentChildren渲染子内容传函数时接收selector的返回值也可直接传静态 JSX属性语义详解source完整表格状态订阅源source的类型是SubscribeSourceTableStateTFeatures。SubscribeSourceTValue是一个联合类型定义见 Subscribe.ts:11 及 SubscribeSource.mdtype SubscribeSourceTValue | AtomTValue | ReadonlyAtomTValue | StoreTValue | ReadonlyStoreTValue在 store 模式下source传入的是table.store——这是由 TanStack Store 支撑的、保存完整TableState的响应式 store。table.store.state是当前值的快照useTable.ts:35中有明确注释警告其只读快照、非响应式订阅入口而正确的订阅方式正是通过本类型描述的Subscribe组件或useSelector(table.store, selector)。selector强制显式投影防止误订阅整个 storeselector: (state: TableStateTFeatures) TSelected接收完整的TableState并返回任意投影值。在 store 模式下selector是必填的源码注释给出了设计意图Subscribe.ts:27-29Required in store mode so you never accidentally subscribe to the whole store without an explicit projection.也就是说直接订阅table.store而不做投影会让组件在任何状态变化时都重渲染。显式selector强制开发者声明关心的状态切片配合源码中useSelector传入的{ compare: shallow }浅比较Subscribe.ts:114-120只有当选中值的浅比较结果发生变化时才触发重渲染。children函数式渲染子children支持两种形式函数(state: TSelected) ComponentChildren接收selector选中的值。这是最常用的形式组件内部会以props.children(selected)方式调用Subscribe.ts:122-124。静态 JSX直接传入ComponentChildren此时不消费选中值。与SubscribePropsWithSource系列的分工SubscribePropsWithStore只是SubscribeProps联合类型的一个分支Subscribe.ts:61-68type SubscribePropsTFeatures, TSelected, TSourceValue | SubscribePropsWithStoreTFeatures, TSelected | SubscribePropsWithSourceIdentityTSourceValue | SubscribePropsWithSourceWithSelectorTSourceValue, TSelected三条分支的定位差异详见 SubscribeProps.md 与 SubscribePropsWithSource.md分支类型source 类型selector适用场景SubscribePropsWithStoretable.store完整状态必填一次性订阅多个状态切片或需要组合状态SubscribePropsWithSourceIdentity单个 atom / store省略恒等投影订阅某个完整值如table.atoms.rowSelectionSubscribePropsWithSourceWithSelector单个 atom / store可选从单一数据源投影出更细的值在useTable与Subscribe中的实际用法方式一table.Subscribe推荐useTable在创建表格实例时把Subscribe绑定到实例上useTable.ts:140-145未传source时自动回退到tableInstance.storetableInstance.Subscribe ((props: any) { return Subscribe({ ...props, source: props.source ?? tableInstance.store, }) }) as PreactTableTFeatures, TData, TSelected[Subscribe]table.Subscribe的签名在useTable.ts中通过重载overload实现useTable.ts:43-79让 JSX 上下文类型推断在两种模式下都正确工作。因此在组件中优先使用table.Subscribe——它在不传source时等价于SubscribePropsWithStore缺省 source 指向table.store传source时等价于 source 系列类型。典型用法来自 examples/preact/basic-subscribe/src/main.tsx 的完整可运行示例// 订阅完整 store投影出多个状态切片表头全选按钮 table.Subscribe selector{(state) ({ columnFilters: state.columnFilters, globalFilter: state.globalFilter, rowSelection: state.rowSelection, })} {() ( IndeterminateCheckbox checked{table.getIsAllRowsSelected()} indeterminate{table.getIsSomeRowsSelected()} onChange{table.getToggleAllRowsSelectedHandler()} / )} /table.Subscribe // 仅订阅 rowSelection atom且只投影当前行的选中值 table.Subscribe source{table.atoms.rowSelection} selector{(s) s?.[row.id]} {(isRowSelected) ( input typecheckbox checked{!!isRowSelected} / )} /table.Subscribe方式二独立Subscribe组件当table不在作用域内时可以直接从tanstack/preact-table导入Subscribe组件并显式传入source{table.store}Subscribe.ts:76-96 的官方示例import { Subscribe } from tanstack/preact-table Subscribe source{table.store} selector{(state) ({ rowSelection: state.rowSelection })} {({ rowSelection }) ( divSelected rows: {Object.keys(rowSelection).length}/div )} /Subscribe需要注意独立组件使用联合props类型而table.Subscribe采用重载签名以获得更好的 JSX 上下文类型推断源码注释明确指出这一点见 Subscribe.ts:72-74。因此在 JSX 中使用table.Subscribe是官方推荐路径独立Subscribe组件适合脱离表格实例的通用订阅场景。源码实现Subscribe组件如何工作Subscribe组件的完整实现只有寥寥几行Subscribe.ts:98-125核心依赖tanstack/preact-store的useSelectorexport function Subscribe(props: SubscribePropsTFeatures, TSelected, TSourceValue): ComponentChildren { const selected useSelector( props.source as never, props.selector as Parameterstypeof useSelector[1], { compare: shallow }, ) as TSelected return typeof props.children function ? (props.children as (state: TSelected) ComponentChildren)(selected) : props.children }关键点订阅useSelector对sourceatom 或 store建立响应式订阅浅比较compare: shallow决定何时重渲染——只有selector选中的值在浅比较下变化才触发渲染children是函数则调用并传入selected否则原样渲染。性能优化实践订阅隔离官方示例的注释basic-subscribe/src/main.tsx明确指出Subscribe/table.Subscribe是更高阶的订阅组件用来把重渲染精确限制在 Preact 组件树中需要更新的局部位置仅在遇到具体性能问题时才推荐使用。实践要点总结默认零订阅useTable(tableOptions, () null)传入空投影默认不订阅任何状态再用table.Subscribe按需订阅示例第 154 行的做法原子级订阅订阅table.atoms.rowSelection等单个 atom再投影到行级值如s?.[row.id]使勾选一行只重渲染该行组合切片订阅订阅完整 store 时用selector显式声明所需切片避免无谓的全量重渲染验证时机官方示例注释提醒要小心测试并验证它在预期时刻才重渲染main.tsx:66。该模式在仓库测试中也有充分验证packages/preact-table/tests/unit/rendering.test.tsxdescribe(table.Subscribe)验证了订阅后状态更新的渲染行为packages/preact-table/tests/unit/adapterReactivity.test.tsx验证了Subscribe两种 source 重载的桥接以及每个被选依赖各自隔离渲染周期的测试用例isolates Subscribe render cycles to each selected dependencypackages/preact-table/tests/unit/useTable.test.tsx则覆盖了table.Subscribe订阅分页状态的场景。小结SubscribePropsWithStore是 TanStack Table Preact 适配器中订阅完整表格状态场景的类型骨架source固定指向table.storeselector强制显式投影浅比较决定重渲染时机children消费选中值完成局部渲染。理解它是掌握tanstack/preact-table精细化响应式订阅、构建高性能表格交互的第一步。实际开发中优先通过table.Subscribe缺省 source 即 store 模式获得最佳类型推断需要脱离表格实例时再使用独立的Subscribe组件。 /output文章【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/table创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考