@leslie1900/el-table-horizontal-scroll 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wang Ming
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# el-table-horizontal-scroll
+
+一个专门为 Element Plus Table (Vue 3) 优化横向滚动条体验的自定义指令。
+
+## 特性
+
+- 🚀 **悬浮式滚动条**：当表格超出屏幕宽度且底部在视口外时，会在屏幕底部生成一个固定的横向滚动条，方便用户在任何位置进行横向滚动。
+- 🖱️ **完美交互**：支持在悬浮滚动条上直接点击轨道进行平滑滚动、拖动滑块进行任意位置滚动，并与表格原生的横向滚动保持完美的双向同步。
+- 🍃 **自动销毁**：自动监听容器大小变化与可见性变化，并在指令解绑时释放所有 DOM 节点与事件监听器，避免内存泄漏。
+- 📦 **开箱即用**：支持 Vue 3 全局注册与局部导入。
+
+## 安装
+
+使用 npm 或 pnpm 安装：
+
+```bash
+npm install el-table-horizontal-scroll
+# 或者
+pnpm add el-table-horizontal-scroll
+```
+
+## 使用方式
+
+### 1. 全局注册
+
+在入口文件（例如 `main.ts` 或 `main.js`）中注册该插件：
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+import ElTableHorizontalScroll from 'el-table-horizontal-scroll'
+
+const app = createApp(App)
+app.use(ElTableHorizontalScroll)
+app.mount('#app')
+```
+
+### 2. 局部注册
+
+在单文件组件（SFC）中按需引入：
+
+```vue
+<script setup lang="ts">
+import { tableHorizontalScrollDirective as vTableHorizontalScroll } from 'el-table-horizontal-scroll'
+</script>
+
+<template>
+  <el-table v-table-horizontal-scroll ...>
+    <!-- ... -->
+  </el-table>
+</template>
+```
+
+### 3. 指令配置选项
+
+可以通过指令绑定的值来控制滚动条的显示行为：
+
+- **鼠标悬浮显示（默认）**：
+  ```html
+  <el-table v-table-horizontal-scroll>...</el-table>
+  <!-- 或者传入 'hover' -->
+  <el-table v-table-horizontal-scroll="'hover'">...</el-table>
+  ```
+  在鼠标移入表格时显示滚动滑块，移出时隐藏。
+
+- **始终显示**：
+  ```html
+  <el-table v-table-horizontal-scroll="'always'">...</el-table>
+  ```
+  只要表格存在横向滚动且底部处于视口下方，便一直显示悬浮滚动条。
+
+- **禁用优化**：
+  ```html
+  <el-table v-table-horizontal-scroll="false">...</el-table>
+  ```
+  传入 `false` 可在特定场景下动态禁用该指令。
+
+## 开源协议
+
+[MIT LICENSE](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,40 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const V=()=>{const e="el-table-horizontal-scrollbar-style";if(document.getElementById(e))return;const t=document.createElement("style");t.id=e,t.innerHTML=`
+    .el-table-horizontal-scrollbar {
+      position: fixed !important;
+      bottom: 0 !important;
+      height: 6px !important;
+      background-color: transparent !important;
+      z-index: 1000 !important;
+      cursor: pointer !important;
+      opacity: 0 !important;
+      pointer-events: none !important;
+      transform: scaleY(1) translateY(0) !important;
+      transform-origin: bottom !important;
+      transition: opacity 0.3s cubic-bezier(0.25, 1, 0.5, 1),
+                  transform 0.3s cubic-bezier(0.25, 1, 0.5, 1),
+                  background-color 0.3s cubic-bezier(0.25, 1, 0.5, 1) !important;
+    }
+    .el-table-horizontal-scrollbar.is-active {
+      opacity: 0.4 !important;
+      pointer-events: auto !important;
+    }
+    .el-table-horizontal-scrollbar.is-active:hover {
+      opacity: 0.8 !important;
+      transform: scaleY(1.5) translateY(-10%) !important;
+      background-color: rgba(0, 0, 0, 0.02) !important;
+    }
+    .el-table-horizontal-scrollbar__thumb {
+      position: absolute !important;
+      top: 0 !important;
+      left: 0 !important;
+      height: 100% !important;
+      border-radius: 4px !important;
+      background-color: var(--el-text-color-placeholder, rgba(144, 147, 153, 0.35)) !important;
+      cursor: pointer !important;
+      transform: translateX(0);
+      transition: background-color 0.2s ease !important;
+    }
+    .el-table-horizontal-scrollbar__thumb:hover {
+      background-color: var(--el-text-color-secondary, rgba(144, 147, 153, 0.55)) !important;
+    }
+  `,document.head.appendChild(t)},T=(e,t)=>{if(t.value===!1)return;V();const o=e.querySelector(".el-scrollbar__wrap"),E=e.querySelector(".el-scrollbar");if(!o||!E||e.__tableScrollData)return;const n=document.createElement("div");n.className="el-table-horizontal-scrollbar";const l=document.createElement("div");l.className="el-table-horizontal-scrollbar__thumb",n.appendChild(l),e.appendChild(n);const u=document.createElement("div");u.className="el-table-horizontal-scrollbar-sentinel",Object.assign(u.style,{height:"1px",marginTop:"-1px",visibility:"hidden",pointerEvents:"none"}),e.appendChild(u);const g=t.value==="always"?"always":"hover";let h=!1,y=!1,z=!1;const k=()=>{const r=o.clientWidth,i=o.scrollWidth,a=r*100/i;l.style.width=`${Math.min(a,100)}%`},S=()=>{const r=o.clientWidth,i=o.scrollWidth,a=o.scrollLeft,s=i-r,m=n.clientWidth-l.clientWidth;if(s<=0||m<=0){l.style.transform="translateX(0)";return}const d=a/s*m;l.style.transform=`translateX(${d}px)`},c=()=>{if(!o||!n)return;const r=E.getBoundingClientRect();o.scrollWidth>o.clientWidth&&y&&!z&&(g==="always"||h)?(n.classList.add("is-active"),n.style.width=`${r.width}px`,n.style.left=`${r.left}px`,k(),S()):n.classList.remove("is-active")},W=()=>{S()};o.addEventListener("scroll",W);const _=()=>{h=!0,c()},x=()=>{h=!1,c()};e.addEventListener("mouseenter",_),e.addEventListener("mouseleave",x);const O=r=>{if(r.ctrlKey||r.button===2)return;r.stopImmediatePropagation(),r.preventDefault();const i=r.clientX,a=o.scrollLeft,s=o.scrollWidth-o.clientWidth,m=n.clientWidth-l.clientWidth;if(s<=0||m<=0)return;const d=s/m,p=L=>{const X=L.clientX-i;o.scrollLeft=a+X*d},v=()=>{document.removeEventListener("mousemove",p),document.removeEventListener("mouseup",v),document.onselectstart=null};document.addEventListener("mousemove",p),document.addEventListener("mouseup",v),document.onselectstart=()=>!1};l.addEventListener("mousedown",O);const w=r=>{if(r.target===l)return;r.preventDefault();const i=n.getBoundingClientRect(),a=r.clientX-i.left,s=l.clientWidth,m=a-s/2,d=n.clientWidth-s,p=Math.max(0,Math.min(d,m)),v=o.scrollWidth-o.clientWidth;if(v<=0||d<=0)return;const L=v/d;o.scrollTo({left:p*L,behavior:"smooth"})};n.addEventListener("click",w);const I=new IntersectionObserver(([r])=>{y=r.isIntersecting,c()},{threshold:0});I.observe(e);const M=new IntersectionObserver(([r])=>{z=r.isIntersecting,c()},{threshold:0});M.observe(u);let b=null;const D=()=>{b===null&&(b=requestAnimationFrame(()=>{c(),b=null}))},R=()=>{b!==null&&(cancelAnimationFrame(b),b=null)},f=new ResizeObserver(()=>{D()});f.observe(e),f.observe(o),e.__tableScrollData={scrollWrap:o,barContainer:n,thumbEl:l,bottomIsVisibleObserverEl:u,tableIntersectionObserver:I,bottomIsVisibleObserver:M,resizeObserver:f,onTableScroll:W,onDragStart:O,onBarClick:w,onMouseEnter:_,onMouseLeave:x,updatePosition:c,cancelResize:R,mode:g,isMouseOverTable:h},c()},H=e=>{const t=e.__tableScrollData;t&&(t.tableIntersectionObserver&&t.tableIntersectionObserver.disconnect(),t.bottomIsVisibleObserver&&t.bottomIsVisibleObserver.disconnect(),t.resizeObserver&&t.resizeObserver.disconnect(),t.cancelResize&&t.cancelResize(),t.scrollWrap&&t.scrollWrap.removeEventListener("scroll",t.onTableScroll),t.onMouseEnter&&e.removeEventListener("mouseenter",t.onMouseEnter),t.onMouseLeave&&e.removeEventListener("mouseleave",t.onMouseLeave),t.thumbEl&&t.thumbEl.removeEventListener("mousedown",t.onDragStart),t.barContainer&&(t.barContainer.removeEventListener("click",t.onBarClick),t.barContainer.remove()),t.bottomIsVisibleObserverEl&&t.bottomIsVisibleObserverEl.remove(),delete e.__tableScrollData)},C={mounted(e,t){setTimeout(()=>{T(e,t)},150)},updated(e,t){setTimeout(()=>{const o=e.__tableScrollData;o?(o.mode=t.value==="always"?"always":"hover",o.updatePosition()):T(e,t)},150)},unmounted(e){H(e)}},P=e=>{e.directive("table-horizontal-scroll",C)},B={install:P};exports.default=B;exports.tableHorizontalScrollDirective=C;

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { App, Directive } from 'vue';
+
+interface TableScrollData {
+    scrollWrap: HTMLElement;
+    barContainer: HTMLElement;
+    thumbEl: HTMLElement;
+    bottomIsVisibleObserverEl: HTMLElement;
+    tableIntersectionObserver: IntersectionObserver;
+    bottomIsVisibleObserver: IntersectionObserver;
+    resizeObserver: ResizeObserver;
+    onTableScroll: () => void;
+    onDragStart: (e: MouseEvent) => void;
+    onBarClick: (e: MouseEvent) => void;
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    updatePosition: () => void;
+    cancelResize: () => void;
+    mode: 'hover' | 'always';
+    isMouseOverTable: boolean;
+}
+declare global {
+    interface HTMLElement {
+        __tableScrollData?: TableScrollData;
+    }
+}
+export declare const tableHorizontalScrollDirective: Directive;
+declare const _default: {
+    install: (app: App<any>) => void;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,190 @@
+const X = () => {
+  const e = "el-table-horizontal-scrollbar-style";
+  if (document.getElementById(e))
+    return;
+  const t = document.createElement("style");
+  t.id = e, t.innerHTML = `
+    .el-table-horizontal-scrollbar {
+      position: fixed !important;
+      bottom: 0 !important;
+      height: 6px !important;
+      background-color: transparent !important;
+      z-index: 1000 !important;
+      cursor: pointer !important;
+      opacity: 0 !important;
+      pointer-events: none !important;
+      transform: scaleY(1) translateY(0) !important;
+      transform-origin: bottom !important;
+      transition: opacity 0.3s cubic-bezier(0.25, 1, 0.5, 1),
+                  transform 0.3s cubic-bezier(0.25, 1, 0.5, 1),
+                  background-color 0.3s cubic-bezier(0.25, 1, 0.5, 1) !important;
+    }
+    .el-table-horizontal-scrollbar.is-active {
+      opacity: 0.4 !important;
+      pointer-events: auto !important;
+    }
+    .el-table-horizontal-scrollbar.is-active:hover {
+      opacity: 0.8 !important;
+      transform: scaleY(1.5) translateY(-10%) !important;
+      background-color: rgba(0, 0, 0, 0.02) !important;
+    }
+    .el-table-horizontal-scrollbar__thumb {
+      position: absolute !important;
+      top: 0 !important;
+      left: 0 !important;
+      height: 100% !important;
+      border-radius: 4px !important;
+      background-color: var(--el-text-color-placeholder, rgba(144, 147, 153, 0.35)) !important;
+      cursor: pointer !important;
+      transform: translateX(0);
+      transition: background-color 0.2s ease !important;
+    }
+    .el-table-horizontal-scrollbar__thumb:hover {
+      background-color: var(--el-text-color-secondary, rgba(144, 147, 153, 0.55)) !important;
+    }
+  `, document.head.appendChild(t);
+}, M = (e, t) => {
+  if (t.value === !1)
+    return;
+  X();
+  const o = e.querySelector(".el-scrollbar__wrap"), E = e.querySelector(".el-scrollbar");
+  if (!o || !E || e.__tableScrollData)
+    return;
+  const n = document.createElement("div");
+  n.className = "el-table-horizontal-scrollbar";
+  const s = document.createElement("div");
+  s.className = "el-table-horizontal-scrollbar__thumb", n.appendChild(s), e.appendChild(n);
+  const u = document.createElement("div");
+  u.className = "el-table-horizontal-scrollbar-sentinel", Object.assign(u.style, {
+    height: "1px",
+    marginTop: "-1px",
+    visibility: "hidden",
+    pointerEvents: "none"
+  }), e.appendChild(u);
+  const y = t.value === "always" ? "always" : "hover";
+  let v = !1, g = !1, z = !1;
+  const C = () => {
+    const r = o.clientWidth, i = o.scrollWidth, a = r * 100 / i;
+    s.style.width = `${Math.min(a, 100)}%`;
+  }, W = () => {
+    const r = o.clientWidth, i = o.scrollWidth, a = o.scrollLeft, l = i - r, m = n.clientWidth - s.clientWidth;
+    if (l <= 0 || m <= 0) {
+      s.style.transform = "translateX(0)";
+      return;
+    }
+    const d = a / l * m;
+    s.style.transform = `translateX(${d}px)`;
+  }, c = () => {
+    if (!o || !n)
+      return;
+    const r = E.getBoundingClientRect();
+    o.scrollWidth > o.clientWidth && g && !z && (y === "always" || v) ? (n.classList.add("is-active"), n.style.width = `${r.width}px`, n.style.left = `${r.left}px`, C(), W()) : n.classList.remove("is-active");
+  }, S = () => {
+    W();
+  };
+  o.addEventListener("scroll", S);
+  const x = () => {
+    v = !0, c();
+  }, _ = () => {
+    v = !1, c();
+  };
+  e.addEventListener("mouseenter", x), e.addEventListener("mouseleave", _);
+  const w = (r) => {
+    if (r.ctrlKey || r.button === 2)
+      return;
+    r.stopImmediatePropagation(), r.preventDefault();
+    const i = r.clientX, a = o.scrollLeft, l = o.scrollWidth - o.clientWidth, m = n.clientWidth - s.clientWidth;
+    if (l <= 0 || m <= 0)
+      return;
+    const d = l / m, p = (L) => {
+      const R = L.clientX - i;
+      o.scrollLeft = a + R * d;
+    }, h = () => {
+      document.removeEventListener("mousemove", p), document.removeEventListener("mouseup", h), document.onselectstart = null;
+    };
+    document.addEventListener("mousemove", p), document.addEventListener("mouseup", h), document.onselectstart = () => !1;
+  };
+  s.addEventListener("mousedown", w);
+  const I = (r) => {
+    if (r.target === s)
+      return;
+    r.preventDefault();
+    const i = n.getBoundingClientRect(), a = r.clientX - i.left, l = s.clientWidth, m = a - l / 2, d = n.clientWidth - l, p = Math.max(0, Math.min(d, m)), h = o.scrollWidth - o.clientWidth;
+    if (h <= 0 || d <= 0)
+      return;
+    const L = h / d;
+    o.scrollTo({
+      left: p * L,
+      behavior: "smooth"
+    });
+  };
+  n.addEventListener("click", I);
+  const O = new IntersectionObserver(
+    ([r]) => {
+      g = r.isIntersecting, c();
+    },
+    { threshold: 0 }
+  );
+  O.observe(e);
+  const T = new IntersectionObserver(
+    ([r]) => {
+      z = r.isIntersecting, c();
+    },
+    { threshold: 0 }
+  );
+  T.observe(u);
+  let b = null;
+  const k = () => {
+    b === null && (b = requestAnimationFrame(() => {
+      c(), b = null;
+    }));
+  }, D = () => {
+    b !== null && (cancelAnimationFrame(b), b = null);
+  }, f = new ResizeObserver(() => {
+    k();
+  });
+  f.observe(e), f.observe(o), e.__tableScrollData = {
+    scrollWrap: o,
+    barContainer: n,
+    thumbEl: s,
+    bottomIsVisibleObserverEl: u,
+    tableIntersectionObserver: O,
+    bottomIsVisibleObserver: T,
+    resizeObserver: f,
+    onTableScroll: S,
+    onDragStart: w,
+    onBarClick: I,
+    onMouseEnter: x,
+    onMouseLeave: _,
+    updatePosition: c,
+    cancelResize: D,
+    mode: y,
+    isMouseOverTable: v
+  }, c();
+}, V = (e) => {
+  const t = e.__tableScrollData;
+  t && (t.tableIntersectionObserver && t.tableIntersectionObserver.disconnect(), t.bottomIsVisibleObserver && t.bottomIsVisibleObserver.disconnect(), t.resizeObserver && t.resizeObserver.disconnect(), t.cancelResize && t.cancelResize(), t.scrollWrap && t.scrollWrap.removeEventListener("scroll", t.onTableScroll), t.onMouseEnter && e.removeEventListener("mouseenter", t.onMouseEnter), t.onMouseLeave && e.removeEventListener("mouseleave", t.onMouseLeave), t.thumbEl && t.thumbEl.removeEventListener("mousedown", t.onDragStart), t.barContainer && (t.barContainer.removeEventListener("click", t.onBarClick), t.barContainer.remove()), t.bottomIsVisibleObserverEl && t.bottomIsVisibleObserverEl.remove(), delete e.__tableScrollData);
+}, H = {
+  mounted(e, t) {
+    setTimeout(() => {
+      M(e, t);
+    }, 150);
+  },
+  updated(e, t) {
+    setTimeout(() => {
+      const o = e.__tableScrollData;
+      o ? (o.mode = t.value === "always" ? "always" : "hover", o.updatePosition()) : M(e, t);
+    }, 150);
+  },
+  unmounted(e) {
+    V(e);
+  }
+}, B = (e) => {
+  e.directive("table-horizontal-scroll", H);
+}, P = {
+  install: B
+};
+export {
+  P as default,
+  H as tableHorizontalScrollDirective
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@leslie1900/el-table-horizontal-scroll",
+  "version": "1.0.0",
+  "description": "A Vue 3 directive to optimize horizontal scrollbar for Element Plus table.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "element-plus",
+    "el-table",
+    "scrollbar",
+    "horizontal-scroll",
+    "directive"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "vue": "^3.5.17",
+    "vite": "^4.4.8",
+    "typescript": "^4.7.4",
+    "vite-plugin-dts": "^3.5.0"
+  }
+}