TanStack Table v9 的 Lit 列可见性(Column Visibility)实战指南:隐藏/显示列的完整实现方案

发布时间:2026/9/20 12:45:39

TanStack Table v9 的 Lit 列可见性(Column Visibility)实战指南:隐藏/显示列的完整实现方案 前端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点击查看免费下载导读本文基于 TanStack Table 开源仓库的 Lit 框架指南系统讲解在tanstack/lit-tablev9中启用与使用列可见性功能Column Visibility的完整方案。你会掌握columnVisibilityFeature的注册方式、columnVisibility状态的三种管理模式外部 atom、受控 state、initialState、按列禁用隐藏的配置以及如何用getIsVisible/getToggleVisibilityHandler/getVisibleLeafColumns/getVisibleCells等 API 渲染出可用的列显隐切换面板与“感知可见性”的表头、表体、表尾渲染逻辑。示例先行可运行的 Lit 参考实现如果想直接跳到完整实现仓库中提供了可运行的 Lit 示例 examples/lit/column-visibility包含示例入口 main.ts完整的组件实现含列切换面板、表头/表体/表尾渲染与调试输出e2e 冒烟测试 smoke.spec.ts覆盖列显隐切换、Toggle All、表头分组消失、数据重建后状态保持等行为的端到端验证package.json依赖tanstack/lit-table^9.1.2与lit^3.3.3可通过pnpm devVite启动开发预览pnpm test:e2e运行 Playwright 端到端测试。该示例的数据由makeData基于 faker 随机生成见 makeData.ts表结构包含NamefirstName/lastName与Infoage/visits/status/progress两层表头分组正好可以验证“分组列随子列全部隐藏而消失”的行为。启用列可见性功能Feature 注册列可见性是一个按需注册的 feature。在 v9 中通过tableFeatures将columnVisibilityFeature注入到features即可启用启用后相关的列 API、表 API 与columnVisibility状态切片才会被创建。import { LitElement, html } from lit import { customElement, state } from lit/decorators.js import { TableController, tableFeatures, columnVisibilityFeature, } from tanstack/lit-table const features tableFeatures({ columnVisibilityFeature }) customElement(my-table) class MyTable extends LitElement { state() private data defaultData private tableController new TableController(this) protected render() { const table this.tableController.table({ features, columns, data: this.data, }) return html... } }从源码看columnVisibilityFeature.ts 做了四件事通过getInitialState注入默认columnVisibility状态默认值为空对象通过getDefaultTableOptions提供默认的onColumnVisibilityChange状态更新器通过assignColumnPrototype挂载列级 APIgetIsVisible、getCanHide、toggleVisibility、getToggleVisibilityHandler通过constructTableAPIs挂载表级 APIgetVisibleFlatColumns、getVisibleLeafColumns、setColumnVisibility、resetColumnVisibility、toggleAllColumnsVisible等。其中getIsVisible、row.getVisibleCells等 API 的 memo 依赖都包含table.atoms.columnVisibility?.get()意味着可见性状态变化时会触发这些派生 API 的精确重算。在 示例 main.ts 中TableController还传入了第二个参数(state) ({ columnVisibility: state.columnVisibility })作为选择器让table.state.columnVisibility只订阅可见性切片从而把重渲染范围控制在最小。columnVisibility 状态映射与判空规则columnVisibility状态本质是一个列 ID 到布尔值的映射Recordstring, boolean类型为ColumnVisibilityState。判定规则如下某列 ID 存在于映射中且值为false→ 该列隐藏某列 ID 不存在于映射中或值为true→ 该列显示。也就是说“未记录”即“可见”。对应源码见 columnVisibilityFeature.utils.ts 中的column_getIsVisible叶子列读取state.columnVisibility[column.id]缺失时回退为true父级分组列则在其任意子列可见时视为可见。这一“缺失即可见”的设计带来两个实用推论初始空状态{}意味着所有列都可见勾选又取消重新显示某列时映射中会保留{ columnId: true }这样的显式记录而不是删除该键——e2e 测试中专门断言了这一点取消勾选后重新勾选visits状态变为{ visits: true }。管理可见性状态的三种方式根据“是否需要把columnVisibility状态所有权移出表格”v9 提供三种模式按推荐优先级排列。方式一外部 Atom推荐v9 首选如果需要自己拥有可见性状态例如持久化用户偏好推荐在模块作用域或共享 store 模块创建稳定的 atom并通过atoms选项注入。外部 atom 的优势是应用任何位置都能做细粒度订阅其他代码读写可见性状态时无需经过持有表格的组件。import { createAtom } from tanstack/store import { TableController, tableFeatures, columnVisibilityFeature, } from tanstack/lit-table import type { ColumnVisibilityState } from tanstack/lit-table const features tableFeatures({ columnVisibilityFeature }) // 在模块作用域或共享 store 模块创建稳定 atom const columnVisibilityAtom createAtomColumnVisibilityState({ columnId1: true, columnId2: false, // 默认隐藏此列 columnId3: true, }) const table this.tableController.table({ features, //... atoms: { columnVisibility: columnVisibilityAtom, }, }) // 在任意需要的地方读取columnVisibilityAtom.get() // 或订阅变化columnVisibilityAtom.subscribe(...)v9 的状态体系建立在 TanStack Store 之上table.atoms是每个已注册状态切片对应的只读派生 atomtable.store是它们组合出的扁平只读 store而外部 atom 则直接接管对应切片的可写源头。关于 v9 状态表面table.baseAtoms/table.atoms/table.store/table.state的完整对比可参考 Table State (Lit) Guide。方式二v8 风格受控 State兼容迁移v8 风格的state.columnVisibilityonColumnVisibilityChange模式依然受支持。它适合简单集成或从 v8 迁移的代码但粒度不如外部 atom 细。const features tableFeatures({ columnVisibilityFeature }) state() private columnVisibility: ColumnVisibilityState { columnId1: true, columnId2: false, // 默认隐藏此列 columnId3: true, } const table this.tableController.table({ features, //... state: { columnVisibility: this.columnVisibility, //... }, onColumnVisibilityChange: (updater) { this.columnVisibility typeof updater function ? updater(this.columnVisibility) : updater }, })注意onColumnVisibilityChange的 updater 既可以是新的状态对象也可以是(old) newState的函数——这正是table.setColumnVisibility的更新语义见源码table_setColumnVisibility其底层通过setStateSlice路由到该回调。方式三initialState 仅初始化如果可见性状态完全不需要脱离表格管理只需用initialState设置初始默认状态即可。此时状态由表格内部持有。const features tableFeatures({ columnVisibilityFeature }) const table this.tableController.table({ features, //... initialState: { columnVisibility: { columnId1: true, columnId2: false, // 默认隐藏此列 columnId3: true, }, //... }, })[!NOTE] 如果columnVisibility同时传给initialState和statestate的初始化优先initialState会被忽略。两者只能二选一不要同时提供。此外table.resetColumnVisibility()可以把可见性重置回initialState的配置而table.resetColumnVisibility(true)会忽略初始状态、直接重置为{}即全部可见。禁止隐藏指定列enableHiding默认所有列都可隐藏/显示。若希望某些列不可隐藏在对应列定义上设置enableHiding: falseconst columns [ { header: ID, accessorKey: id, enableHiding: false, // 禁止隐藏此列 }, { header: Name, accessorKey: name, // 可隐藏 }, ]源码中column_getCanHide的判定是两层“与”关系列级columnDef.enableHiding与表级table.options.enableHiding都默认为true只要任意一层为false该列就不可隐藏return ( (column.columnDef.enableHiding ?? true) (column.table.options.enableHiding ?? false ? // 表级默认 true (column.table.options.enableHiding ?? true)) )因此也可以在tableOptions上设置表级enableHiding: false来全局禁止所有列隐藏示例 main.ts 中留有该选项的注释。对应的toggleVisibility内部会先检查getCanHide不可隐藏的列不会写入状态见column_toggleVisibilitytoggleAllColumnsVisible(false)也会把不可隐藏的列保持为可见。列级 Toggle API渲染显隐切换 UI渲染列显隐切换控件时下面几个列 API 最常用column.getCanHide()—— 判断该列是否允许隐藏用于禁用不可隐藏列的开关对应enableHiding: falsecolumn.getIsVisible()—— 读取当前可见性用作开关的初始选中态column.toggleVisibility(visible?)—— 切换可见性传visible则写入该值不传则翻转当前状态column.getToggleVisibilityHandler()—— 返回一个事件处理器把column.toggleVisibility直接接到 UI 事件上内部读取event.target.checked。一个典型的列切换面板渲染所有叶子列的 checkbox如下html ${table.getAllLeafColumns().map( (column) html label input typecheckbox .checked${column.getIsVisible()} ?disabled${!column.getCanHide()} change${column.getToggleVisibilityHandler()} / ${column.id} /label , )} 示例 main.ts 在此基础上还实现了“Toggle All”全选控制使用了表级配套 APItable.getIsAllColumnsVisible()是否全部可见、table.getToggleAllColumnsVisibilityHandler()全选/全不选的事件处理器。e2e 测试验证了点击某个列开关后 Toggle All 会自动取消选中因为它由getIsAllColumnsVisible驱动全部取消后所有表头/单元格消失但tbody行依然存在每行渲染 0 个可见单元格。感知可见性的渲染 API不要用错“全量”方法渲染表头、表体、表尾时table.getAllLeafColumns与row.getAllCells不会考虑列可见性它们返回全量列/单元格。必须改用对应的 “visible” 变体table.getVisibleLeafColumns()—— 过滤后的可见叶子列row.getVisibleCells()—— 过滤后的可见单元格若有列固定还会按“起始固定 → 中间 → 末尾固定”的顺序排列见row_getVisibleCells源码。html table thead tr ${table .getVisibleLeafColumns() .map((column) htmlth${column.id}/th)} /tr /thead tbody ${table.getRowModel().rows.map( (row) html tr ${row .getVisibleCells() .map((cell) htmltd${FlexRender({ cell })}/td)} /tr , )} /tbody /table 此外还有几个关联 API 值得了解table.getVisibleFlatColumns()—— 过滤后的可见“平铺”列含父级分组列父列在任一字列可见时可见table.getIsSomeColumnsVisible()—— 是否存在至少一个可见叶子列适合做三态“全选”控件row.getVisibleCellsByColumnId()—— 以列 ID 为键的可见单元格查找表隐藏列不出现是固定列重排时内部使用的数据源。如果使用了 Header Group API如table.getHeaderGroups()、table.getFooterGroups()与header.colSpan它们已经内置了可见性计算无需额外过滤。示例中表头/表尾正是用getHeaderGroupsgetFooterGroups渲染的隐藏列后colSpan与分组行都会自动收敛e2e 测试还验证了“当某分组的所有子列都隐藏后该分组列头才会消失”的行为Name分组在firstName、lastName都被隐藏后才从表头消失。与数据更新的关系可见性独立于行数据列可见性状态保存在表格状态中与行数据data相互独立。示例专门验证了这一点隐藏age列后点击 “Regenerate Data” 重新生成 20 行随机数据columnVisibility保持{ age: false }切换开关保持未选中可见单元格数量不变见 smoke.spec.ts 的 “keeps column visibility when data is regenerated” 用例。因此在实现“数据刷新但保留用户列配置”这类需求时只要不重置表格状态可见性配置会自动保留。小结与深入阅读在 Lit TanStack Table v9 中实现列显隐只需四步注册columnVisibilityFeature按需选择atoms/state/initialState管理columnVisibility状态用enableHiding控制哪些列不可隐藏渲染时使用getIsVisible、getToggleVisibilityHandler等切换 API 与getVisibleLeafColumns、getVisibleCells等感知可见性的渲染 API。源码实现集中在 columnVisibilityFeature.ts 与其 utils可运行示例与端到端测试见 examples/lit/column-visibility。进一步的关联主题可继续阅读状态管理总览 Table State (Lit) Guide、列固定 column-pinning.md、列顺序 column-ordering.md以及仓库内其他框架的对应指南如 docs/framework/react/guide/column-visibility.md。赞分享前端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点击查看免费下载相关推荐Preact 表格列显隐Column Visibility实战指南动态隐藏/显示列的完整实现Preact 表格列显隐Column Visibility实战指南动态隐藏/显示列的完整实现 列显隐Column Visibility是数据表格中最常前端UI组件TanStack TableEmber列显隐实战从 columnVisibilityFeature 到列可见性 Toggle 的完整实现TanStack TableEmber列显隐实战从 columnVisibilityFeature 到列可见性 Toggle 的完整实现 导读 本指南围绕前端UI组件TanStack Table React 列过滤实战指南v9 中 Column Filtering 的完整实现与源码剖析TanStack Table React 列过滤实战指南v9 中 Column Filtering 的完整实现与源码剖析 本文围绕 TanStack Tabl前端UI组件上一篇7分钟掌握Laravel Stats一键生成项目架构全景报告下一篇鲁班H5终极指南PSD一键转换、第三方API集成与自动化部署全解析创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/20 12:45:39

