vue3-el-table-sticky-plugin

English | 简体中文

一个用于 Element Plus el-table 的 Vue 3 指令插件，让表头在页面滚动或业务容器滚动时保持吸顶。

文档入口

• 中文文档：https://xcy960815.github.io/vue3-el-table-sticky-plugin/zh-CN/
• 在线演示：https://xcy960815.github.io/vue3-el-table-sticky-plugin/zh-CN/guide/demo
• English docs: https://xcy960815.github.io/vue3-el-table-sticky-plugin/

特性

• 支持 el-table 表头吸顶，不侵入表格数据和列配置。
• 支持默认页面滚动，也支持指定业务滚动容器。
• 支持多个表格实例同时使用，状态按表格实例隔离。
• 支持监听外部区域尺寸变化后重新计算吸顶位置。
• 自动处理挂载、更新、卸载时的事件监听和 ResizeObserver 清理。
• 内置 TypeScript 类型声明。

环境要求

• Vue ^3.2.13
• Element Plus 2.x
• Node ^20.19.0 || >=22.12.0，仅用于本仓库开发和构建

安装

npm install vue3-el-table-sticky-plugin

pnpm add vue3-el-table-sticky-plugin

快速开始

import { createApp } from 'vue';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';
import Vue3TableStickyPlugin from 'vue3-el-table-sticky-plugin';

import App from './App.vue';

const app = createApp(App);

app.use(ElementPlus);
app.use(Vue3TableStickyPlugin);
app.mount('#app');

在 el-table 上使用 v-sticky：

<template>
  <div class="page-scroll">
    <div class="toolbar">
      <!-- 筛选项、操作按钮、动态内容 -->
    </div>

    <el-table
      v-sticky="{
        offsetTop: 0,
        scrollTarget: '.page-scroll',
        observe: ['.toolbar'],
        boundary: 'table',
      }"
      :data="tableData"
      border
    >
      <el-table-column prop="date" label="Date" width="180" />
      <el-table-column prop="name" label="Name" width="180" />
      <el-table-column prop="address" label="Address" />
    </el-table>
  </div>
</template>

<script setup lang="ts">
const tableData = [
  {
    date: '2016-05-03',
    name: 'Tom',
    address: 'No. 189, Grove St, Los Angeles',
  },
];
</script>

<style scoped>
.page-scroll {
  height: 100%;
  overflow-y: auto;
}
</style>

配置项

v-sticky 接收一个对象：

interface StickyOptions {
  offsetTop?: number | (() => number);
  scrollTarget?: string | HTMLElement | Window;
  boundary?: 'table' | 'scroll-container' | string | HTMLElement;
  observe?: Array<string | HTMLElement>;
  strategy?: 'auto' | 'fixed' | 'sticky';
  zIndex?: number | 'auto';
  activeClass?: string;

  /** @deprecated 请使用 offsetTop。 */
  top?: number;
  /** @deprecated 请使用 scrollTarget。 */
  parent?: string;
  /** @deprecated 请使用 observe。 */
  willBeChangeElementClasses?: string[];
}

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | offsetTop | number \| (() => number) | 当前表头距离视口顶部的位置 | 表头吸顶后距离当前滚动视口顶部的距离。 | | scrollTarget | string \| HTMLElement \| Window | 最近可滚动祖先，其次是 window | 用于吸顶计算的滚动容器。 | | boundary | 'table' \| 'scroll-container' \| string \| HTMLElement | 'table' | 触达底部后释放吸顶表头的边界元素。 | | observe | Array<string \| HTMLElement> | [] | 会影响吸顶位置的元素列表；这些元素尺寸变化时会触发布局重算。 | | strategy | 'auto' \| 'fixed' \| 'sticky' | 'auto' | 预留策略配置；当前引擎使用 fixed 定位渲染。 | | zIndex | number \| 'auto' | 'auto' | 表头吸顶时的层级。 | | activeClass | string | 'fixed' | 表头吸顶时添加的 class。 | | top | number | - | 已废弃，作为 offsetTop 的兼容别名。 | | parent | string | - | 已废弃，作为 scrollTarget 的兼容别名。 | | willBeChangeElementClasses | string[] | - | 已废弃，作为 observe 的兼容别名。 |

配置优先级：

1. 指令参数，例如 v-sticky="{ offsetTop: 64 }"。
2. 插件安装参数，例如 app.use(Vue3TableStickyPlugin, { offsetTop: 64 })。
3. 插件默认值。

全局默认配置

可以在安装插件时设置默认参数：

app.use(Vue3TableStickyPlugin, {
  offsetTop: 64,
  scrollTarget: '.app-main',
});

指令参数会覆盖全局默认配置：

<el-table
  v-sticky="{
    offsetTop: 0,
    scrollTarget: '.page-scroll',
  }"
/>

滚动容器规则

插件会监听 scrollTarget 指定的滚动容器。表格必须位于该容器内部，并且这个容器必须是真正发生滚动的元素。如果没有传 scrollTarget，插件会自动查找最近的可滚动祖先，找不到时回退到 window。

推荐写法：

.page-scroll {
  height: 100%;
  overflow-y: auto;
}

如果要测试外层业务容器滚动，不要给 el-table 设置固定 height。Element Plus 在设置 height 后会让表格 body 内部滚动，而插件监听的是你指定的外层 parent，两者不一致时吸顶不会触发。

Demo 路由

仓库内置 Vite demo，每个测试场景一个地址：

| 地址 | 场景 | | ------------------ | -------------------------------------- | | /#/basic-body | 默认 body 滚动。 | | /#/parent-scroll | 指定父级滚动容器。 | | /#/multi-table | 同一滚动容器内多个吸顶表格。 | | /#/dynamic-top | 顶部工具栏高度变化后重新计算吸顶位置。 |

启动 demo：

pnpm install
pnpm dev

启动文档站：

pnpm docs:dev

项目结构

plugin/     插件源码
src/        Vite demo 应用
types/      打包后的 TypeScript 类型声明
dist/       插件构建产物

常用命令

pnpm dev            # 启动 Vite demo
pnpm docs:dev       # 启动 VitePress 文档站
pnpm docs:build     # 构建文档站
pnpm build          # 构建插件包
pnpm build:plugin   # 构建插件 JS 和类型声明
pnpm build:demo     # 构建 demo 应用
pnpm lint           # 运行 ESLint
pnpm format:check   # 检查 Prettier 格式

构建产物

包入口包括：

• dist/vue3-el-table-sticky-plugin.esm.js
• dist/vue3-el-table-sticky-plugin.umd.js
• types/vue3-el-table-sticky-plugin.d.ts

注意事项

• scrollTarget、boundary 和 observe 在接收选择器的位置都支持 CSS 选择器。
• parent 和 willBeChangeElementClasses 仍作为已废弃兼容别名可用。
• 无效选择器会被忽略，并在控制台输出 warning。
• 可选监听元素不存在时不会阻断页面渲染。
• 吸顶激活时，插件会在 Element Plus 表头 wrapper 上添加 fixed class，并在取消吸顶时移除。

License

MIT