前端UI组件【免费下载链接】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点击查看免费下载导读SubscribeDirective是 TanStack Table Lit 适配器tanstack/lit-table中用于实现模板片段级精准重渲染的核心异步指令。它订阅一个tanstack/lit-store的 Store 或 Atom当状态变化时只重渲染它包裹的那一小段模板而不是让整个 Lit 组件以及整张表格参与更新。读完本文你将掌握SubscribeDirective的完整类型签名、生命周期行为、fakeReactiveControllerHost桥接原理以及如何通过subscribe()/table.subscribe()在真实表格中实现过滤输入、分页控件、行选择复选框等区域的独立更新。一、SubscribeDirective 是什么按 SubscribeDirective 文档 的定义SubscribeDirective是一个异步 Lit 指令AsyncDirective它订阅一个tanstack/lit-store的 sourceStore 或 Atom状态变化时只为它包裹的模板部分触发重渲染与宿主组件或其他模板区域隔离使用一个 fake伪造的ReactiveControllerHost来弥合 TanStack 标准控制器TanStackStoreSelector的生命周期要求与AsyncDirective生命周期之间的差异。类定义位于 packages/lit-table/src/subscribe-directive.ts:43继承自AsyncDirective来自lit/async-directive.js。其核心价值在于在 TanStack Table 这样一个高频状态变更的场景中把状态变化 → 整组件重渲染的粗粒度更新细化成状态变化 → 仅更新依赖该状态的那块 DOM。二、类型体系SelectionSource、Selector 与 TemplateFunction要正确使用SubscribeDirective先理解它的三个基础类型源码见 subscribe-directive.ts:13-28SelectionSourceTValue可订阅源export type SelectionSourceTValue | AtomTValue | ReadonlyAtomTValue | StoreTValue | ReadonlyStoreTValue即指令接受tanstack/lit-store的四种来源可写 Atom、只读 Atom、可写 Store、只读 Store。这意味着你既可以订阅整张表格的table.store其状态为完整的TableState也可以订阅任意一个状态切片 atom如table.atoms.rowSelection甚至是你自己通过createAtom创建的外部 atom。对应类型别名文档见 SelectionSource。SelectorTSource, TSelected选择器type SelectorTSource, TSelected (state: TSource) TSelected一个从完整状态中提取/派生相关切片的纯函数。例如(state) state.pagination只取分页切片(rowSelection) rowSelection[row.id]只取某一行是否被选中。TemplateFunctionTSelected渲染函数type TemplateFunctionTSelected (value: TSelected) unknown接收被选中状态、返回要渲染的内容通常是 Lit 的TemplateResult的函数。它是订阅结果 → DOM 输出的桥梁。此外源码 subscribe-directive.ts:35 定义了一个恒等选择器identitySelector T(state: T): T state用于无选择器、订阅整个状态的场景保证内部逻辑统一走选择器 → 模板这条路径。三、render 的两种调用重载render()提供两个重载定义于 subscribe-directive.ts:61-76分别对应全量订阅与切片订阅两种用法重载一订阅完整状态renderTSource( source: SelectionSourceTSource, template: TemplateFunctionTSource, ): unknown只传source与template不经过选择器状态任意部分变化都会触发该模板片段重渲染。适合展示整个状态如调试面板的 JSON 输出。重载二订阅状态切片renderTSource, TSelected( source: SelectionSourceTSource, selector: SelectorTSource, TSelected, template: TemplateFunctionTSelected, ): unknown通过selector提取相关切片只有当该切片变化时才重渲染模板其他部分状态的变化不会波及该片段。这是细粒度渲染的主力形式。需要注意两个重载的render()方法体实际上只是return noChangesubscribe-directive.ts:78-85真正的渲染逻辑在update()中完成——注释明确指出实际渲染在 update 中处理以确保 template 只在必要时才被求值。四、update()订阅去重与模板闭包更新update()subscribe-directive.ts:87-144是SubscribeDirective的调度中枢其核心逻辑分四步参数归一化通过template undefined判断是否为恒等订阅即重载一从而决定哪个参数是选择器、哪个是模板。订阅条件判断比较this.latestSource ! source与this.latestSelector ! selector并结合this.initialized标志决定是否需要重建订阅shouldReinitialize。这样当宿主组件因无关原因重渲染、而 source 与 selector 均未变化时不会重建底层控制器。模板闭包始终更新源码注释说明了关键设计——模板闭包在每次宿主渲染时都会被重建并捕获外层渲染作用域表格包装器、行模型等的值因此指令总是采用最新的resolvedTemplate。若保留旧闭包订阅驱动的更新会持续用上一次渲染捕获的旧值渲染造成数据滞后。触发宿主更新并渲染当需要重建时先hostDisconnected()清理旧控制器再创建新的TanStackStoreSelector最后调用controller.hostUpdate()建立订阅并输出当前值。无论是否重建update()最后都会返回this.resolvedTemplate?.(this.latestSelector!(this.latestSource!.get()))即用最新选择器读取当前状态并渲染——这保证即使在无状态变更通知的宿主更新如行模型收到新数据下片段也能拿到新鲜输入。五、生命周期disconnected 与 reconnectedSubscribeDirective重写了AsyncDirective的两个连接生命周期方法disconnected()subscribe-directive.ts:147-149指令被从 DOM 移除时调用this.controller?.hostDisconnected()清理控制器订阅避免内存泄漏与悬挂回调。reconnected()subscribe-directive.ts:152-157指令被重新挂载到 DOM 时调用this.controller?.hostUpdate()恢复订阅若已有已解析模板则通过this.setValue(...)立即把最新选中状态写回片段保证重挂载后内容即时正确。其余成员构造函数、isConnected属性、_$isConnected访问器、_$initialize()、setValue()均继承自AsyncDirective其中setValue()用于在指令正常update/render生命周期之外设置片段值是订阅回调驱动重渲染的关键机制注意不能同步地在update或render内调用。六、核心设计fake ReactiveControllerHost 桥接SubscribeDirective最有技术含量的部分是它如何把 TanStack 的控制器体系接入 Lit 的异步指令体系。TanStackStoreSelector本是为ReactiveControllerHost宿主组件设计的控制器而指令没有宿主。解决办法是造一个假的宿主createFakeHost()subscribe-directive.ts:163-176返回一个最小ReactiveControllerHost实现return { addController: () {}, removeController: () {}, requestUpdate: () { if (this.resolvedTemplate this.controller) { this.setValue(this.resolvedTemplate(this.controller.value)) } }, get updateComplete() { return Promise.resolve(true) }, }要点addController/removeController为空操作——控制器注册对指令无实际意义requestUpdate是订阅回调的落点当 store/atom 状态变化时TanStackStoreSelector触发宿主requestUpdate()假宿主随即读取controller.value中最新的选中状态交给resolvedTemplate渲染并通过setValue()写入指令片段从而只更新这一小段 DOMupdateComplete立即 resolve保证需要等待更新完成的外部代码不会阻塞。通过这个桥接TanStackStoreSelector的完整生命周期订阅、通知、卸载被无缝移植到AsyncDirective上这也是文档注释所说的fake ReactiveControllerHost 弥合两者差距的源码级印证。七、订阅入口subscribe() 与 table.subscribe()独立的 subscribe() 指令subscribe是SubscribeDirective的指令工厂subscribe-directive.ts:191通过directive(SubscribeDirective)创建并带有与render()对应的两个重载签名。其标准用法示例出自 subscribe 变量文档// 无选择器订阅整个状态 htmldiv${subscribe(myStore, (state) htmlspan${state.count}/span)}/div // 有选择器仅当 count 变化时更新 htmldiv${subscribe(myStore, state state.count, (count) htmlspan${count}/span)}/div表格上的 table.subscribe()在TableController.table()返回的LitTable实例上subscribe被直接暴露为table.subscribe见 TableController.ts:222-229并可与表格配套的table.store、table.atoms.*或外部 atom 组合使用。配套的模式是给TableController.table()传() null选择器让宿主本身退出状态驱动的重渲染把颗粒度完全交给各table.subscribe片段TableController.ts:212-220 的注释明确说明门控让() ({})这类选择器把宿主完全排除在状态驱动更新之外将细粒度响应性推入 table.subscribe 岛。完整实战示例仓库中的 examples/lit/basic-subscribe/src/main.ts 是一个完整的可运行示例对应 React 侧的basic-subscribe覆盖三种订阅形态1. 表格 store 选择器全局过滤输入框仅过滤值变化时重渲染this.table.subscribe( this.table.store, (state) state.globalFilter, (globalFilter) html input typetext .value${globalFilter ?? } input${(e: InputEvent) this.table.setGlobalFilter((e.currentTarget as HTMLInputElement).value)} classsummary-panel placeholderSearch all columns... / , )2. 表格 store 组合选择器tbody 整体仅过滤/分页切片变化时重渲染private getBodyState (state: ReturnTypetypeof this.table.store.get) ({ columnFilters: state.columnFilters, globalFilter: state.globalFilter, pagination: state.pagination, }) this.table.subscribe(this.table.store, this.getBodyState, () htmltbody.../tbody)这里把 selector 定义为稳定的组件属性引用保证宿主重渲染时 source 与 selector 引用不变指令可跳过订阅重建对应update()中的去重判断。3. 外部 atom行选择统计仅选择状态变化时重渲染const rowSelectionAtom createAtomRowSelectionState({}) // ... this.table.subscribe(rowSelectionAtom, (rowSelection) htmldiv ${Object.keys(rowSelection).length.toLocaleString()} of ... Total Rows Selected /div)行内复选框则更进一步每行只订阅自己的选择值subscribe( table.atoms.rowSelection, (rowSelection) rowSelection[row.id], (isRowSelected) htmlinput typecheckbox .checked${!!isRowSelected} ... /, )这样切换某一行时只有该复选框的 DOM 更新而示例中 1000 行乃至 100 万行压力测试数据的渲染性能正是依赖这种岛式更新模式。八、适用场景与注意事项何时使用与 TableController 的宿主级订阅配合时SubscribeDirective适合对更新频率高、且彼此独立的状态区域做隔离例如行选择复选框、分页控件、过滤输入框、选中统计、行模型相关的 tbody 区域以及任何频繁变更但不想触发整表/整组件重渲染的片段。示例源码也提醒仅当你真正遇到性能问题时才使用这些模式——它不是默认写法的替代品而是一个可选的性能优化手段。注意事项update()中总是采用最新模板闭包这意味着模板可安全捕获外层渲染作用域的值但应理解这是刻意设计不是无意的行为选择器应尽量引用稳定如组件属性否则每次宿主渲染都会触发订阅重建sourceChanged || selectorChangeddisconnected()会清理订阅reconnected()会恢复并立即输出最新值配合repeat指令下的动态行/列渲染时可放心使用。九、相关参考类文档SubscribeDirective指令工厂文档subscribe()类型文档SelectionSource源码实现packages/lit-table/src/subscribe-directive.ts表格控制器packages/lit-table/src/TableController.ts完整示例examples/lit/basic-subscribe/src/main.ts赞分享前端UI组件【免费下载链接】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点击查看免费下载相关推荐CANN/docs PR文档翻译技能PR文档翻译Skill 功能描述 检测用户本地仓库的md文档自动翻译成英文文档。支持 非docs目录下的所有md文档 docs目录下排除列表外的md文档前端UI组件tanstack/lit-query 演进全解析基于 Lit 响应式控制器的 TanStack Query 官方适配层tanstack/lit query 演进全解析基于 Lit 响应式控制器的 TanStack Query 官方适配层 tanstack/lit quer前端缓存状态管理TanStack QueryLit 版useMutationState 深度解析从 Mutation Cache 中响应式订阅变更状态TanStack QueryLit 版useMutationState 深度解析从 Mutation Cache 中响应式订阅变更状态 useMutati前端缓存状态管理上一篇Agents与向量数据库集成实现高效语义搜索的完整方案下一篇Gloo性能优化10个技巧让你的WASM应用快如闪电创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TanStack Table Lit 适配器的 SubscribeDirective：基于 lit-store 的模板级细粒度状态订阅
前端UI组件【免费下载链接】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点击查看免费下载导读SubscribeDirective是 TanStack Table Lit 适配器tanstack/lit-table中用于实现模板片段级精准重渲染的核心异步指令。它订阅一个tanstack/lit-store的 Store 或 Atom当状态变化时只重渲染它包裹的那一小段模板而不是让整个 Lit 组件以及整张表格参与更新。读完本文你将掌握SubscribeDirective的完整类型签名、生命周期行为、fakeReactiveControllerHost桥接原理以及如何通过subscribe()/table.subscribe()在真实表格中实现过滤输入、分页控件、行选择复选框等区域的独立更新。一、SubscribeDirective 是什么按 SubscribeDirective 文档 的定义SubscribeDirective是一个异步 Lit 指令AsyncDirective它订阅一个tanstack/lit-store的 sourceStore 或 Atom状态变化时只为它包裹的模板部分触发重渲染与宿主组件或其他模板区域隔离使用一个 fake伪造的ReactiveControllerHost来弥合 TanStack 标准控制器TanStackStoreSelector的生命周期要求与AsyncDirective生命周期之间的差异。类定义位于 packages/lit-table/src/subscribe-directive.ts:43继承自AsyncDirective来自lit/async-directive.js。其核心价值在于在 TanStack Table 这样一个高频状态变更的场景中把状态变化 → 整组件重渲染的粗粒度更新细化成状态变化 → 仅更新依赖该状态的那块 DOM。二、类型体系SelectionSource、Selector 与 TemplateFunction要正确使用SubscribeDirective先理解它的三个基础类型源码见 subscribe-directive.ts:13-28SelectionSourceTValue可订阅源export type SelectionSourceTValue | AtomTValue | ReadonlyAtomTValue | StoreTValue | ReadonlyStoreTValue即指令接受tanstack/lit-store的四种来源可写 Atom、只读 Atom、可写 Store、只读 Store。这意味着你既可以订阅整张表格的table.store其状态为完整的TableState也可以订阅任意一个状态切片 atom如table.atoms.rowSelection甚至是你自己通过createAtom创建的外部 atom。对应类型别名文档见 SelectionSource。SelectorTSource, TSelected选择器type SelectorTSource, TSelected (state: TSource) TSelected一个从完整状态中提取/派生相关切片的纯函数。例如(state) state.pagination只取分页切片(rowSelection) rowSelection[row.id]只取某一行是否被选中。TemplateFunctionTSelected渲染函数type TemplateFunctionTSelected (value: TSelected) unknown接收被选中状态、返回要渲染的内容通常是 Lit 的TemplateResult的函数。它是订阅结果 → DOM 输出的桥梁。此外源码 subscribe-directive.ts:35 定义了一个恒等选择器identitySelector T(state: T): T state用于无选择器、订阅整个状态的场景保证内部逻辑统一走选择器 → 模板这条路径。三、render 的两种调用重载render()提供两个重载定义于 subscribe-directive.ts:61-76分别对应全量订阅与切片订阅两种用法重载一订阅完整状态renderTSource( source: SelectionSourceTSource, template: TemplateFunctionTSource, ): unknown只传source与template不经过选择器状态任意部分变化都会触发该模板片段重渲染。适合展示整个状态如调试面板的 JSON 输出。重载二订阅状态切片renderTSource, TSelected( source: SelectionSourceTSource, selector: SelectorTSource, TSelected, template: TemplateFunctionTSelected, ): unknown通过selector提取相关切片只有当该切片变化时才重渲染模板其他部分状态的变化不会波及该片段。这是细粒度渲染的主力形式。需要注意两个重载的render()方法体实际上只是return noChangesubscribe-directive.ts:78-85真正的渲染逻辑在update()中完成——注释明确指出实际渲染在 update 中处理以确保 template 只在必要时才被求值。四、update()订阅去重与模板闭包更新update()subscribe-directive.ts:87-144是SubscribeDirective的调度中枢其核心逻辑分四步参数归一化通过template undefined判断是否为恒等订阅即重载一从而决定哪个参数是选择器、哪个是模板。订阅条件判断比较this.latestSource ! source与this.latestSelector ! selector并结合this.initialized标志决定是否需要重建订阅shouldReinitialize。这样当宿主组件因无关原因重渲染、而 source 与 selector 均未变化时不会重建底层控制器。模板闭包始终更新源码注释说明了关键设计——模板闭包在每次宿主渲染时都会被重建并捕获外层渲染作用域表格包装器、行模型等的值因此指令总是采用最新的resolvedTemplate。若保留旧闭包订阅驱动的更新会持续用上一次渲染捕获的旧值渲染造成数据滞后。触发宿主更新并渲染当需要重建时先hostDisconnected()清理旧控制器再创建新的TanStackStoreSelector最后调用controller.hostUpdate()建立订阅并输出当前值。无论是否重建update()最后都会返回this.resolvedTemplate?.(this.latestSelector!(this.latestSource!.get()))即用最新选择器读取当前状态并渲染——这保证即使在无状态变更通知的宿主更新如行模型收到新数据下片段也能拿到新鲜输入。五、生命周期disconnected 与 reconnectedSubscribeDirective重写了AsyncDirective的两个连接生命周期方法disconnected()subscribe-directive.ts:147-149指令被从 DOM 移除时调用this.controller?.hostDisconnected()清理控制器订阅避免内存泄漏与悬挂回调。reconnected()subscribe-directive.ts:152-157指令被重新挂载到 DOM 时调用this.controller?.hostUpdate()恢复订阅若已有已解析模板则通过this.setValue(...)立即把最新选中状态写回片段保证重挂载后内容即时正确。其余成员构造函数、isConnected属性、_$isConnected访问器、_$initialize()、setValue()均继承自AsyncDirective其中setValue()用于在指令正常update/render生命周期之外设置片段值是订阅回调驱动重渲染的关键机制注意不能同步地在update或render内调用。六、核心设计fake ReactiveControllerHost 桥接SubscribeDirective最有技术含量的部分是它如何把 TanStack 的控制器体系接入 Lit 的异步指令体系。TanStackStoreSelector本是为ReactiveControllerHost宿主组件设计的控制器而指令没有宿主。解决办法是造一个假的宿主createFakeHost()subscribe-directive.ts:163-176返回一个最小ReactiveControllerHost实现return { addController: () {}, removeController: () {}, requestUpdate: () { if (this.resolvedTemplate this.controller) { this.setValue(this.resolvedTemplate(this.controller.value)) } }, get updateComplete() { return Promise.resolve(true) }, }要点addController/removeController为空操作——控制器注册对指令无实际意义requestUpdate是订阅回调的落点当 store/atom 状态变化时TanStackStoreSelector触发宿主requestUpdate()假宿主随即读取controller.value中最新的选中状态交给resolvedTemplate渲染并通过setValue()写入指令片段从而只更新这一小段 DOMupdateComplete立即 resolve保证需要等待更新完成的外部代码不会阻塞。通过这个桥接TanStackStoreSelector的完整生命周期订阅、通知、卸载被无缝移植到AsyncDirective上这也是文档注释所说的fake ReactiveControllerHost 弥合两者差距的源码级印证。七、订阅入口subscribe() 与 table.subscribe()独立的 subscribe() 指令subscribe是SubscribeDirective的指令工厂subscribe-directive.ts:191通过directive(SubscribeDirective)创建并带有与render()对应的两个重载签名。其标准用法示例出自 subscribe 变量文档// 无选择器订阅整个状态 htmldiv${subscribe(myStore, (state) htmlspan${state.count}/span)}/div // 有选择器仅当 count 变化时更新 htmldiv${subscribe(myStore, state state.count, (count) htmlspan${count}/span)}/div表格上的 table.subscribe()在TableController.table()返回的LitTable实例上subscribe被直接暴露为table.subscribe见 TableController.ts:222-229并可与表格配套的table.store、table.atoms.*或外部 atom 组合使用。配套的模式是给TableController.table()传() null选择器让宿主本身退出状态驱动的重渲染把颗粒度完全交给各table.subscribe片段TableController.ts:212-220 的注释明确说明门控让() ({})这类选择器把宿主完全排除在状态驱动更新之外将细粒度响应性推入 table.subscribe 岛。完整实战示例仓库中的 examples/lit/basic-subscribe/src/main.ts 是一个完整的可运行示例对应 React 侧的basic-subscribe覆盖三种订阅形态1. 表格 store 选择器全局过滤输入框仅过滤值变化时重渲染this.table.subscribe( this.table.store, (state) state.globalFilter, (globalFilter) html input typetext .value${globalFilter ?? } input${(e: InputEvent) this.table.setGlobalFilter((e.currentTarget as HTMLInputElement).value)} classsummary-panel placeholderSearch all columns... / , )2. 表格 store 组合选择器tbody 整体仅过滤/分页切片变化时重渲染private getBodyState (state: ReturnTypetypeof this.table.store.get) ({ columnFilters: state.columnFilters, globalFilter: state.globalFilter, pagination: state.pagination, }) this.table.subscribe(this.table.store, this.getBodyState, () htmltbody.../tbody)这里把 selector 定义为稳定的组件属性引用保证宿主重渲染时 source 与 selector 引用不变指令可跳过订阅重建对应update()中的去重判断。3. 外部 atom行选择统计仅选择状态变化时重渲染const rowSelectionAtom createAtomRowSelectionState({}) // ... this.table.subscribe(rowSelectionAtom, (rowSelection) htmldiv ${Object.keys(rowSelection).length.toLocaleString()} of ... Total Rows Selected /div)行内复选框则更进一步每行只订阅自己的选择值subscribe( table.atoms.rowSelection, (rowSelection) rowSelection[row.id], (isRowSelected) htmlinput typecheckbox .checked${!!isRowSelected} ... /, )这样切换某一行时只有该复选框的 DOM 更新而示例中 1000 行乃至 100 万行压力测试数据的渲染性能正是依赖这种岛式更新模式。八、适用场景与注意事项何时使用与 TableController 的宿主级订阅配合时SubscribeDirective适合对更新频率高、且彼此独立的状态区域做隔离例如行选择复选框、分页控件、过滤输入框、选中统计、行模型相关的 tbody 区域以及任何频繁变更但不想触发整表/整组件重渲染的片段。示例源码也提醒仅当你真正遇到性能问题时才使用这些模式——它不是默认写法的替代品而是一个可选的性能优化手段。注意事项update()中总是采用最新模板闭包这意味着模板可安全捕获外层渲染作用域的值但应理解这是刻意设计不是无意的行为选择器应尽量引用稳定如组件属性否则每次宿主渲染都会触发订阅重建sourceChanged || selectorChangeddisconnected()会清理订阅reconnected()会恢复并立即输出最新值配合repeat指令下的动态行/列渲染时可放心使用。九、相关参考类文档SubscribeDirective指令工厂文档subscribe()类型文档SelectionSource源码实现packages/lit-table/src/subscribe-directive.ts表格控制器packages/lit-table/src/TableController.ts完整示例examples/lit/basic-subscribe/src/main.ts赞分享前端UI组件【免费下载链接】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点击查看免费下载相关推荐CANN/docs PR文档翻译技能PR文档翻译Skill 功能描述 检测用户本地仓库的md文档自动翻译成英文文档。支持 非docs目录下的所有md文档 docs目录下排除列表外的md文档前端UI组件tanstack/lit-query 演进全解析基于 Lit 响应式控制器的 TanStack Query 官方适配层tanstack/lit query 演进全解析基于 Lit 响应式控制器的 TanStack Query 官方适配层 tanstack/lit quer前端缓存状态管理TanStack QueryLit 版useMutationState 深度解析从 Mutation Cache 中响应式订阅变更状态TanStack QueryLit 版useMutationState 深度解析从 Mutation Cache 中响应式订阅变更状态 useMutati前端缓存状态管理上一篇Agents与向量数据库集成实现高效语义搜索的完整方案下一篇Gloo性能优化10个技巧让你的WASM应用快如闪电创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考