Preact Table 的 SubscribePropsWithSourceWithSelector 类型详解原子订阅与选择器投影实战【免费下载链接】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中一个关键类型别名SubscribePropsWithSourceWithSelector。它定义在 Subscribe.ts是Subscribe组件与table.Subscribe高阶组件的核心 props 类型用于实现订阅某个原子atom或 store并通过 selector 投影出需要的值仅在投影值变化时触发局部重渲染的精确渲染模式。读完本文你将掌握该类型的三要素source/selector/children、其与全量 store 订阅及恒等订阅两类变体的区别并能结合源码与官方示例写出可复用的细粒度订阅代码。类型定义从文档到源码SubscribePropsWithSourceWithSelector的官方类型别名定义如下type SubscribePropsWithSourceWithSelectorTSourceValue, TSelected { source: SubscribeSourceTSourceValue selector: (state: TSourceValue) TSelected children: ((state: TSelected) ComponentChildren) | ComponentChildren }该类型接收两个泛型参数TSourceValue所订阅source携带的值类型。它可以是某个表的 state 切片如RowSelectionState、PaginationState也可以是table.optionsStore的完整 options 值。TSelectedselector投影projection后的返回值类型也是children渲染函数接收的参数类型。它通常比TSourceValue更窄、更具体。类型别名在文档中的说明是Subscribe to a projected value from a source (atom or store)——即订阅来自某个数据源原子或 store的投影值这正是该类型区别于其他订阅变体的定位所在。三个属性的职责与类型约束source: SubscribeSourceTSourceValuesource指定要订阅的数据源。其类型SubscribeSourceTValue在 Subscribe.ts 中定义为以下四种的联合export type SubscribeSourceTValue | AtomTValue | ReadonlyAtomTValue | StoreTValue | ReadonlyStoreTValue这些类型均来自tanstack/preact-storeTanStack Store。在表实例上最常见的两个来源是table.store由所有已注册 state 切片table.atoms合成的只读扁平 store其值为完整TableStatetable.atoms.slice按功能特性注册的只读派生原子例如table.atoms.rowSelection、table.atoms.pagination、table.atoms.globalFilter。需要特别注意的是在 v9 中state 切片只对注册进features的功能存在见 table-state.md 的 Feature-based State 一节。例如只有注册了rowSelectionFeaturetable.atoms.rowSelection才可用未注册的功能对应原子在类型层面即不可访问。selector: (state: TSourceValue) TSelectedselector是从完整数据源值中投影出子集的纯函数。其核心作用有二收窄渲染范围组件只对selector返回值的变化敏感而非整个 source 的变化提供类型收窄TSelected通常比TSourceValue更精确让children渲染函数获得更好的类型推导。selector在该类型中是必填项这与恒等订阅变体SubscribePropsWithSourceIdentityTSourceValue形成对比——后者把selector声明为selector?: undefined省略selector等价于使用恒等函数children直接收到TSourceValue本身。两者在 Subscribe.ts 中被联合为SubscribePropsWithSourceTSourceValue, TSelected TSourceValueexport type SubscribePropsWithSourceTSourceValue, TSelected TSourceValue | SubscribePropsWithSourceIdentityTSourceValue | SubscribePropsWithSourceWithSelectorTSourceValue, TSelectedchildren: ((state: TSelected) ComponentChildren) | ComponentChildrenchildren可以是渲染函数或静态内容渲染函数形式(state: TSelected) ComponentChildren订阅值变化时以新的投影值调用它实现局部重渲染静态内容形式直接传入ComponentChildren不依赖订阅值渲染。这里ComponentChildren来自preact类型表示 Preact 的任意可渲染子节点元素、文本、数组等。与全量 store 订阅变体的边界除了SubscribePropsWithSource*系列还有专门用于整表状态订阅的SubscribePropsWithStoreTFeatures, TSelectedSubscribe.ts。它的特点是source被固定为SubscribeSourceTableStateTFeatures即完整表状态selector同样必填官方注释明确说明这是有意为之store 模式下必须显式投影以免你无意中订阅整个 store 而不做任何投影。而SubscribeProps顶层联合类型Subscribe.ts把这三种形态合在一起构成Subscribe组件 props 的完整类型面export type SubscribeProps TFeatures extends TableFeatures, TSelected unknown, TSourceValue unknown, | SubscribePropsWithStoreTFeatures, TSelected | SubscribePropsWithSourceIdentityTSourceValue | SubscribePropsWithSourceWithSelectorTSourceValue, TSelected可以这样理解三者的分工store 模式订阅整表状态并投影source selector 模式本文主题订阅单一原子/store 并投影source 恒等模式订阅单一原子/store 而不投影。底层实现useSelector 与浅比较SubscribePropsWithSourceWithSelector的运行时行为由Subscribe组件实现支撑。在 Subscribe.ts 中组件对三种 props 形态分别提供函数重载最终实现如下export function Subscribe TFeatures extends TableFeatures, TSelected, TSourceValue, ( 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(source, selector, { compare: shallow })来自tanstack/preact-store的订阅 hook。组件挂载时订阅props.sourceselector负责投影**浅比较shallow compare**决定投影结果是否变化从而决定是否触发 Preact 重渲染。这解释了为何示例中常投影出对象字面量如{ rowSelection }浅比较意味着只有被投影字段的引用变化才会触发更新。children 分派children为函数时以selected为参数调用否则直接返回静态内容。重载设计SubscribePropsWithSourceWithSelector作为中间重载出现Subscribe.ts确保带selector的 source 订阅在 JSX 中能获得正确的上下文类型推导。table.Subscribe绑定 store 默认值的便捷入口在实际业务代码中你更常接触的是table.Subscribe。useTable在 useTable.ts 中把独立Subscribe组件绑定到表实例上tableInstance.Subscribe ((props: any) { return Subscribe({ ...props, source: props.source ?? tableInstance.store, }) }) as PreactTableTFeatures, TData, TSelected[Subscribe]也就是说省略source时默认订阅table.store即 store 模式显式传入source原子或外部 store时即走 source 模式——此时SubscribePropsWithSourceWithSelector便派上用场。table.Subscribe的类型重载useTable.ts与独立组件保持一致source无selector时按恒等订阅推导出TSourceValue带selector时按投影结果推导出TSubSelected。官方注释建议在useTable之后优先使用table.Subscribe因为它基于重载JSX 上下文类型推导更友好独立Subscribe组件则使用联合 props 类型适合没有表实例在作用域内如仅持有table.store的场景。实战示例行选择原子的细粒度订阅官方示例 basic-subscribe 完整演示了该类型的典型用法。示例在useTable中通过第二个参数() null声明默认不订阅任何表状态把渲染控制权完全交给table.Subscribe实现百万行压力测试下仍可接受的渲染性能const table useTable( { key: basic-subscribe, features, atoms: { rowSelection: rowSelectionAtom }, columns, data, getRowId: (row) row.id, enableRowSelection: true, }, () null, // 默认不订阅任何表状态用 table.Subscribe 做定点更新 )场景一source selector 投影行级选中值。每行复选框只订阅table.atoms.rowSelection再用selector投影到该行的选中状态使勾选一行只重渲染那一行的复选框Subscribe source{table.atoms.rowSelection} selector{(rowSelection) rowSelection[row.id]} {(isRowSelected) ( IndeterminateCheckbox checked{!!isRowSelected} disabled{!row.getCanSelect()} indeterminate{row.getIsSomeSelected()} onClick{row.getToggleSelectedHandler()} / )} /Subscribe注意这里的selector参数类型是RowSelectionState即TSourceValue返回boolean | undefined即TSelected完美对应SubscribePropsWithSourceWithSelectorRowSelectionState, boolean。场景二store 模式投影多个切片。表头全选复选框需要同时感知列过滤、全局过滤与行选择状态因此省略source默认订阅table.store用selector投影出需要的切片组合Subscribe selector{(state) ({ columnFilters: state.columnFilters, globalFilter: state.globalFilter, rowSelection: state.rowSelection, })} {() ( IndeterminateCheckbox checked{table.getIsAllRowsSelected()} indeterminate{table.getIsSomeRowsSelected()} onChange{table.getToggleAllRowsSelectedHandler()} / )} /Subscribe场景三source 恒等订阅。当只需要完整原子值本身时省略selector即可此时命中SubscribePropsWithSourceIdentity如table.atoms.rowSelection直接渲染已选行数table.Subscribe source{table.atoms.rowSelection} {(rowSelection) ( div {Object.keys(rowSelection).length.toLocaleString()} rows selected /div )} /table.Subscribe示例代码中的注释还给出了重要的使用建议仅在遇到具体的性能问题时才推荐使用这些模式——细粒度订阅会放大对 state 依赖关系的理解成本常规场景下使用table.state或默认订阅即可。总结SubscribePropsWithSourceWithSelector是 TanStack Table Preact 细粒度渲染优化的类型基石。它通过三个紧密配合的属性——订阅源source、投影函数selector、渲染回调children——把哪里需要重渲染的控制权精确交到开发者手中。理解它也就理解了table.Subscribe全系 API恒等订阅、投影订阅、store 投影订阅三种形态的分工以及useSelector浅比较在其中的作用。想要继续深入可以通读 Subscribe.ts 源码、useTable.ts 中Subscribe的类型重载以及 Table State (Preact) Guide 中关于原子与 store 的完整说明。【免费下载链接】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），仅供参考