【js】浏览器滚动条优化组件OverlayScrollbars

前言

在前端，滚动条作为一个长期被吐槽却又不得不忍受的存在，几乎出现在每个页面里，却又几乎无法优雅地控制。

而且当你的开发系统是mac（隐藏滚动条模式），而生产环境则是古老的win......

就出现了完全没有"预料"到的整体UI风格和"操作系统默认"风格滚动条格格不入的尴尬问题反馈！

标准方案scrollbar-color

复制代码

scrollbar-color: #1677ff #f0f2f5;
scrollbar-width: thin;

能力非常有限：只能改颜色和粗细。

非标准方案 ::-webkit-scrollbar

复制代码

::-webkit-scrollbar {
  width: 8px;
}
::-webkit-scrollbar-thumb {
  background: #1677ff;
}

只能修改部分css属性，且仅在 WebKit 系浏览器上不起作用，未来也不确定~

如果遇到 UI "有点苛刻"的需求，这两种方案就不够用了。

‌OverlayScrollbars 是一个用于隐藏原生滚动条并提供可自定义覆盖滚动条的 JavaScript 插件，同时完整保留原生滚动功能与体验‌。‌‌‌

OverlayScrollbars 旨在解决原生浏览器滚动条样式不美观、占用布局空间及跨浏览器表现不一致的问题。其核心优势包括：‌‌‌

‌保留原生滚动行为 ‌：插件在提供自定义滚动条外观的同时，‌完全保留了包括触摸滚动、鼠标滚轮在内的所有原生滚动功能和无障碍支持‌。

‌广泛的兼容性‌：支持 Firefox 59+、Chrome 55+、Edge 15+、Safari 10+ 等主流浏览器，并适配移动端、桌面端及鼠标、触摸、触控笔等多种输入方式。

现代化技术栈 ‌：完全使用 ‌TypeScript 编写 ‌，提供完善的类型定义；采用 ‌零依赖 ‌ 设计，确保代码体积最小化，并支持 ‌Tree Shaking‌ 以便按需引入。

丰富的功能支持 ‌：支持 ‌滚动吸附（Scroll Snapping） ‌、‌虚拟滚动库 ‌，并可直接应用于 <body> 元素。‌‌‌

OverlayScrollbars 可以：控制宽度、做圆角、加动画 、定义 hover / active 状态

安装

复制代码

npm install overlayscrollbars。

引入

复制代码

import 'overlayscrollbars/overlayscrollbars.css';
import { OverlayScrollbars } from 'overlayscrollbars';

初始化

复制代码

const element = document.querySelector('.your-element');
const osInstance = OverlayScrollbars(element);

避免初始化时原生滚动条短暂显示的"闪烁"问题，可以为元素添加 data-overlayscrollbars-initialize 属性。

样式与主题定制

OverlayScrollbars 内置了 ‌**os-theme-dark** ‌ 和 ‌**os-theme-light** ‌ 两种主题，可通过 scrollbars.theme 选项切换。

深度自定义可通过 ‌CSS 自定义属性（CSS Variables） ‌ 实现。例如，创建一个名为 os-theme-custom 的类，并定义如下变量来调整滚动条尺寸和颜色：‌‌‌

复制代码

.os-theme-custom {
     - -os-size: 10px;
     - -os-handle-bg: #ff6b6b;
     - -os-handle-bg-hover: #ff8e8e;

}

初始化时指定自定义主题：OverlayScrollbars(element, { scrollbars: { theme: 'os-theme-custom' } })

主流框架支持

OverlayScrollbars 提供了针对 ‌React、Vue、Angular、Svelte、Solid‌ 的高质量、完全类型化的官方封装版本。

例如，在 Vue 项目中，你需要同时安装 overlayscrollbars 和 overlayscrollbars-vue，然后使用 <OverlayScrollbarsComponent> 或在组合式 API 中使用 useOverlayScrollbars。

滚动条不显示‌：确保 CSS 文件已正确引入，并在 DOM 加载完成后进行初始化。

‌移动端触控支持 ‌：配置 scrollbars.pointers 选项确保包含 'touch'。

性能优化 ‌：对于内容频繁更新的场景，可使用 update 选项中的防抖配置（如 debounce）来减少不必要的重绘。

‌插件使用 ‌：如需点击滚动条轨道进行快速定位（clickScroll），需正确引入并配置 ClickScrollPlugin。‌‌‌

滚动条这个东西，很小，但是真的会影响整体风格~

虽然 scrollbar-color 至少能"统一风格 "，但如果想要更干净的布局、更精致的细节和真正可控的设计，光靠原生 CSS 还是不太够。

OverlayScrollbars在不改变原生体验的前提下，把滚动条变成一个"可设计的组件"。