前端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 Tabletable-core 核心 React/Vue/Solid/Svelte 等框架适配层中列可见性Column Visibility特性的两个表级配置选项——enableHiding与onColumnVisibilityChange。它们定义于TableOptions_ColumnVisibility接口是启用列隐藏/显示能力、接入受控状态controlled state的入口。读完本文你将掌握这两个选项的默认行为、与columnVisibility状态的关系、外部 Atom 与回调两种状态管理模式并能结合源码与示例搭建一个完整可用的显示/隐藏列控制面板。接口概览TableOptions_ColumnVisibility该接口在仓库中的定义位于 columnVisibilityFeature.types.ts完整签名如下export interface TableOptions_ColumnVisibility { /** * Whether to enable column hiding. Defaults to true. */ enableHiding?: boolean /** * Called with an updater when column visibility state changes. Pair this with * state.columnVisibility when using external state; external atoms can own * the slice without this callback. */ onColumnVisibilityChange?: OnChangeFnColumnVisibilityState }接口仅包含两个可选属性集中体现了列可见性特性的全部表级配置面属性类型默认值作用enableHidingboolean可选true是否允许隐藏列表级总开关onColumnVisibilityChangeOnChangeFnColumnVisibilityState可选由makeStateUpdater生成的内部更新器列可见性状态变化时被调用的回调配合state.columnVisibility实现受控模式配套的状态类型ColumnVisibilityState定义在同一文件顶部columnVisibilityFeature.types.tsexport type ColumnVisibilityState Recordstring, boolean即一个列 ID → 布尔值的映射某列 ID 的值为false表示该列被隐藏值为true或该列 ID 不在映射中都表示该列可见。这一缺失即可见的语义是整个特性的核心约定下文源码分析会反复印证。选项一enableHiding——控制列能否被隐藏enableHiding是列隐藏能力的总开关默认值为true即默认情况下所有列都可以被隐藏或重新显示。当你希望某些列例如主键、操作按钮列始终固定可见时有两种层级可以关闭隐藏能力。表级全局禁用将enableHiding: false传入useTable的选项对象即可让所有列都无法隐藏const table useTable({ features, columns, data, enableHiding: false, // 全局禁止隐藏任何列 })列级定向禁用更常见的做法是在**列定义ColumnDef**上使用列级enableHiding只锁定特定列。列级选项定义于 ColumnDef_ColumnVisibility源码见 columnVisibilityFeature.types.tsconst columns [ { header: ID, accessorKey: id, enableHiding: false, // 该列禁止隐藏 }, { header: Name, accessorKey: name, // 未设置默认可隐藏 }, ]组合判定逻辑column_getCanHide列级与表级两个开关并非二选一而是**与关系**。核心实现位于 columnVisibilityFeature.utils.tsexport function column_getCanHide(column) { return ( (column.columnDef.enableHiding ?? true) (column.table.options.enableHiding ?? true) ) }即只有当列定义的enableHiding缺省视为true且表级enableHiding缺省视为true都为真时该列才允许被隐藏。任一设置为falsecolumn.getCanHide()都会返回false。测试用例 columnVisibilityFeature.utils.test.ts 分别验证了全局禁用与列级禁用两条路径均使column_getCanHide返回false。提示即使某列被锁定为不可隐藏它的 ID 仍可能出现在columnVisibility状态映射中但column_toggleVisibility在调用前会先检查column_getCanHide不可隐藏的列会被直接跳过状态不会被修改见 utils 实现 columnVisibilityFeature.utils.ts。选项二onColumnVisibilityChange——受控状态的更新回调onColumnVisibilityChange的完整类型为OnChangeFnColumnVisibilityState即接收一个更新器updater的函数。更新器可以是新的状态映射也可以是接收旧状态并返回新状态的函数// 直接传入新映射 onColumnVisibilityChange({ visits: false }) // 或传入函数式更新器 onColumnVisibilityChange((old) ({ ...old, visits: false }))该回调在以下场景被触发table.setColumnVisibility(updater)table.toggleAllColumnsVisible(value)任一列执行column.toggleVisibility(value)table.resetColumnVisibility(defaultState)默认行为内部状态更新器即使你不传该选项列可见性依然可用。feature 在注册时通过getDefaultTableOptions为onColumnVisibilityChange提供了默认实现见 columnVisibilityFeature.tsgetDefaultTableOptions: (table) { return { onColumnVisibilityChange: makeStateUpdater(columnVisibility, table), } }makeStateUpdater(columnVisibility, table)生成一个内部更新器负责将新状态写回表的state.columnVisibility并触发相关订阅。这解释了为什么什么都不配也能开箱即用地隐藏/显示列——默认情况下表格自己管理这份状态。受控模式state.columnVisibility onColumnVisibilityChange当你需要自行拥有columnVisibility状态例如持久化用户偏好、与表单联动、在表格外部读写v8 风格的受控模式仍然受支持把状态值传给state.columnVisibility把 setter 传给onColumnVisibilityChangeconst [columnVisibility, setColumnVisibility] useStateColumnVisibilityState({ columnId1: true, columnId2: false, // 默认隐藏该列 columnId3: true, }) const table useTable({ features, columns, data, state: { columnVisibility, }, onColumnVisibilityChange: setColumnVisibility, })推荐方案外部 Atom无需该回调按原文档的说明React 指南外部 Atom 可以直接拥有这个状态切片从而无需onColumnVisibilityChange回调。外部 Atom 提供全应用范围内的细粒度订阅表格之外的其他代码也能读写可见性状态而无需重新渲染拥有表格的组件import { useCreateAtom, useSelector } from tanstack/react-store import { columnVisibilityFeature, tableFeatures, useTable } from tanstack/react-table import type { ColumnVisibilityState } from tanstack/react-table const features tableFeatures({ columnVisibilityFeature }) const columnVisibilityAtom useCreateAtomColumnVisibilityState({ columnId1: true, columnId2: false, // 默认隐藏该列 columnId3: true, }) const columnVisibility useSelector(columnVisibilityAtom) // 在任意需要的地方订阅 const table useTable({ features, columns, data, atoms: { columnVisibility: columnVisibilityAtom, }, })此时可见性状态的写入经由atoms.columnVisibility直接落到外部 AtomonColumnVisibilityChange不再是必需项。这是 v9 框架适配层推荐的状态管理方式。非受控模式initialState 设定初始值如果状态完全交给表格内部管理只需用initialState.columnVisibility指定初始可见性const table useTable({ features, columns, data, initialState: { columnVisibility: { columnId1: true, columnId2: false, // 首屏默认隐藏该列 columnId3: true, }, }, })注意若columnVisibility同时出现在initialState和state中state的初始化优先initialState会被忽略。二者只能二选一见 React 指南 的 NOTE 提示。状态语义与默认状态列可见性 feature 在注册时通过getInitialState注入初始状态columnVisibilityFeature.ts默认状态由getDefaultColumnVisibilityState()生成即一个空对象{}实现见 columnVisibilityFeature.utils.ts。空对象的语义是所有列 ID 在映射中缺失因此所有列默认可见。测试 columnVisibilityFeature.utils.test.ts 验证了getDefaultColumnVisibilityState()返回{}且column_getIsVisible在默认情况下返回true。column_getIsVisible的判定逻辑columnVisibilityFeature.utils.ts还处理了两种特殊情况叶子列leaf读取state.columnVisibility[column.id]缺失时回退为true父/分组列parent/group自身没有直接状态条目而是递归判断任一子列可见则该父列可见。测试用例should return true if any child column is visible验证了这一点columnVisibilityFeature.utils.test.ts。配套 API 家族Table、Column、Row 三层TableOptions_ColumnVisibility只是配置入口特性启用后会为三个对象注入完整 API类型定义见 columnVisibilityFeature.types.ts注册逻辑见 columnVisibilityFeature.ts。Table 级 APIAPI说明getIsAllColumnsVisible()是否所有叶子列都可见用于全选复选框的 checkedgetIsSomeColumnsVisible()是否至少一个叶子列可见用于三态控制getToggleAllColumnsVisibilityHandler()复选框风格处理器读取event.target.checked并切换全部列getVisibleFlatColumns()当前可见的扁平列列表含仍有可见后代的父列getVisibleLeafColumns()当前可见的叶子列列表行单元格与表头渲染通常用它resetColumnVisibility(defaultState?)重置为initialState.columnVisibility传true则忽略初始状态、重置为{}setColumnVisibility(updater)以新映射或更新器函数更新可见性状态toggleAllColumnsVisible(value?)显示/隐藏所有可隐藏的叶子列getToggleAllColumnsVisibilityHandler的源码columnVisibilityFeature.utils.ts展示了它与onColumnVisibilityChange的联动处理器把event.target.checked传给table_toggleAllColumnsVisible后者构建完整映射并调用table_setColumnVisibility最终经由setStateSlice路由到onColumnVisibilityChange默认是内部更新器受控模式下是你传入的 setter。Column 级 APIAPI说明getCanHide()该列是否允许被隐藏综合列级与表级enableHidinggetIsVisible()该列当前是否可见getToggleVisibilityHandler()复选框风格处理器读取event.target.checked切换该列toggleVisibility(value?)切换该列可见性不传值时自动取反完整签名见 Column_ColumnVisibility。Row 级 APIAPI说明getVisibleCells()该行中属于可见列的单元格启用列固定时按 start → center → end 排序getVisibleCellsByColumnId()以列 ID 为键的可见单元格映射隐藏列被剔除渲染要点务必使用可见系列 API启用列隐藏后渲染表头、表体与表脚时不要使用table.getAllLeafColumns()、row.getAllCells()这类忽略可见性的 API而要改用table.getVisibleLeafColumns()、row.getVisibleCells()否则被隐藏的列仍会渲染出来。表头分组 APItable.getHeaderGroups()等本身已经考虑了列可见性可放心使用见 React 指南。table_getVisibleLeafColumns与row_getVisibleCells的实现columnVisibilityFeature.utils.ts都是先取全集、再按column_getIsVisible过滤row_getVisibleCells额外处理了列固定pinning下的排序。两个 API 在 columnVisibilityFeature.ts 中注册了 memo 依赖含columnVisibility、columnOrder、columnPinning、grouping等状态状态变化时自动失效重算。端到端示例构建显示/隐藏列控制面板仓库的官方示例 examples/react/column-visibility/src/main.tsx 是上述选项与 API 的完整落地核心结构如下const features tableFeatures({ columnVisibilityFeature }) const table useTable({ features, columns, data, // initialState: { columnVisibility: { visits: false } }, // 首屏隐藏某列 // atoms: { columnVisibility: columnVisibilityAtom }, // 推荐外部 Atom 拥有状态 // state: { columnVisibility }, // 受控模式 // onColumnVisibilityChange: setColumnVisibility, // enableHiding: false, // 全局禁止隐藏 debugTable: true, }) // 全选开关 逐列开关 table thead {table.getHeaderGroups().map((headerGroup) ( tr key{headerGroup.id} {headerGroup.headers.map((header) ( th key{header.id} colSpan{header.colSpan} {header.isPlaceholder ? null : table.FlexRender header{header} /} /th ))} /tr ))} /thead tbody {table.getRowModel().rows.map((row) ( tr key{row.id} {row.getVisibleCells().map((cell) ( td key{cell.id} table.FlexRender cell{cell} / /td ))} /tr ))} /tbody /table控制面板部分将全选复选框绑定到table.getIsAllColumnsVisible()与table.getToggleAllColumnsVisibilityHandler()将逐列复选框绑定到column.getIsVisible()与column.getToggleVisibilityHandler()与 React 指南 中给出的模板一致。该示例同时提供了 e2e 冒烟测试 examples/react/column-visibility/tests/e2e/smoke.spec.ts用于验证切换列可见性后的渲染结果。提示可见性菜单通常渲染列本身而非表头对象——被隐藏的列可能没有活动的表头上下文。建议使用稳定的文本标签如自定义的列 ID → 标签映射、columnDef.meta中的label字段或直接使用column.id作为开关文案见 React 指南 的 NOTE。源码链路小结将以上内容串起来一次隐藏某列操作背后的完整调用链为UI 触发column.getToggleVisibilityHandler()或column.toggleVisibility(false)column_toggleVisibility校验column_getCanHide列级与表级enableHiding与运算并将新的可见性写入各叶子列columnVisibilityFeature.utils.tstable_setColumnVisibility通过setStateSlice将更新器路由到onColumnVisibilityChangecolumnVisibilityFeature.utils.ts默认情况下该回调是makeStateUpdater生成的内部更新器将状态写回表内受控模式下则由你的onColumnVisibilityChange接收更新器并驱动state.columnVisibility外部 Atom 模式下状态直接落到 Atom状态变化使getVisibleLeafColumns、getVisibleCells等 memo 依赖失效重算后触发渲染隐藏的列从表头与表体中消失。常见误区使用全集 API 渲染getAllLeafColumns()/getAllCells()不感知可见性渲染时必须改用getVisibleLeafColumns()/getVisibleCells()initialState与state同时提供columnVisibilitystate优先initialState被忽略请二选一误以为enableHiding: false会从状态中清除该列不可隐藏的列只是不会被toggleVisibility修改若它已在状态映射中仍可通过setColumnVisibility显式赋值虽然不推荐将分组列 ID 直接写入状态可见性状态按叶子列 ID 索引对分组列调用toggleVisibility会扩散到其可隐藏的叶子列而非写入分组列自身 ID有测试用例专门验证见 columnVisibilityFeature.utils.test.ts。延伸阅读React 框架列可见性指南各框架均有对应指南如 Vue、Angular、Svelte、SolidColumn_ColumnVisibility 接口 与 ColumnDef_ColumnVisibility 接口Table_ColumnVisibility 接口 与 TableState_ColumnVisibility 接口columnVisibilityFeature 变量文档 及各静态函数文档如 table_setColumnVisibility、column_toggleVisibility官方示例 examples/react/column-visibility其他框架如 Vue、Svelte 也有对应版本赞分享前端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 Octane Table 列显隐Column Visibility特性实战指南TanStack Octane Table 列显隐Column Visibility特性实战指南 本篇指南聚焦 TanStack Octane Table前端UI组件TanStack Table v9 的 Lit 列可见性Column Visibility实战指南隐藏/显示列的完整实现方案TanStack Table v9 的 Lit 列可见性Column Visibility实战指南隐藏/显示列的完整实现方案 导读 本文基于 TanSta前端UI组件TanStack Svelte Table v9 列可见性Column Visibility完全指南状态管理、切换 API 与渲染实践TanStack Svelte Table v9 列可见性Column Visibility完全指南状态管理、切换 API 与渲染实践 本文聚焦 TanS前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考