VCSA 6.7证书过期导致无法登录的紧急恢复与修复指南

1. 故障现场还原与核心问题定位1.1 一个典型的VCSA 6.7登录故障场景早上九点,运维群里弹出一条消息:“vCenter打不开了,网页提示证书错误,客户端也连不上。”我打开浏览器访问vCenter的5480端口,页面直接报SSL证书过期…

2026/9/20 12:40:39

windows控制台cmd乱码解决方案

我们在cmd中执行命令的时候,有时候会出现中文乱码问题,我们可以使用chcp命令解决乱码在控制台输入chcp命令可以查看当前代码页的编码是963(简体中文 GBK编码)控制台中输入chcp 65001并回车将代码页编码改为 UTF-8,这样…

2026/9/20 13:20:42

n8n实战:如何用开源工作流工具实现公众号运营自动化

简介:一份详细介绍利用n8n搭建公众号运营自动化工作流的实战文档,适合有一定编程基础、希望减少重复劳动的公众号运营者或开发者阅读。文档先从工具与账号准备入手,覆盖n8n平台、DeepSeek API、豆包模型API、微信公众号开发者账号的申请与配置…

2026/9/20 13:20:42

AssetRipper资产提取快速指南

AssetRipper资产提取快速指南 【免费下载链接】AssetRipper GUI application to analyze game files 项目地址: https://gitcode.com/GitHub_Trending/as/AssetRipper AssetRipper是一款免费的Unity资产提取工具,支持3.5.0到6000.5.X版本,能把游戏…

