OverlayScrollbars 中文文档

一个 JavaScript 滚动条插件，它能隐藏原生滚动条，提供可自定义样式的覆盖滚动条，并保留原生的功能和手感。

• 仓库地址：https://github.com/KingSora/OverlayScrollbars
• 示例：https://kingsora.github.io/OverlayScrollbars/examples

为什么

创建这个插件是因为讨厌既难看又占用空间的原生滚动条。类似的插件在功能、质量、简洁性、许可协议或浏览器兼容性方面没有达到要求。

目标与特性

• 简单、强大且文档齐全的 API
• 高度的浏览器兼容性 - 支持 Firefox 59+、Chrome 55+、Opera 42+、Edge 15+和 Safari 10+
• 完全可访问 - 完全保留原生滚动行为
• 支持服务器端运行（Node、Deno 和 Bun）- 支持 SSR（服务器端渲染）、SSG（静态站点生成）和 ISR（增量静态再生）
• 在多种设备上测试过 - 包括移动设备、桌面和平板电脑
• 适用于多种（及混用的）输入方式 - 鼠标、触控和笔
• 树摇优化 - 只打包实际需要的部分
• 自动更新检测 - 无需轮询
• 利用浏览器最新特性 - 在新浏览器中实现最佳性能
• 与流方向无关 - 支持所有 direction、flex-direction 和 writing-mode 的值
• 支持滚动吸附（Scroll Snapping）
• 支持所有虚拟滚动库
• 支持 body 元素
• 简单且有效的滚动条样式定制
• 高度可定制
• 支持 TypeScript - 完全使用 TypeScript 编写
• 无依赖 - 100% 自主编写，确保体积小巧和最佳功能
• 高品质且完全类型化的框架版本，适用于 React、Vue、Angular、Svelte 和 Solid。

选择你的框架

除了原生 JavaScript 版本之外，您还可以使用官方提供的框架组件与实用工具：

开始使用

npm & nodejs

OverlayScrollbars 可以从 npm 或您选择的包管理器下载：

npm install overlayscrollbars

安装后，您可以这样导入：

import "overlayscrollbars/overlayscrollbars.css";
import {
  OverlayScrollbars,
  ScrollbarsHidingPlugin,
  SizeObserverPlugin,
  ClickScrollPlugin,
} from "overlayscrollbars";

注意：如果路径 'overlayscrollbars/overlayscrollbars.css' 无法正常工作，请使用 'overlayscrollbars/styles/overlayscrollbars.css' 作为 CSS 文件的导入路径。

您可以将此 Node 示例 作为参考或起点。

手动下载与嵌入

您可以在没有任何打包器或包管理器的情况下使用 OverlayScrollbars。 只需从发布页面下载或使用 CDN 即可。

• 使用带有 .browser 扩展名的 javascript 文件。
• 如果您需要支持较旧的浏览器，请使用带有 .es5 扩展名的 javascript 文件，否则请使用 .es6 文件。
• 生产环境中，请使用带有 .min 扩展名的 javascript 和 stylesheet 文件。

在 HTML 中手动嵌入 OverlayScrollbars：

<link type="text/css" href="path/to/overlayscrollbars.css" rel="stylesheet" />
<script
  type="text/javascript"
  src="path/to/overlayscrollbars.browser.es.js"
  defer
></script>

使用全局变量 OverlayScrollbarsGlobal 来访问 API，就像在 nodejs / 模块中一样：

var {
  OverlayScrollbars,
  ScrollbarsHidingPlugin,
  SizeObserverPlugin,
  ClickScrollPlugin,
} = OverlayScrollbarsGlobal;

您可以将此 浏览器示例 作为参考或起点。

本文档中的示例将使用 import 语法而非 OverlayScrollbarsGlobal 对象。两种版本是等价的。