我所理解的 OverlayScrollbars 最佳实践(2):原生 JS、React、Vue 与浏览器扩展接入
- 原生滚动条与覆盖式原理
- 原生 JS、React、Vue 与浏览器扩展接入(当前)
- 问题排查
给新容器加滚动条,可以让库生成内部结构;给虚拟列表或现有弹窗加滚动条,要先确认业务代码是否依赖原来的节点。四种接法都用同一个 DOM 核心,区别在于谁交出节点、什么时候更新、谁负责清理。
原生 JS:在真实滚动节点上创建实例
安装包名是 overlayscrollbars,官方项目名为 OverlayScrollbars。它提供原生 DOM API,也提供框架包装。最小接入需要同时引入 JavaScript 和 CSS:
pnpm add overlayscrollbars
下面是普通浏览器项目中的局部容器示例。HTML 放进页面,CSS 进入全局样式入口,JS 在目标节点已经插入文档后执行:
<div id="reading-shell">
<div id="reading-list" tabindex="0" aria-label="文章列表">
<!-- 这里放列表内容 -->
</div>
</div>
#reading-shell {
position: relative;
block-size: 280px;
}
#reading-list {
block-size: 100%;
overflow: auto;
}
import 'overlayscrollbars/overlayscrollbars.css';
import { OverlayScrollbars } from 'overlayscrollbars';
const host = document.getElementById('reading-shell')!;
const element = document.getElementById('reading-list')!;
const instance = OverlayScrollbars(
{
target: element,
elements: { viewport: element, padding: false, content: false },
scrollbars: { slot: host },
},
{
scrollbars: { theme: 'os-theme-dark', autoHide: 'scroll', autoHideDelay: 700 },
},
);
target 是交给库增强的目标,viewport 才是真正承载滚动位置的元素。默认初始化允许库生成内部 viewport;这里用对象初始化把两者指定为同一个节点,并关闭额外内容包装。轨道通过初始化对象的 scrollbars.slot 放在不滚动的 reading-shell 中,和 viewport 分开;如果把轨道也放进滚动节点,库就需要在滚动后做反向位移校正。
这个选择保护了已有调用方:原来监听 element 的 scroll、读写它的 scrollTop,或通过 ref 调用 scrollTo() 的代码,继续操作同一个滚动节点。无限加载、吸顶、滚动恢复和虚拟列表尤其依赖这份契约。新组件也可以采用库的默认结构,只要其他调用方统一从 instance.elements().viewport 取得真实滚动层。
显隐与内容追加的可运行对照放在第一篇的演示中。
页面主体、弹窗和内部列表分别接入
给 body 初始化一次,不会自动增强每个内部滚动区。文档、目录和抽屉正文是不同 scroll container,应分别确定谁拥有实例。
弹窗和面板里还有一个常见坑:滚动容器选错了。
比如上传照片弹窗,顶部 header 和底部保存按钮应该固定,只有中间网格滚动。此时滚动条样式应该挂在中间网格层,而不是整个弹窗外壳上。
<section class="upload-panel">
<header class="upload-panel__header">...</header>
<div class="upload-panel__grid">
<!-- grid item -->
</div>
<footer class="upload-panel__footer">...</footer>
</section>
如果把滚动放在外壳上,header 和 footer 会跟着内容滚动,OverlayScrollbars 也会接管错误的滚动根。如果把滚动放在 grid 层,外壳只负责弹窗位置和尺寸,grid 自己负责 scrollport,职责会清楚很多。
这条规则对账号弹窗、资料编辑弹窗、荣誉墙弹窗也一样:弹窗外壳负责定位和背景,header 固定,内容层滚动,底部按钮按设计固定或渐隐覆盖。滚动条提示只属于真正滚动的那一层。
搜索应用中我把这一层封装在通用 dialog 里,业务只提供正文和 Footer;博客则对页面主体、目录和材料阅读器分别装配。两者都把滚动条安装范围限定到真实滚动层。
上面的实例如果随弹层或路由存在,退出时调用 instance.destroy();选项变化用 instance.options(...),内容变化先交给库的观察器。没有打包器时,可以用官方浏览器构建:先加载 CSS 和浏览器脚本,再从 OverlayScrollbarsGlobal 取初始化函数。
React:官方组件和 useOverlayScrollbars hook
新建由 React 控制的滚动区,先用官方 overlayscrollbars-react。安装 pnpm add overlayscrollbars overlayscrollbars-react,并加载核心库的 CSS。给容器一个受限尺寸,才能形成内部滚动:
import { OverlayScrollbarsComponent } from 'overlayscrollbars-react';
import 'overlayscrollbars/overlayscrollbars.css';
export function ActivityPanel({ children }) {
return (
<OverlayScrollbarsComponent style={{ blockSize: 280 }} options={{ scrollbars: { autoHide: 'scroll' } }}>
{children}
</OverlayScrollbarsComponent>
);
}
官方组件负责随 React 组件创建和销毁实例。需要拿滚动节点时,从组件 ref 的 osInstance() 取得实例,再读 elements().viewport;getElement() 返回的是组件根节点。用了 defer 时,实例可能尚未创建,依赖它的逻辑可以放进 events.initialized。
React 包还导出了官方 useOverlayScrollbars hook。组件提供现成的滚动容器,hook 让调用方继续管理原来的 DOM。如果虚拟列表的 outerRef 或已有监听需要留在原节点上,可以在 effect 中调用 hook 返回的 initialize,指定原节点为 viewport。组件卸载时,hook 会清理实例。
如果目标节点在这个组件的生命周期内保持不变,可以这样写:
import { useEffect, useRef } from 'react';
import { useOverlayScrollbars } from 'overlayscrollbars-react';
export function ExistingScrollRegion({ children }) {
const hostRef = useRef(null);
const scrollRef = useRef(null);
const [initialize] = useOverlayScrollbars();
useEffect(() => {
const host = hostRef.current;
const viewport = scrollRef.current;
if (!host || !viewport) return;
initialize({
target: viewport,
elements: { viewport, padding: false, content: false },
scrollbars: { slot: host },
});
}, [initialize]);
return (
<div ref={hostRef} style={{ position: 'relative', blockSize: 280 }}>
<div ref={scrollRef} style={{ blockSize: '100%', overflow: 'auto' }}>
{children}
</div>
</div>
);
}
如果内部节点可能在组件仍挂载时被替换,初始化也要跟着节点走,可以把这个滚动层拆成独立组件,让它随节点一起卸载。项目已经有自己的滚动区 hook,也可以在里面直接用核心库;这时要让 effect 返回清理函数调用 destroy(),并将选项更新与实例创建分开。开发时用 Strict Mode 检查创建、清理、再创建之后是否只剩一组轨道。团队自己封装的是主题、ref 和生命周期,手柄同步仍交给库。
Vue:官方组件、composable 和 v-scrollbar 怎么选
自有 Vue 界面优先使用官方组件,包括可以调整滚动节点的既有页面。安装 pnpm add overlayscrollbars overlayscrollbars-vue 后,从官方 overlayscrollbars-vue 导入 OverlayScrollbarsComponent,再加载核心库的 CSS。组件接收 options、events 和 defer,也可以用 @os-scroll 监听滚动。滚动条实例随组件挂载和卸载。
例如局部活动列表,可以直接在单文件组件里使用。用 activity-panel 给根节点设置高度,和原生示例一样让内容在面板内部溢出:
<script setup>
import { OverlayScrollbarsComponent } from 'overlayscrollbars-vue';
import 'overlayscrollbars/overlayscrollbars.css';
</script>
<template>
<overlay-scrollbars-component :options="{ scrollbars: { autoHide: 'scroll' } }" class="activity-panel">
<slot />
</overlay-scrollbars-component>
</template>
普通局部容器会把插槽包在一个内部节点里,用它做 viewport。轨道默认留在外层,跟内部滚动分开。这是官方组件的模板和初始化代码决定的。现有页面迁移时,把读取 scrollTop 和调用 scrollTo() 的代码迁到实例的 elements().viewport,滚动事件可以接 @os-scroll。原来依赖直接子元素的样式也要一起检查。
Markdown 阅读器早期用了自写指令,把轨道装进了正在滚动的 viewport。库需要在滚动后补一段反向位移,正文和内链浮窗里都遇到过整条轨道晃动。迁到官方组件后,轨道的位置由不滚动的外层决定。错误初始化与回归范围见第三篇的轨道排查。
图右侧的 composable 显式把原节点设为 viewport。图左侧如果要直接监听原生事件,应找到内部 viewport。使用组件事件时,可以在模板上监听 @os-scroll。
项目级 ScrollArea 定义哪些契约
只有一个活动列表时,直接用官方组件就够了。如果多个滚动区只需要同一种外观,也可以通过默认主题统一。阅读器的正文、目录、字体列表和预览浮窗除了用同一套主题,还反复遇到同一组问题:焦点和可访问名称应该落到哪个节点?保存的滚动位置什么时候能恢复?浮窗滚到底时,要不要带动正文?
我给这些滚动区包了一个 ScrollArea。官方组件继续生成 viewport、挂轨道并管理实例;ScrollArea 把滚动轴、焦点、名称和边界行为落到正确的节点,再通过 @viewport 把这个节点交给调用方。这样正文可以恢复阅读位置,字体列表可以定位选中项,浮窗也能阻止同轴手势传到背景。各处共用一套接入约定,具体滚到哪里仍由各自决定。
下面的 Code Lab 用普通 Vue 3.5 展示这层封装。点「跳到第 16 段」或「回到顶部」,可以看到 scrollTop 更新;卸载阅读区后,调用方收到 null,两个跳转按钮随即禁用。切换配色时,横向和纵向的手柄一起变色。想看业务如何接入,先读 scroll-area-demo.vue;要看节点如何交出来、主题在哪定义,再打开 copy/components/scroll-area/index.vue。
| 接口 | 用途 |
|---|---|
| 外层 class | 设置滚动区高度、Flex / Grid 约束和背景 |
| axis | 选择横向或纵向滚动 |
| label / labelledby | 给真实 viewport 提供名称;有现成标题时引用标题 id |
| tabindex | 默认 0;内部控件已管理焦点时用 -1 |
| viewport 事件 | 初始化完成后提供真实滚动节点,销毁时提供 null |
| scroll 事件 | 转发原生滚动事件,由调用方决定测量或节流 |
例如设置页已经有标题,就让滚动区引用它。字体列表的搜索输入框采用 combobox 交互,方向键通过 aria-activedescendant 指向候选,滚动层可以退出 Tab 顺序:
<scroll-area class="settings-panel" labelledby="settings-title">
<h1 id="settings-title">设置</h1>
<!-- 设置内容 -->
</scroll-area>
<scroll-area class="font-options" :tabindex="-1" @viewport="listViewport = $event">
<!-- 字体候选 -->
</scroll-area>
这里的 tabindex 要落到 viewport。写在外层 host 上,焦点所在的节点和真实滚动节点仍可能不同。能否用键盘进入也应独立于名称配置;MDN 对滚动区无障碍的说明建议提供键盘焦点与相应名称。内部已有焦点管理时用 -1,可以避免多出一处 Tab 停靠,同时保留程序聚焦能力。
初始化处理的顺序也属于接口。先取得 viewport,配置方向、焦点与名称,再通知调用方就绪。下面是组件内的关键处理,labelledby 存在时优先使用标题引用,切换或清空属性时移除旧值:
watch(
[viewport, axis, label, labelledby, tabindex],
([element, direction, name, titleId, tabOrder]) => {
if (!element) return;
const title = titleId.trim();
const text = name.trim();
element.dataset.scrollAreaAxis = direction;
element.tabIndex = tabOrder;
if (title) element.setAttribute('aria-labelledby', title);
else element.removeAttribute('aria-labelledby');
if (text && !title) element.setAttribute('aria-label', text);
else element.removeAttribute('aria-label');
if (title || text) element.setAttribute('role', 'region');
else element.removeAttribute('role');
},
{ flush: 'sync' },
);
function initialized(instance: OverlayScrollbars) {
const element = instance.elements().viewport;
viewport.value = element;
emit('viewport', element);
}
这样调用方在就绪回调内执行 focus({ preventScroll: true }) 或恢复 scrollTop 时,节点已经可用。同步 watch 先为新 viewport 配置属性,再由初始化回调通知调用方。它也负责后续配置变化,设置页不必在内容层另放一个可聚焦的 section。
在 overlayscrollbars-vue 0.5.10 中,初始化发生在官方组件的 watchPostEffect 内。最初把上面的同步逻辑直接写进初始化回调,回调读取的 label、labelledby 等响应式值也被这个 effect 收集;改名时出现销毁、重新初始化,scrollTop 从 123 变成 0。独立 watch 在自己的 getter 中收集依赖,回调只使用传入的值,可以让配置变化与实例生命周期分开。这个问题说明,就绪事件后的滚动正常还不够,还要验证配置和内容变化后仍是同一个滚动区。
卸载也有一个接口责任:调用方可能已经给 viewport 安装了自己的观察器。测试中,只转发官方 os-destroyed 未能在包装组件卸载时发出 null,因此在包装层的 onBeforeUnmount 中提前清理公开引用,并通过空值判断避免重复通知:
function destroyed() {
if (!viewport.value) return;
viewport.value = null;
emit('viewport', null);
}
onBeforeUnmount(destroyed);
这段代码负责交还项目接口,实例本身仍由官方组件销毁。调用方在收到 null 或新节点时,释放原节点上的监听与观察器。
边界样式同样要跟着真实 viewport。假如写成 .scroll-area–y 后代的所有 viewport 都使用 overscroll-behavior-y: contain,外层纵向阅读区就会把内层横向区域一起选中。在横向代码上使用竖向滚轮,正文可能因此滚不动。可以让每个实例给自己的 viewport 标记方向,再按该节点的属性匹配:
.scroll-area [data-scroll-area-axis='y'] {
overscroll-behavior-y: contain;
}
.scroll-area [data-scroll-area-axis='x'] {
overscroll-behavior-x: contain;
}
这是全局 CSS 的选择器写法;Vue scoped 样式需要对库生成的节点使用 :deep()。内层横向 viewport 只匹配 x 规则,竖向手势可以继续交给正文。浮窗的纵向 viewport 使用 contain,可以在到顶或到底时阻止滚动传给背景;具体语义见 MDN 的 overscroll-behavior 说明。是否阻止边界传递仍要按产品交互决定,普通网页不必一律如此设置。
项目组件也需要保留清楚的边界。查找命中后居中、按文档保存偏移、字体过滤后回到列表顶部,仍由各自业务决定。调用方已经拿到真实 viewport,就可以用原生 scrollTo 或 scrollTop;滚动包装不必再复制一组同义方法,也不用为每个实例额外安装 ResizeObserver。只有一处使用、只需改主题时,直接用官方组件或统一默认选项已经足够。
Vapor 通过互操作使用官方组件
Vapor 不要求把框架封装全部改成指令。需要先检查发布包:overlayscrollbars-vue 0.5.10 的组件仍走普通 Vue 的 VDOM 路径。Vue 3.6.0-rc.14 的纯 Vapor 应用可以按官方互操作说明安装 vaporInteropPlugin,让普通组件与 Vapor 业务模板一起运行:
import { createVaporApp, vaporInteropPlugin } from 'vue';
import App from './App.vue';
import 'overlayscrollbars/overlayscrollbars.css';
createVaporApp(App).use(vaporInteropPlugin).mount('#app');
本地 Markdown 阅读器采用这组 Vue 版本,核心库是 OverlayScrollbars 2.17.0。隔离示例里,不安装互操作插件时,官方组件没有显示,控制台出现 Vapor 组件初始化警告;安装后,插槽、选项更新和卸载清理正常。在 Windows Electron 打包版中再验证正文、目录、字体列表与链接预览,才能判断业务接口是否也接对了。构建通过或页面没有异常,都不能代替这些操作。
阅读器通过 ScrollArea 统一主题、滚动轴、键盘入口与无障碍名称,同时转发 os-initialized 提供的真实 viewport 和 os-scroll 提供的滚动事件。父组件等 viewport 就绪后恢复阅读偏移,并把这个节点交给 ResizeObserver;字体候选的搜索重置和方向键定位也操作同一个 viewport。插槽内的文章、列表和批注内容移除原有的 overflow,避免形成两层滚动区。
初始阅读位置需要及时恢复,因此这条路径即时初始化,没有使用 defer。浮窗开关、前进后退和重启恢复都要检查;尺寸变化时只更新测量,不能反复把阅读位置重置为初始值。
必须保留现有滚动节点的场景
在能调整滚动结构的 Vue 页面里,官方组件就能承担主题、显隐、滚动事件和实例清理,指令排在它后面。组件的 options 用来配置滚动行为,普通局部容器的 viewport 由组件自己创建。如果虚拟列表或外部代码必须继续读写原来的那个元素,就需要一种可以指定原 viewport 的接法。
只有一个组件需要保住现有节点,我会先用官方 useOverlayScrollbars:在 onMounted 中传入和原生示例一样的 { target: el, elements: { viewport: el, padding: false, content: false }, scrollbars: { slot: host } }。这样原有 scrollTop、滚动监听和 DOM 结构都能保留,composable 会在组件卸载时销毁实例。host 要是尺寸贴合滚动区、已定位且不滚动的独立外层,不能只因为它是 parentElement 就直接采用。如果节点会在组件仍挂载时被 v-if 换掉,需按节点的生命周期处理,或把滚动层拆成单独组件。
多处已有节点都无法迁移滚动契约,而且确实要按节点统一启停时,才考虑维护 v-scrollbar。指令放在实际滚动的元素上,直接外层用 data-scrollbar-host 标记。配套 CSS 让外层负责定位和裁切,内层继续承载滚动。
<template>
<div data-scrollbar-host>
<div v-scrollbar="{ active: enabled, autoHide: 'leave' }" class="upload-panel__grid">
<!-- 上传项 -->
</div>
</div>
</template>
target 和 viewport 仍指向原元素,scrollbars.slot 则指向外层宿主。Vue 在 mounted 创建实例,在 updated 更新选项,禁用或卸载时销毁实例。找不到符合约定的宿主时,原元素继续使用原生滚动条。打开保留原节点的 Vue / Nuxt 指令源码弹窗,可以对照指令、样式和两种弹窗结构。
Markdown 代码块怎样接入滚动条
阅读器的正文和内链预览都是先把 Markdown 渲染成 HTML,再插入页面。外层的纵向滚动区由 ScrollArea 管理,但里面每个 <pre> 都是渲染器生成的 DOM,Vue 没有为它们创建组件实例。把整篇文章放进一个 Vue 插槽,也只会创建外面那一个滚动区。每个长代码块还需要自己的横向滚动条。
我把这一步留在阅读模块。正文或预览插入 HTML 后,代码块适配函数找到渲染器生成的 <pre>,通过官方 DOM 初始化 API保留它作为 viewport,并把 scrollbars.slot 指向已经定位、不会滚动的代码块外壳。替换 HTML 或卸载预览时,由插入内容的一方销毁旧实例。正文和预览都属于同一个阅读模块,所以两处复用模块内的适配函数;其他业务仍通过 ScrollArea 接入。
必须保留原节点时再适配 Vapor 指令
字体 Popup 迁到 Vue 3.6.0-rc.14 时,继续使用 OverlayScrollbars 2.16.0 的 DOM API,改动发生在指令:函数执行时节点可能还没插入,要等 post effect 再初始化;退出所属分支时停止 effect 并销毁实例。
同时把原节点保留为 viewport,滚动条放到对应局部父层,避免重新包裹 Vue 管理的子节点。列表重排、内容缩短、容器缩小、隐藏重显和分支销毁都需要回归。这里的兼容结果只覆盖当前宿主,不能外推到所有 Vue wrapper;完整迁移与包体积分析见 Vapor 实践记录。
第三方页面:用 Chrome 扩展增强现有滚动区
先在开发者工具里找到滚动时 scrollTop 确实变化的元素,看看原站是否给它绑了滚动监听、用它做恢复或测量子元素。只改外观颜色时,可以先用范围明确的 CSS。确实需要覆盖式轨道,再把库和样式随扩展打包,通过内容脚本对已确认的节点安装实例。内容脚本在隔离环境中可以操作共享 DOM;目标在 iframe 时,要确认扩展能注入对应文档,样式也要进入那个文档。遇到 Shadow DOM,则单独检查样式边界。
这里沿用原生 JS 的对象初始化,保留目标作为 viewport。若默认轨道位置被裁切,可以找一个能稳定定位的外壳,用 scrollbars.slot 指定轨道挂载点。下面是内容脚本中的装配片段,viewport 和 shell 由站点适配器提供:
const instance = OverlayScrollbars(
{
target: viewport,
elements: { viewport, padding: false, content: false },
scrollbars: { slot: shell },
},
{ scrollbars: { autoHide: 'scroll' } },
);
动态弹窗和 SPA 会换节点。适配器应记录自己创建的实例:同一个节点再次扫到时复用,节点退出或被替换时销毁,再对新节点初始化。需要 MutationObserver 时,观察最小的稳定范围,合并重复扫描,并避开扩展生成的轨道。初始化取消或失败时,撤掉扩展自己加的预隐藏标记;已经有独立滚动实现的编辑器,优先保留原站行为。
body 要单独评估。局部容器成功,并不说明窗口滚动、锚点、页面内查找、历史恢复和弹窗滚动锁都能保留。如果确实要接管整页,再核对官方对象初始化选项里的 cancel.body,并逐项回归这些操作。
全局默认值和项目封装各管什么
如果整个应用只是要统一主题和自动隐藏策略,可以在客户端入口、创建第一个实例前设置默认值。下面假设 os-theme-app 的样式已经加载。
import { OverlayScrollbars } from 'overlayscrollbars';
OverlayScrollbars.env().setDefaultOptions({
scrollbars: { theme: 'os-theme-app', autoHide: 'scroll', autoHideDelay: 700 },
});
环境 API 的 setDefaultOptions() 会把传入的字段合并到当前默认值。同一份库里的后续实例都能继承这组配置,单个实例显式传入的选项优先。已有实例可以用 instance.options(...) 更新。环境还提供 setDefaultInitialization(),可以统一初始化结构和取消条件的默认值。只给一类容器保留原 viewport 时,在对应的初始化调用里指定即可。
官方组件与项目包装负责不同的事情:官方组件管理滚动结构和生命周期,项目包装统一主题及业务接口;仅为了设置一次主题,不需要再写指令。v-scrollbar 适用于必须保留已有 DOM 契约的另一类接入。它是在核心库上的一层 Vue 封装。它把原节点指定为 viewport,并按指令绑定值创建、更新或销毁实例。示例指令也显式传入了自己的主题和显隐选项,这些字段会覆盖全局默认值。只有主题和显隐需要统一时,一次默认配置就够了。多处模板都要复用节点和启停规则时,才值得维护指令。
样式统一用主题变量
全局生效的主题也可以由组件维护。比如 ScrollArea.vue 用 <style scoped> 管理自己的容器和焦点样式,再用单独的非 scoped 样式块定义滚动条主题。库生成的轨道不带 Vue 的作用域属性,选择器用 .os-scrollbar 加项目主题类,就能命中通过组件或 DOM API 创建的轨道。两条接入路径选同一个 scrollbars.theme,主题变量只维护一份。
OverlayScrollbars 的样式文档分别列了普通、悬停和按下时的手柄厚度。2.17.0 的内置深浅主题都让这三个值保持 100%,只在悬停和按下时改变手柄的不透明度。
想让手柄平时细一点、鼠标靠近时又容易拖,可以固定轨道厚度,再给手柄设置不同状态的尺寸:
.os-scrollbar.os-theme-app {
--os-size: 15px;
--os-padding-perpendicular: 3px;
--os-padding-axis: 4px;
--os-handle-min-size: 30px;
--os-handle-perpendicular-size: 5px;
--os-handle-perpendicular-size-hover: 9px;
--os-handle-perpendicular-size-active: 9px;
--os-handle-interactive-area-offset: 4px;
--os-track-border-radius: 999px;
--os-handle-border-radius: 999px;
--os-handle-bg: rgb(100 116 139 / 0.48);
--os-handle-bg-hover: rgb(100 116 139 / 0.7);
--os-handle-bg-active: rgb(100 116 139 / 0.85);
}
初始化时把 scrollbars.theme 设置为 os-theme-app。上面的 5px 和 9px 只改变可见手柄,4px 扩展的是可抓取区域,轨道仍是 15px。库会处理厚度切换,正文无需为悬停让出额外空间。实际项目再把颜色映射到自己的主题 token,并检查深浅配色、键盘焦点和强制颜色模式。
阅读器还希望按住手柄拖出轨道后保持 9px。这个细节额外依赖 2.17.0 的 .os-scrollbar-interaction 状态类,它不在官方主题可用类名列表里。普通悬停只需上面的变量;如果项目也依赖这个状态类,升级后要实测拖出轨道、松手、手柄恢复的过程。
厚度与手柄长度不要混写
--os-size 控制轨道整体厚度,--os-handle-min-size 控制手柄沿滚动方向的最小长度,--os-handle-perpendicular-size 控制垂直于滚动方向的尺寸。横向和纵向的物理属性映射已经由库完成。
图中蓝色标的是手柄沿滚动轴的尺寸:横条量宽度,竖条量高度。实际手柄可能比设定的最小值更长。
例如,想把手柄最小长度设成 36px,应改 --os-handle-min-size,而不是同时写 min-width: 36px; min-height: 36px。后一种写法会把竖向手柄也撑到 36px 宽。
原生 CSS 的颜色、厚度与占位方式,见第一篇的能力比较。这里的主题变量由库定义,需要按照滚动轴的语义使用。
OverlayScrollbars 分别生成带有 .os-scrollbar-horizontal 和 .os-scrollbar-vertical 的滚动条节点,由库 CSS 按方向把同一组变量映射到不同物理属性。这些映射已写在方向 class 的规则里,主题侧只需要使用官方文档定义的语义变量。
库内部等价于按方向写了两套映射:
.os-scrollbar-horizontal {
height: var(--os-size);
}
.os-scrollbar-vertical {
width: var(--os-size);
}
.os-scrollbar-horizontal .os-scrollbar-handle {
min-width: var(--os-handle-min-size);
height: var(--os-handle-perpendicular-size);
}
.os-scrollbar-vertical .os-scrollbar-handle {
min-height: var(--os-handle-min-size);
width: var(--os-handle-perpendicular-size);
}
遇到问题可以直接查对应一节:
Vue 与 Nuxt 的滚动条指令源码
工作区里的两个示例分别把指令挂在上传网格和弹窗主体上。原节点继续处理滚动,轨道由直接外层承载。迁移到其他页面时,先核对外层尺寸和真实 viewport,再接入相同的指令。