Vuetify v-table 完全指南：轻量表格组件的 Props、Slots 与 Sass 定制

Vuetify v-table 完全指南轻量表格组件的 Props、Slots 与 Sass 定制【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetifyv-table是 Vuetify 组件库中最基础的表格组件它是对原生 HTMLtable元素的一层轻量封装在保留thead、tbody、tr、td等原生标签语义的同时注入 Material Design 风格的外观与交互。本文基于 Vuetify 官方文档tables.md并结合源码实现系统讲解v-table的全部 Props、Slots、样式变量与底层渲染机制读完你可以直接用它构建从静态数据展示到固定表头、斑马纹、悬停高亮等各类轻量表格场景。v-table 是什么轻量包装而非重型数据表格在 Vuetify 的表格家族中v-table属于简单的一端。官方文档对它的定位是The simpler of the table components isv-table, a basic wrapper component for the HTMLtableelement. In addition, regular table elements such asthead,tbody,tr, andtdwork by default.即它是对原生table元素的基础包装组件原生表格标签thead、tbody、tr、td等默认即可直接使用不需要额外注册或转换。这意味着你现有的手写 HTML 表格结构可以近乎零成本迁移到 Vuetify 的视觉体系下。从源码看组件定义位于 VTable.tsx通过genericComponent创建inheritAttrs: false最终渲染为一个v-table类名的根元素内部结构为props.tag classv-table ... !-- 默认 tag 为 div -- └─ div classv-table__wrapper !-- 可滚动容器 -- └─ table !-- 原生 table --值得注意的是v-table并不像v-data-table那样内置排序、分页、筛选等数据能力。若需要这些高级功能官方文档明确指向更复杂的表格组件v-data-table其示例可见 packages/docs/src/examples/v-data-table。选择原则很简单纯展示用v-table需要数据操作能力时升级到v-data-table。基本用法从原生表格到 v-tablev-table的使用方式与原生表格几乎一致把table换成v-table即可。官方 Usage 示例usage.vue如下template v-table thead tr th classtext-leftName/th th classtext-leftCalories/th /tr /thead tbody tr v-foritem in desserts :keyitem.name td{{ item.name }}/td td{{ item.calories }}/td /tr /tbody /v-table /template script export default { data () { return { desserts: [ { name: Frozen Yogurt, calories: 159 }, { name: Ice cream sandwich, calories: 237 }, { name: Eclair, calories: 262 }, { name: Cupcake, calories: 305 }, { name: Gingerbread, calories: 356 }, { name: Jelly bean, calories: 375 }, { name: Lollipop, calories: 392 }, { name: Honeycomb, calories: 408 }, { name: Donut, calories: 452 }, { name: KitKat, calories: 518 }, ], } }, } /script要点说明数据仍由你自己管理这里用v-for渲染行v-table只负责外观与布局。官方示例中在th上使用了text-left工具类对齐表头文字这是 Vuetify 内置的文本对齐 utility。源码中表头单元格默认text-align: start见 VTable.sass即默认靠左对齐符合 Material Design 数据表格规范。Props 全解析从主题到斑马纹v-table的 Props 定义在 VTable.tsx 的makeVTableProps中共 6 个专属 Props外加从 composables 混入的tag、theme、density、class、style等通用 Props。下面逐一展开。theme切换表格主题通过themeprop 可以将表格切换到另一套主题如暗色无需改变全局主题配置。示例prop-dark.vuev-table themedark !-- thead / tbody 内容同上 -- /v-table底层实现theme来自makeThemeProps在 setup 中通过provideTheme(props)提供主题上下文VTable.tsx生成的themeClasses会追加到根元素的 class 列表上。表格背景与文字颜色由 Sass 变量$table-backgroundrgb(var(--v-theme-surface))与$table-colortheme-color(on-surface, var(--v-high-emphasis-opacity))控制见 _variables.scss因此切换主题时颜色会随 CSS 变量自动联动。density表格密度densityprop 控制行高与表头高度取值与全局密度体系一致default、comfortable、compact。示例prop-dense.vuev-table densitycompact !-- 更紧凑的行间距 -- /v-table底层实现密度通过useDensity(props)composable 计算densityClasses在 VTable.sass 中通过tools.density(v-table, $table-density)生成带修饰符的 CSS 变量include tools.density(v-table, $table-density) using ($modifier) --v-table-header-height: #{$table-header-height $modifier} --v-table-row-height: #{$table-row-height $modifier}配合 _variables.scss 中$table-density: (default: 0, comfortable: -2, compact: -4)可以算出三种密度下精确的行高| density | 表头高度默认 56px 修正值 | 行高默认 52px 修正值 | | - | - | - | | default | 56px | 52px | | comfortable | 54px | 50px | | compact | 52px | 48px |height固定表格高度heightprop 接受数字或字符串如300px用于设置表格整体高度。示例prop-height.vuev-table height300px !-- 内容超出 300px 时表格内部滚动 -- /v-table底层实现设置 height 后组件会额外追加v-table--fixed-height类VTable.tsx并将高度值通过convertToUnit转为 CSS 长度应用到.v-table__wrapper的style.heightVTable.tsx。同时 VTable.sass 为v-table--fixed-height设置了overflow-y: auto实现内容溢出时仅表格区域滚动。fixed-header固定表头fixed-headerprop 需与height配合使用将表头固定在表格顶部滚动内容时表头保持可见。示例prop-fixed-header.vuev-table height300px fixed-header !-- 表头固定tbody 内容滚动 -- /v-table底层实现这里用到了 CSSposition: sticky见 VTable.sass.v-table--fixed-header .v-table__wrapper table thead position: sticky top: 0 z-index: 2同时表头单元格会获得background: $table-background与box-shadow: inset 0 -1px 0 $table-border-colorVTable.sass保证滚动时表头不透明且与内容区有清晰分隔线。z-index: 2确保表头始终覆盖在滚动的行内容之上。striped斑马纹stripedprop 为表格行添加交替背景色取值为even或odd分别对应偶数行、奇数行着色。示例prop-striped.vuev-table stripedeven !-- 偶数行应用条纹背景 -- /v-table底层实现源码中striped的 validator 只接受even与oddVTable.tsx渲染时对应追加v-table--striped-even或v-table--striped-odd类VTable.tsx。样式通过nth-child(even/odd)选择器实现VTable.sass.v-table--striped-even .v-table__wrapper table tbody tr:nth-child(even) background-image: linear-gradient(0deg, $table-stripe-color, $table-stripe-color)条纹颜色由 Sass 变量$table-stripe-color控制默认值为rgba(var(--v-border-color), var(--v-hover-opacity))_variables.scss。官方文档特别提示条纹颜色可通过 Sass 变量进一步调整详见下文通过 Sass 变量定制。其他 Props源码中还提供了文档示例之外的一些 Props一并说明| Prop | 类型 | 默认值 | 说明 | | - | - | - | - | |gridlines|Boolean \| horizontal \| vertical \| all|horizontal| 表格网格线方向。传true等价于all横竖都有传false则无网格线none。校验逻辑见 VTable.tsx | |fixed-footer|Boolean|false| 固定表尾tfoot与fixed-header对称同样基于position: sticky; bottom: 0VTable.sass | |hover|Boolean|false| 行悬停高亮。实现上通过td::after绝对定位覆盖层叠加$table-hover-colorVTable.sass因此不会影响单元格内容 | |tag|String|div| 根元素标签来自makeTagProps默认渲染为div包裹table| |class/style| - | - | 来自makeComponentProps透传到根元素 |Slots 全解析VTableSlots类型定义了 5 个插槽VTable.tsx| 插槽 | 说明 | 渲染位置 | | - | - | - | |default| 表格主体内容thead、tbody、tfoot等渲染进原生table内部 |.v-table__wrapper table| |caption| 表格标题渲染进table内的caption位置 |table内部最前 | |top| 表格顶部扩展区渲染在 wrapper 之前 | 根元素下、wrapper 外 | |bottom| 表格底部扩展区渲染在 wrapper 之后 | 根元素下、wrapper 外 | |wrapper| 自定义整个 wrapper 区域仅在未提供default插槽时生效 | 替代.v-table__wrapper|从 VTable.tsx 的渲染逻辑可见当存在top/bottom插槽时组件会自动追加v-table--has-top/v-table--has-bottom类VTable.sass将 wrapper 的对应圆角清零保证顶部/底部区域与表格区视觉上融为一体。典型用法用top插槽放工具栏搜索框、操作按钮用bottom插槽放分页或摘要信息v-table template #top div classpa-4表格工具栏/div /template thead…/thead tbody…/tbody template #bottom div classpa-4共 10 条记录/div /template /v-table通过 Sass 变量定制官方文档明确指出 striped 的配色can be further adjusted using sass variables可通过 Sass 变量进一步调整。实际上v-table的全部视觉细节都集中定义在 _variables.scss 中支持在项目中覆盖| Sass 变量 | 默认值 | 作用 | | - | - | - | |$table-background|rgb(var(--v-theme-surface))| 表格背景色随主题变量联动 | |$table-color|theme-color(on-surface, var(--v-high-emphasis-opacity))| 文字颜色 | |$table-density|(default: 0, comfortable: -2, compact: -4)| 三种密度对应的行高/表头高修正值 | |$table-header-height|56px| 表头高度基准值 | |$table-header-font-weight|500| 表头字重 | |$table-row-height|52px| 行高基准值 | |$table-border-color|rgba(var(--v-border-color), var(--v-border-opacity))| 网格线/边框颜色 | |$table-border|thin solid $table-border-color| 边框样式 | |$table-hover-color|rgba(var(--v-border-color), var(--v-hover-opacity))| 悬停高亮色 | |$table-stripe-color|rgba(var(--v-border-color), var(--v-hover-opacity))| 斑马纹颜色 | |$table-transition-duration|0.28s| 过渡动画时长 | |$table-line-height|1.5| 行高line-height | |$table-column-padding|0 16px| 单元格内边距 |覆盖方式是在你的全局样式中、引入 Vuetify 样式之前重新赋值例如// 自定义 v-table 变量 $table-stripe-color: rgba(99, 102, 241, 0.08); $table-header-font-weight: 600; $table-column-padding: 0 24px; // 之后再引入 Vuetify 样式 use vuetify with (...)所有变量均带!default声明因此可以被安全覆盖而不会报重复定义错误。表格过渡动画的时长、属性与缓动函数$table-transition-duration/$table-transition-property/$table-transition-timing-function默认作用于box-shadow, opacity, background, height在斑马纹、悬停等状态切换时提供平滑过渡VTable.sass。源码实现要点渲染结构与可访问性从 VTable.tsx 可以提炼几个值得注意的实现细节根元素为 divtable 包在 wrapper 中v-table根元素默认是divflex 纵向布局max-width: 100%内部.v-table__wrapper承担滚动容器职责overflow: autoVTable.sass。这样做的好处是固定高度时滚动发生在 wrapper 层而表头 sticky 定位与圆角裁剪都能精确控制。gridlines 的归一化处理gridlines为布尔值时会被归一化为alltrue或nonefalse最终以v-table--gridlines-{none|horizontal|vertical|all}类名输出VTable.tsx水平网格线作用于th的border-bottom与行间border-bottom垂直网格线作用于th:not(:last-child)/td:not(:last-child)的border-rightVTable.sass。aria-label 透传组件通过pickWithRest(attrs, [/^aria-label/])将aria-label属性单独提取并透传到原生table元素上VTable.tsx其余属性落在根元素上。这意味着无障碍标注可以精准作用于语义化表格本体v-table aria-label月度销售数据 … /v-table主题与密度的复用theme与density均来自 Vuetify 通用 composablesprovideTheme/useDensity与全组件库的密度、主题体系完全统一因此v-table可以无缝嵌入不同主题的应用而无需额外配置。小结与选型建议v-table的设计哲学是轻原生表格结构 精选的视觉增强 Props。适合以下场景静态或仅需展示的数据列表无需排序、筛选、分页需要固定表头、固定高度滚动、斑马纹、悬停高亮等视觉特性的纯展示表格希望用最小改动把现有 HTML 表格升级为 Material Design 风格。而当你需要列排序、分页、服务端数据加载、行选择等能力时应升级到v-data-table系列组件。在 Vuetify 生态中v-table与v-data-table分别覆盖轻量展示与数据密集型两类需求配合使用即可应对绝大多数表格场景。进一步阅读当前仓库中的相关资源组件源码VTable.tsx组件样式VTable.sass样式变量_variables.scss官方文档原文tables.md全部官方示例packages/docs/src/examples/v-table含 usage、prop-dark、prop-dense、prop-height、prop-fixed-header、prop-striped 六个示例【免费下载链接】vuetify Vue Component Framework项目地址: https://gitcode.com/gh_mirrors/vu/vuetify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考