2026/9/20 13:20:42

hwinfo64免费版使用指南:用传感器数据精准排查硬件故障

简介:hwinfo64是一款专门面向64位Windows系统的专业硬件检测与性能测试工具,适合电脑爱好者、装机用户和技术运维人员使用,可全面查看处理器、主板及芯片组、PCMCIA接口、BIOS版本、内存等硬件信息,也可监控CPU温度,并…

2026/9/20 13:20:42

华为IFS财经变革启示:业财融合与流程重构的落地路径

简介:这份49页PPT系统梳理了华为IFS(集成财经服务)变革的全貌,适合企业财务管理者、流程变革从业者及研究华为管理实践的学习者。内容围绕变革动因、总体指导思想、核心框架与落地路径展开,清晰呈现了华为如何应对财经…

2026/9/20 13:15:41

实测降AIGC平台效果!实测下来谁更胜一筹?

最近后台快被私信炸毁了,清一色都是同一个问题:"论文AI率90%,学校用知网查,有没有靠谱的降AI工具?"作为一个帮三个学弟学妹成功通过盲审的过来人,我想说:选错工具,轻则白花…

2026/9/20 0:04:49

GAMP 5 基于风险的计算机化系统验证:软件分类与审计追踪实践

简介:《A Risk-Based Approach to Compliant GxP Computerized Systems》即业内熟知的GAMP 5指南,面向制药企业质量与IT合规人员、验证工程师及计算机化系统管理者,用于解决GxP法规环境下系统合规性难以科学落地的问题。文档以风险管理为主线…

