varlet Table 表格组件完全指南:从基本表格、弱背景色到固定表头的实现与定制

原创2026-10-15 09:19:511,887 阅读
文章标签:UI组件前端

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

长表格 + 分页 + 固定表头是文档给出的进阶组合。核心是两步:

  1. 给 var-table 设置 scroller-height="400px",让 __main 滚动容器获得最大高度,纵向滚动被限制在表格内部;
  2. 给 <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 变量的覆写能力,它覆盖了数据展示场景从轻量清单到带分页、固定表头的长表格的典型需求。

登录后查看全文
varlet