我所理解的 OverlayScrollbars 最佳实践(3):问题排查
- 原生滚动条与覆盖式原理
- 原生 JS、React、Vue 与浏览器扩展接入
- 问题排查(当前)
滚轮能滚,手柄却不见了;给列表装上滚动条后,滚动恢复又失效了。这两种问题看上去都像初始化不对,但一个可能只是样式,另一个可能是原调用方仍在操作旧节点。我通常先操作一次滚动,找到真正改变 scrollTop 的元素,再看尺寸和覆盖层。
先检查滚动根和溢出
在开发者工具里读取 instance.elements() 和 instance.state()。局部容器先比较 viewport 的 scrollHeight 和 clientHeight,横向则比较宽度;没有溢出时,visibility: 'auto' 下看不到条是正常的。Flex 或 Grid 子项如果被内容撑开,先检查滚动层有没有受限尺寸。纵向 Flex 布局可以检查子项是否需要 min-block-size: 0 才能缩进面板。
如果能滚,但旧的监听器、吸底或位置恢复失效,对比接入前后的节点。elements().scrollOffsetElement 用来读写偏移,scrollEventElement 用来订阅原生事件;普通局部容器里它们通常就是 viewport。文档滚动则继续使用窗口 API。如果库生成了新的滚动层,要么把调用方迁到正确节点,要么按接入篇显式复用原 viewport。
DOM 在,手柄却看不见
还遇到过一种看似初始化失败的问题:滚动条节点已经生成,内容也能滚动,但手柄完全看不见。原因在样式顺序:库的 .os-scrollbar 声明了默认变量,如果应用只写 .os-theme-app,同等优先级下,后加载的库 CSS 可能覆盖主题变量。
主题选择器使用 .os-scrollbar.os-theme-app,再核对实际生效的 --os-size、--os-handle-bg 与轨道位置。这比给整个面板不断加 z-index 更容易定位问题。底部有渐变遮罩时,也只调整滚动条的层级,不能把全部滚动内容一起提到遮罩上方。
autoHide: 'scroll' 适合滚动时提示,'leave' 更强调鼠标离开后隐藏,常显则使用 'never'。是否具有 hover 能力应按输入设备判断,不能只看屏幕宽度;触屏和键盘使用者也需要发现可滚动内容。
主题变量生效后仍然看不到手柄,可以暂时关掉自动隐藏,再检查轨道是否被 overflow 裁切、被遮罩盖住,或者挂到了错误的 slot。确认是哪一层拦住,再修那一层。
滚动时整条轨道移动
如果正文宽度没有变化,轨道却跟着滚动晃动,先查挂载结构。Markdown 阅读器早期的自写指令把原节点同时用作 target 和 viewport,轨道也落在了滚动节点里面。下面的代码复现了这种挂载关系。
OverlayScrollbars({
target: viewport,
elements: { viewport, padding: false, content: false },
scrollbars: { slot: viewport },
}, options);
当 target 和 viewport 是同一个局部节点时,省略 scrollbars.slot 也会让轨道挂到这个节点上。轨道和正文一起滚动时,库要在滚动后用反向 transform 抵消这段位移。如果浏览器先绘制了滚动、校正稍后才生效,中间帧就可能看见整条轨道晃一下。
把轨道挂到不滚动的外层后,外层的位置就决定了轨道的位置。阅读器用接入篇的官方组件方案分开了外层和 viewport。必须保留原节点时,也可以把初始化对象的 scrollbars.slot 指向独立 host,得到同样的结构。
迁到官方组件后,还要沿着实例的 elements().viewport 检查业务逻辑。旧内容层继续设置 overflow: auto,会生成第二个滚动区;旧 ref 上的 scrollTop 也不再是实际阅读位置。初始化就绪后绑定真实 viewport,滚动事件通过 os-scroll 接收,才能保持查找跳转、批注定位和阅读恢复使用同一个滚动根。
实际验收需要记录连续帧:内容尺寸不变、持续向下滚动时,轨道的 DOMRect 应保持固定,滑块只向下移动;反向滚动与拖动手柄也要测试。链接浮窗还要确认滚到底之后,浮窗坐标和背景正文保持原位。图片补齐尺寸、字体替换、折叠块展开导致的范围变化,要和轨道自身漂移分开记录;DOM 采样不足以解释肉眼看到的晃动时,再查看录屏或合成画面。
浮窗还要覆盖快速移出、再移入同一链接的操作。取消尚未执行的打开定时器时,也要清除待打开地址,并让旧异步请求失效;否则下一次移入可能被误判为已经调度,预览迟迟不出现。
阅读器迁到官方组件后,用 Windows 打包版复测了正文和内链预览。连续滚动时轨道留在原位,批注保存和阅读位置恢复也走新的 viewport。如果再看到偶发的晃动,可以结合实际运行版本、DOM 尺寸和绘制帧,确认是轨道移动、滑块反跳,还是正文重排。
键盘与嵌套滚动要单独验证
滚轮正常不代表键盘入口也接对了。通过 Tab 聚焦滚动区后,用 PageDown / PageUp 检查实际变化的 scrollTop;若焦点停在 host 或内容层,就回到真实 viewport 上检查 tabindex。无障碍名称可用 label 提供,也可用 labelledby 引用已有标题,但不能把「有没有名称」当成「能不能聚焦」的开关。初始化就绪回调内立即 focus 也要成功,避免属性尚未配置就发出事件。
名称切换需要覆盖 label → labelledby → 清空三个状态,核对旧 aria-label、aria-labelledby 和 role 是否按约定移除。同时记录初始化次数、viewport 身份和 scrollTop,改名与增加内容不应导致实例重建或位置归零。字体 combobox、树形导航已经管理内部焦点时,让滚动层使用 tabindex=-1,验证方向键仍能把当前项滚进可见区,搜索输入框也没有失去焦点。
嵌套区域要测两个方向:横向滚轮推动内部内容,竖向滚轮继续推动正文。检查各 viewport 的 computed overscroll-behavior-x / y,外层纵向 contain 不应误加到内层横向区域。浮窗则相反,滚到自身边界后继续滚,背景应保持原位。只测滚动范围中间的一次滚轮,很容易漏掉这种边界问题。
ScrollArea 的接口与初始化顺序见接入篇的项目组件约定。卸载后检查调用方收到 null,绑定在旧 viewport 上的资源已释放,再挂载只有一组轨道。几何稳定、焦点可用、事件时序和销毁清理应分别验收,不能只凭统一了组件入口就认为这些问题都已解决。
内容在变时,复用实例并补对更新信号
观察器能帮忙更新几何,但应用仍然要知道哪些变化会影响滚动范围,哪些属于业务行为。
逐字输出不需要逐字重建
搜索直答会不断追加文本,原组件还可能通过 ref 调用 scrollTo() 自动跟随。接入滚动条时,首先保护这个 ref 所指向的节点,再让库合并处理文本与尺寸变化。
实例只初始化一次。重复扫描发现已有实例时继续复用,不在每个字符到达后执行 destroy() / 重建,也不默认每次都 update(true)。是否追到末尾、用户上翻后是否停止自动跟随,由消息组件决定;滚动条只反映当前位置。
虚拟列表也要分开处理。OverlayScrollbars 不减少列表 DOM,虚拟列表负责可见范围和总高度占位。过滤 mutation 只能忽略已经确认不改变真实滚动尺寸的变化,不能为了减少更新,把总高度变化也屏蔽掉。
图片加载与 transform 缩放不是同一种变化
图片预览需要保留原图片的父子关系、尺寸、缩放和关闭逻辑。替图片再加一层内容包装,可能改变原站定位或点击判断;因此这类接入同样复用原 viewport,把轨道放到稳定外壳。
图片 load 会影响内容尺寸;transform 缩放可能改变可滚动溢出,却不改变 ResizeObserver 观察的布局盒。只在动画开始时更新,可能把中间帧的范围留到结束。当前图片预览额外订阅图片的 load transitionend,并观察尺寸恢复标记,在变化完成后通过库的调度更新。
这不是要求所有容器都加更多观察器。先确认现有自动更新缺了什么信号,再配置 update.elementEvents 或 update.attributes;使用完成事件而不是猜一个固定延时。长图滚轮、手柄拖动、缩放结束和点击关闭仍要在真实浏览器里逐项检查。
布局横移与首帧闪烁
先看横移发生在哪个范围:只有面板内部变宽,通常查这个容器的槽位;正文和固定导航一起动,则查根滚动和弹窗滚动锁。
hover 时切换原生条,网格横向抖动
第一种是 hover 时切换原生滚动条样式。
.panel {
overflow-y: auto;
scrollbar-width: none;
}
.panel:hover {
scrollbar-width: thin;
}
这段代码在某些环境里会直接改变滚动条占位。只要滚动条从 none 变成 thin 后参与布局,clientWidth 就会变,网格列宽也会变。对图片网格、卡片网格、居中按钮来说,这种变化就是肉眼可见的抖动。
第二种是直接上 scrollbar-gutter: stable。
.panel {
overflow-y: auto;
scrollbar-gutter: stable;
}
scrollbar-gutter: stable 的目标是预留滚动条空间,避免滚动条出现时突然挤内容。它解决的是「出现时挤一下」,但代价是滚动条区域从一开始就占着宽度。如果设计稿里的按钮是按视觉区域居中的,这个预留槽会让按钮看起来偏一边。
使用 stable both-edges 还可以让两侧预留对称槽位,但会进一步占用宽度;原生覆盖式条不会因此产生槽位。需要先判断项目是否接受这份固定留白,不能把 gutter 当成切换为覆盖式条的开关。
它适合表格、长列表、阅读区这类「宁可常驻占位,也不要内容宽度变化」的场景。对弹窗网格、浮层面板、图片选择器这种追求视觉贴合的区域,预留一条空槽经常不是想要的结果。
打开抽屉,固定导航也横移
页面级问题发生在滚动锁:打开抽屉后,经典滚动条消失,可用宽度增加,居中的正文与固定导航都可能移动。只给普通流内容补 padding,不一定同时保护固定导航。
博客最终让 body 使用 OverlayScrollbars,保留 window 滚动 API;目录和材料正文分别增强,页面实例跨 Swup 导航保留,局部实例随文章释放。做法和生命周期详见主题重写记录。
页面滚动和锚点、查找定位、浏览器历史、无限加载、弹窗锁滚动联系很深。自有项目可以把主体纳入统一接入,但要额外回归这些能力;第三方页面则需要更保守地评估接管范围。
SSR 页面要考虑第一次绘制
即使自绘滚动条不会挤布局,初始化之前仍有一小段空窗。OverlayScrollbars 官方文档说明,库需要时间创建并插入节点;如果浏览器已先绘制原生滚动条,用户就会看到它闪一下,然后才切换为自绘条。把原生条的隐藏样式放在「实例初始化成功」的标记下,只能处理初始化之后,管不到这段空窗。
能控制页面源码时,官方给出的桥接方式是在目标元素首次渲染时就写 data-overlayscrollbars-initialize,并让库的 CSS 在首帧前加载。接管 body 时,html 和 body 都需要这个属性;局部滚动容器只需在该容器上写。属性不能等到 mounted、useEffect 或初始化回调里才补,否则原生条可能已经绘制。这里隐藏的是原生滚动条视觉,不是把滚动容器设成 display: none。
<template>
<div data-scrollbar-host>
<div v-scrollbar data-overlayscrollbars-initialize class="upload-panel__grid">
<!-- grid item -->
</div>
</div>
</template>
这对本文源码包里的自定义 v-scrollbar 只是一个可选的首帧补充,不是指令自动提供的行为:要由模板或 SSR 输出属性,并确认指令确实会初始化这个元素。若指令可通过 v-scrollbar="false" 禁用,桥接属性也要随启用状态一起撤掉;否则实例没装,原生条却被隐藏。使用官方 Vue OverlayScrollbarsComponent 时情况不同,它的模板已经在根元素写了这个属性,不必再手动重复加;但若用 useOverlayScrollbars composable 或自己写组件,仍需检查初始 DOM。官方组件支持 defer 延后初始化,桥接属性在此时尤其有用。SSR 场景还要确认 CSS 已在首屏加载;如果组件只在客户端异步创建,也要检查创建后到初始化之间是否跨过一次绘制。
官方还提醒,普通桥接 CSS 在 JavaScript 完全不执行时也会隐藏原生条;支持该边界的站点可评估 overlayscrollbars.scriptingenabled.css 及 scripting 媒体特性的浏览器兼容范围。不过它解决的是禁用脚本,不会自动处理脚本运行后初始化失败的情形。
初始化失败后,只剩下被隐藏的原生条
预隐藏解决了首帧,却增加了失败责任。内容脚本异常、选择器失效或构造取消时,容器可能仍可滚动,却失去可拖动的视觉入口。
浏览器扩展里的实现用接管结果区分 overlay 与 native:失败目标退出预隐藏规则,恢复原生条,并保留原有滚动位置。取消初始化可能返回一个已经销毁的实例,所以不能仅检查返回值是否为真,还要确认 state().destroyed。
如果构造中途已经插入节点,先尝试通过库实例的 destroy() 恢复结构,不手动拆原站 DOM。失败节点保持原生模式,避免每轮 DOM 扫描都重新构造、再次失败。脚本完全没有执行时,运行时回退也没有机会生效;这正是静态预隐藏要限制到已确认目标的原因。
验证滚动条,要同时看外观和滚动契约
滚动条 DOM 存在,不能证明内容能滚;内容能滚,也不能证明手柄、布局和原有事件都正确。
我会先确认实际 viewport,再测到 scrollHeight > clientHeight 和非零 scrollTop,随后比较显隐、弹窗开关前后的 clientWidth、offsetWidth 与关键 DOMRect。两种宽度不需要彼此相等,边框本来就会造成差值;需要保持的是同一元素前后的稳定。
局部容器再覆盖内容追加、缩短、尺寸变化、隐藏重开与销毁。页面级实例额外检查 window.scrollTo()、锚点、后退、页面内查找和背景锁滚动。测试浏览器不能始终隐藏原生滚动条,否则很容易把 Windows 上的占位变化漏掉。详细步骤见滚动条的完整验收项弹窗。
键盘焦点必须能进入需要滚动的区域,方向键和 PageDown 等操作仍然有效;自动隐藏不能让用户失去内容位置提示。移动端、强制颜色和无脚本回退也要按项目支持范围实测。
滚动条的完整验收项
验收不要只看有没有滚动条
自定义滚动条最容易漏的验收点是布局稳定性。
验收时同时检查尺寸、初始化状态和回退行为:
- hover 前后,滚动容器的
clientWidth和offsetWidth不应该变化。 - hover 前后,关键 grid item 的
DOMRect不应该变化。 - 如果应用像本文的扩展实现一样维护
data-scrollbar-engine,初始化成功后应标为overlay,失败后应标为native;这是应用状态,不是库自动添加的属性。 - 滚动到底时,OverlayScrollbars 的 handle 不应该跑出可视区域。
- 键盘 focus 进入可滚区域时,也应该能显示滚动提示。
- 插件 feature 重复运行后,不应该重复初始化同一个目标,也不应该留下多组自绘滚动条节点。
- 首帧检查不能只看初始化后的截图;打开动态弹窗时要观察自绘条挂载前是否闪现原生条,以及初始化失败时是否还能看到可操作的滚动提示。
- 如果实验性接管
body,要额外验证window.scrollTo(0, 0)、浏览器刷新滚动恢复、锚点跳转、页面内查找定位、弹窗锁滚动和无限流触底;库取消初始化时,页面应该回到原生滚动条,不应该留下半套隐藏样式。
对于维护了这组应用状态的组件,Playwright 里可以写成这种白盒断言:
const panel = page.locator('.upload-panel__grid');
const item = panel.locator('.upload-panel__slot').first();
const before = await item.boundingBox();
const beforeSize = await panel.evaluate((element) => ({
clientWidth: element.clientWidth,
offsetWidth: element.offsetWidth,
}));
await panel.hover();
const after = await item.boundingBox();
expect(before).not.toBeNull();
expect(after).not.toBeNull();
expect(after!.x).toBe(before!.x);
expect(after!.width).toBe(before!.width);
const size = await panel.evaluate((element) => ({
clientWidth: element.clientWidth,
offsetWidth: element.offsetWidth,
engine: element.getAttribute('data-scrollbar-engine'),
}));
expect(size.clientWidth).toBe(beforeSize.clientWidth);
expect(size.offsetWidth).toBe(beforeSize.offsetWidth);
expect(size.engine).toBe('overlay');
这里分别比较 hover 前后的 clientWidth 和 offsetWidth,不要求两者相等:边框本身也会造成差值。截图适合最终视觉回看;检查这次抖动时,直接量 DOMRect 更容易定位,也较少受抗锯齿影响。