varlet Table 表格组件完全指南:从基本表格、弱背景色到固定表头的实现与定制
varlet Table 表格组件完全指南:从基本表格、弱背景色到固定表头的实现与定制
本文围绕 varlet(基于 Material Design 2/3 的 Vue 3 组件库)中的表格组件 var-table 展开。它定位为"一个极简的表格",当你需要以表格形式展示数据时可以使用它。读完本文,你将掌握:plain、bordered、surface="low" 等多种表格形态的写法,footer 插槽搭配 var-pagination 实现分页的完整示例,scroller-height 配合 position: sticky 实现固定表头与纵向局部滚动的原理,以及组件全部的属性、插槽、样式变量和基于 StyleProvider 的样式定制方式。
组件结构与源码走读
在开始写代码之前,先理解 var-table 的 DOM 结构,有助于后面理解"固定表头为什么能 work"。查看 Table.vue 的模板部分,组件整体是"三层"结构:
<div :class="..."> <!-- 外层容器:承载 elevation、plain、bordered 等修饰类 -->
<div :class="n('main')" <!-- .var-table__main:滚动容器,max-height 由 scroller-height 控制 -->
:style="{ 'max-height': toSizeUnit(scrollerHeight) }">
<table :class="n('table')" :style="{ width: toSizeUnit(fullWidth) }">
<slot /> <!-- 默认插槽:放置 thead/tbody -->
</table>
</div>
<div v-if="$slots.footer" :class="n('footer')">
<slot name="footer" /> <!-- footer 插槽:无内容时不渲染 -->
</div>
</div>
从源码结构看,有几个关键点:
- 滚动发生在
__main容器上:table.less 中.var-table__main设置了overflow: auto,而<table>元素本身min-width: 100%。因此横向列数过多、或纵向设置scroller-height时,滚动条都出现在该容器内,这也是固定表头方案的基础。 - elevation 类受
plain控制:模板中类名逻辑为<a href="https://link.gitcode.com/i/1806b00b45cc13c67fa09497589ae3eb" target="_blank">!plain, formatElevation(elevation, 1)]。[formatElevation 在elevation === false时返回null(无阴影),在elevation === true且提供了默认等级时取默认值。Table 传入的默认等级是1,所以默认渲染出var-elevation--1;设置plain后该 elevation 类被整体去掉。 - 尺寸属性统一走
toSizeUnit:toSizeUnit 的规则是"数字自动补px,字符串原样透传"。因此full-width和scroller-height既可以传数字(如400,等价于400px),也可以传带单位的字符串(如"400px"、"50%")。 - footer 按需渲染:
v-if="$slots.footer"保证没有传footer插槽时不产生多余的 DOM 节点,这一点在 index.spec.js 中"should not render footer without footer slot"用例里有明确断言。
基本使用
最简单的使用方式:直接用原生 thead/tbody 结构填充默认插槽,不需要任何数据绑定配置。
<template>
<var-table>
<thead>
<tr>
<th>姓名</th>
<th>数学</th>
<th>英语</th>
</tr>
</thead>
<tbody>
<tr>
<td>耗子君</td>
<td>124</td>
<td>38</td>
</tr>
<tr>
<td>火猫桑</td>
<td>100</td>
<td>135</td>
</tr>
</tbody>
</var-table>
</template>
该示例与仓库中的 示例文件 "基本使用"一节完全一致。渲染效果是一张带白色背景、圆角(--table-border-radius: 2px)、默认 1 级 elevation 阴影的卡片式表格,行高 46px,单元格内边距 8px 16px,行悬停有浅灰背景过渡(transition: background-color 0.25s)。
纯表格:plain 属性
设置 plain 可以一并去掉卡片阴影、背景色和圆角:
<template>
<var-table plain>
<thead>
<tr>
<th>姓名</th>
<th>数学</th>
<th>英语</th>
</tr>
</thead>
<tbody>
<tr>
<td>耗子君</td>
<td>124</td>
<td>38</td>
</tr>
<tr>
<td>火猫桑</td>
<td>100</td>
<td>135</td>
</tr>
</tbody>
</var-table>
</template>
源码层面,plain 通过 .var-table--plain 修饰类完成三件事(见 table.less):
&--plain {
--table-background: transparent; // 去掉背景色
--table-tbody-tr-hover-background: var(--table-plain-row-hover-background);
// 悬停色改为低透明度的 on-surface 叠加
border-radius: 0; // 去掉圆角
}
同时模板中的 [!plain, formatElevation(elevation, 1)] 会移除 elevation 阴影类,所以"卡片感"被彻底剥离。测试用例 index.spec.js 断言了 plain: true 时类列表包含 var-table--plain 且不包含 var-elevation--1,印证了上述行为。
Plain + Bordered:更纯粹的表格形态
同时使用 plain 和 bordered,可以用外边框展示更纯粹的表格形态:
<template>
<var-table plain bordered>
<thead>
<tr>
<th>姓名</th>
<th>数学</th>
<th>英语</th>
</tr>
</thead>
<tbody>
<tr>
<td>耗子君</td>
<td>124</td>
<td>38</td>
</tr>
<tr>
<td>火猫桑</td>
<td>100</td>
<td>135</td>
</tr>
</tbody>
</var-table>
</template>
样式上有两处细节值得注意:
.var-table--bordered只加一条外边框:border: var(--table-border),其中--table-border默认值为thin solid var(--color-outline);- 单独使用
plain时border-radius被置0,但.var-table--plain&--bordered规则会把圆角恢复为var(--table-border-radius)(默认2px),即"纯 + 边框"形态仍保留轻微圆角。
测试中 "table plain bordered" 用例同时断言了两个修饰类共存,行为与文档一致。
弱背景色:surface="low"
通过 surface="low" 使用更接近 MD3(Material Design 3)的弱背景层级:
<template>
<var-table surface="low">
<thead>
<tr>
<th>姓名</th>
<th>数学</th>
<th>英语</th>
</tr>
</thead>
<tbody>
<tr>
<td>耗子君</td>
<td>124</td>
<td>38</td>
</tr>
<tr>
<td>火猫桑</td>
<td>100</td>
<td>135</td>
</tr>
</tbody>
</var-table>
</template>
实现上,surface="low" 会加上 .var-table--surface-low 类(Table.vue 中 surfaceLow = computed(() => props.surface === 'low')),该修饰类通过覆盖局部 CSS 变量生效,而不是重写具体选择器:
&--surface-low {
--table-background: var(--table-surface-low-background);
--table-tbody-tr-hover-background: var(--table-surface-low-row-hover-background);
}
而 --table-surface-low-background 的默认值是 var(--color-surface-container-highest),即直接引用 varlet 的全局色板变量(MD3 的 surface container 层级)。因此当项目切换主题色时,弱背景会随之联动。从 props.ts 可见 surface 目前类型上只接受 'low' 一个取值(TableSurface = 'low')。
尾部插槽:搭配分页组件
可以在 footer 插槽中插入一些东西,最常见的是插入分页组件。下面是一个完整可运行的示例(数据按需生成,翻页时重新拉取当前页数据):
<script setup>
import { ref } from 'vue'
const list = ref(gen(1, 10))
function gen(current, size) {
return Array.from({ length: size }).map((_, index) => {
const id = (current - 1) * size + index + 1
return {
name: `Name ${id}`,
math: id,
english: id,
}
})
}
function get(current, size) {
list.value = gen(current, size)
}
</script>
<template>
<var-table>
<thead>
<tr>
<th>姓名</th>
<th>数学</th>
<th>英语</th>
</tr>
</thead>
<tbody>
<tr v-for="l in list" :key="l.name">
<td>{{ l.name }}</td>
<td>{{ l.math }}</td>
<td>{{ l.english }}</td>
</tr>
</tbody>
<template #footer>
<div class="table-example-footer">
<var-pagination
:simple="false"
:current="1"
:total="100"
:size-option="[5, 10]"
@change="get"
/>
</div>
</template>
</var-table>
</template>
<style>
.table-example-footer {
display: flex;
justify-content: flex-end;
align-items: center;
height: 60px;
padding: 0 16px;
}
</style>
关于 footer 区域的布局约束,table.less 中 .var-table__footer 定义了:
&__footer {
width: 100%;
min-height: var(--table-row-height); // 最小高度与行高一致(默认 46px)
border-top: var(--table-footer-border-top);
background: var(--table-background);
}
即 footer 自带与表格背景一致的背景色和一条顶部分隔线,内部如何排布(如上面示例的 flex 右对齐)由使用者自己控制。由于 footer 位于 __main 滚动容器之外,它始终固定在表格底部,不随表体滚动——这与"固定表头"形成上下呼应的常见组合。
固定表头:scroller-height + sticky
长表格 + 分页 + 固定表头是文档给出的进阶组合。核心是两步:
- 给
var-table设置scroller-height="400px",让__main滚动容器获得最大高度,纵向滚动被限制在表格内部; - 给
<thead>加内联样式position: sticky; top: 0,让表头在容器内滚动时保持吸顶。
<script setup>
import { ref } from 'vue'
const list = ref(gen(1, 10))
function gen(current, size) {
return Array.from({ length: size }).map((_, index) => {
const id = (current - 1) * size + index + 1
return {
name: `Name ${id}`,
math: id,
english: id,
}
})
}
function get(current, size) {
list.value = gen(current, size)
}
</script>
<template>
<var-table scroller-height="400px">
<thead style="position: sticky; top: 0">
<tr>
<th>姓名</th>
<th>数学</th>
<th>英语</th>
</tr>
</thead>
<tbody>
<tr v-for="l in list" :key="l.name">
<td>{{ l.name }}</td>
<td>{{ l.math }}</td>
<td>{{ l.english }}</td>
</tr>
</tbody>
<template #footer>
<div class="table-example-footer">
<var-pagination
:simple="false"
:current="1"
:total="100"
:size-option="[5, 10]"
@change="get"
/>
</div>
</template>
</var-table>
</template>
<style>
.table-example-footer {
display: flex;
justify-content: flex-end;
align-items: center;
height: 60px;
padding: 0 16px;
}
</style>
从源码结构看,这个方案能成立有三层原因:
- 滚动容器是
.var-table__main(overflow: auto),sticky元素(thead)相对于最近的滚动祖元素定位,top: 0即吸附在该容器顶部; - 样式里
thead tr有background: var(--table-background)不透明背景,吸顶时表头能完全遮挡下方滚过的表体行,不会出现"透底"; scroller-height支持数字和字符串两种写法。测试用例分别验证了scrollerHeight: '300px'和scrollerHeight: 300(经toSizeUnit转为300px),最终都落在.var-table__main的max-height内联样式上。
另外 table.less 中 .var-table 通过 --scrollbar-track-background: var(--table-background) 配合 styles/common.less 的通用滚动条样式,把滚动条轨道背景与表格背景色统一,视觉上更干净。
API 参考
属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
full-width |
table 的宽度(包含可滚动部分) |
string | number |
100% |
elevation |
海拔高度,可选值为 true false 和 0-24 的等级 |
string | number | boolean |
true |
plain |
是否以纯表格形态渲染,不带卡片阴影、背景色和圆角 | boolean |
false |
bordered |
是否显示外边框 | boolean |
false |
surface |
弱背景色风格 | 'low' |
- |
scroller-height 3.2.0 |
滚动容器高度,可用于实现纵向局部滚动,固定表头等功能 | string | number |
- |
几个结合源码可以补充的细节:
elevation:true表示默认的 1 级阴影(var-elevation--1,由formatElevation(elevation, 1)的默认等级决定);false完全关闭阴影;0-24的数字/字符串对应 MD 的 elevation 等级(如3渲染为var-elevation--3)。测试用例 "table elevation" 验证了true与3两种取值的类名输出。full-width:最终作用在内部<table>元素的width内联样式上,数字自动补px。测试用例 "table full-Width" 断言默认输出width: 100%;、传200后输出width: 200px;。scroller-height自3.2.0版本引入,缺省时__main无max-height限制,表格随内容自然撑开。
TypeScript 类型定义见 types/table.d.ts,TableProps 接口与上表一一对应。
插槽
| 名称 | 说明 | 参数 |
|---|---|---|
default |
Table 的内容 | - |
footer |
Table 尾部内容 | - |
default 插槽承载 thead/tbody 等标准表格内容,渲染在 __main 滚动容器内;footer 插槽位于滚动容器之外,未提供时不渲染 DOM。两个插槽的行为均有对应测试断言("table default slot"、"table footer slot"、"table default and footer slots")。
样式变量
以下为组件使用的 CSS 变量,可以使用 StyleProvider 组件(style-provider 组件源码)进行样式定制:
| 变量名 | 默认值 |
|---|---|
--table-background |
#fff |
--table-surface-low-background |
var(--color-surface-container-highest) |
--table-surface-low-row-hover-background |
var(--color-surface-container-highest) |
--table-plain-row-hover-background |
hsla(var(--hsl-on-surface), 0.04) |
--table-border-radius |
2px |
--table-border |
thin solid var(--color-outline) |
--table-thead-border-bottom |
thin solid var(--color-outline) |
--table-thead-th-text-color |
rgba(0, 0, 0, 0.6) |
--table-thead-th-text-align |
left |
--table-thead-th-font-size |
14px |
--table-thead-th-font-weight |
500 |
--table-thead-tr-border-bottom |
thin solid var(--color-outline) |
--table-tbody-tr-hover-background |
#f5f5f5 |
--table-tbody-tr-border-bottom |
thin solid var(--color-outline) |
--table-tbody-td-text-color |
#555 |
--table-tbody-td-font-size |
14px |
--table-tbody-td-text-align |
left |
--table-row-height |
46px |
--table-row-padding |
8px 16px |
--table-footer-border-top |
thin solid var(--color-outline) |
这些默认值声明在 table.less 顶部的 :root 块中,与文档表格逐项一致。由于 plain、surface="low" 等形态本质上只是覆盖 --table-background、--table-tbody-tr-hover-background 等少数变量,因此通过 StyleProvider 覆盖变量时,三种形态会共享同一套定制结果,这是"变量驱动样式"设计带来的好处:改一个变量,表头、表体、悬停、footer 分隔线统一联动。
全局默认值与按需引入
components 入口 index.ts 除了标准的 withInstall(Table) 注册逻辑外,还调用了 withPropsDefaultsSetter(Table, tableProps) 并导出 tableProps,这意味着你可以像其他 varlet 组件一样,通过 Table.setPropsDefaults 在整个应用范围内覆盖 Table 的默认属性(例如全局关闭阴影)。TypeScript 侧的 Table 类同样声明了 static setPropsDefaults: SetPropsDefaults<TableProps>(见 types/table.d.ts)。
小结
var-table 的设计思路是"极简容器 + 原生表格语义 + CSS 变量定制":组件本身只负责滚动容器、elevation 卡片、形态修饰类和 footer 区域,thead/tbody 的具体内容完全交给使用者用标准 HTML 表格标签书写。配合 plain/bordered/surface="low" 三种形态开关、scroller-height 局部滚动与 sticky 表头,以及 StyleProvider 对 21 个 CSS 变量的覆写能力,它覆盖了数据展示场景从轻量清单到带分页、固定表头的长表格的典型需求。