2026/9/20 0:04:49

安全托管MSSP实战:从静态防御到人机协同的攻防运营与应急响应

简介:这份PPT围绕互联网业务安全托管服务展开,面向企业安全负责人、IT运维人员及关注MSSP/MSS选型的读者,重点回应传统安全过度依赖人工、碎片化静态防御难以对抗产业化攻击等痛点。资源共1个pptx文件,包体约30.63MB,以…

2026/9/20 0:04:49

GAMP 5 基于风险的计算机化系统验证:软件分类与审计追踪实践

简介:《A Risk-Based Approach to Compliant GxP Computerized Systems》即业内熟知的GAMP 5指南,面向制药企业质量与IT合规人员、验证工程师及计算机化系统管理者,用于解决GxP法规环境下系统合规性难以科学落地的问题。文档以风险管理为主线…

2026/9/20 0:04:49

安全托管MSSP实战:从静态防御到人机协同的攻防运营与应急响应

简介:这份PPT围绕互联网业务安全托管服务展开,面向企业安全负责人、IT运维人员及关注MSSP/MSS选型的读者,重点回应传统安全过度依赖人工、碎片化静态防御难以对抗产业化攻击等痛点。资源共1个pptx文件,包体约30.63MB,以…

2026/9/20 4:54:47

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/20 5:01:23

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/20 5:09:33

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码