跳到正文

我所理解的 OverlayScrollbars 最佳实践(1):原生滚动条与覆盖式原理

我所理解的 OverlayScrollbars 最佳实践

  1. 原生滚动条与覆盖式原理(当前)
  2. 原生 JS、React、Vue 与浏览器扩展接入
  3. 问题排查

上传面板原本排得整整齐齐,多放一行图片,最右边那列就窄了;删掉几张图,列宽又恢复。要查是不是滚动条在挤内容,可以让同一个容器在刚好放得下和多一行之间切换,比较两次的 clientWidth。设置了 overflow: auto 的局部容器也会经历同样的变化。在使用占位式滚动条、且没有预留槽位的环境中,这不只是多出一条视觉提示:内容的可用宽度会随之变化,居中的正文、网格列宽和文字换行都可能跟着动一下。

默认外观也不统一。同一个页面在 Windows 和 macOS 上,滚动条的粗细、轨道、按钮和显隐方式可能不同;系统设置还会改变它是否常显、是否覆盖在内容上。浏览器会沿用操作系统提供的部分滚动条表现,这套默认样式未必适合页面自己的设计。放进窄侧栏、半透明抽屉或精细排版的弹窗后,较宽的轨道和不协调的颜色尤其容易显得突兀。

即使滚动条一直存在,占位本身也会影响对齐。容器明明设置了相同的左右 padding,右侧却还要容纳一条滚动条,内容到外框的视觉留白便不再对称。如果标题和底部按钮在滚动区外,只有中间正文被滚动条挤窄,还可能出现上下区域的内容边缘对不齐。此时反复微调 padding,只是在为某种滚动条宽度做补偿,换个平台未必仍然合适。

浏览器滚动与滚动条的占位

一个元素能不能滚动,核心不取决于滚动条长什么样,而取决于它有没有形成可滚动溢出区域。内容尺寸超过可视区域,且 overflow 允许滚动时,浏览器会给这个元素建立 scroll container。用户真正看到的可视窗口通常叫 scrollport;内容总尺寸和 scrollport 的差值,决定了 scrollTop / scrollLeft 能移动的范围。

页面根滚动又是一个特殊版本。普通内部容器的滚动状态在元素自己身上,业务代码会读写 element.scrollTop;页面根滚动的位置可以通过 window.scrollY 读取、通过 window.scrollTo() 调整,也会受到浏览器刷新后的滚动恢复、锚点跳转和页面内查找的影响。也正因为它牵涉浏览器级能力,插件直接接管 body 要比接管某个评论弹窗或图片列表危险得多。

滚动条本身只是这个滚动状态的视觉和交互外壳。浏览器先知道 scrollport 有多大、内容有多长、当前位置在哪里,再把这些比例映射成 thumb 的长度和位置。内容越长,thumb 越短;越往下滚,thumb 越靠下。这个长度不是 scrollbar-width 里的 width,也不是 CSS 里随手写一个 height: 10px 就能决定的。

前面的宽度变化,需要区分两种滚动条模型:classic scrollbar 放在专用槽位(gutter)里,占用布局空间;overlay scrollbar 浮在内容上,不占布局空间。选择哪种模型由浏览器和系统环境决定,不能仅凭 Windows 或 macOS 就断定所有用户的表现。

因此,无论是内容高度变化触发显隐,还是 hover 时切换原生条,横向抖动的根因通常都是 scrollport 的可用宽度变化。要同时避免显隐挤压和常驻槽位造成的留白,覆盖式滚动条更符合这个布局目标。

改变原生条宽度会挤内容,overlay 只改变覆盖层

原生 CSS 可以调整哪些部分

引入滚动条库之前,先区分想改的是颜色、厚度、占位还是手柄交互。这几件事由不同机制负责,原生 CSS 已经能解决其中一部分。

标准属性调整颜色和厚度

scrollbar-width 在 CSS Scrollbars Level 1 中表达滚动条厚度,接受 auto、thin 和 none。它给浏览器一个普通、较细或隐藏的提示,不负责精确指定 10px,也不负责设置手柄沿滚动方向的长度。

.panel {
  overflow: auto;
  scrollbar-width: thin;
  scrollbar-color: #64748b #e2e8f0;
}

scrollbar-color 的第一个颜色用于手柄,第二个用于轨道,auto 则沿用平台表现。只想让原生条融入页面主题时,这组属性就很合适;颜色仍需保证对比度,强制颜色模式也要按浏览器实际行为验证。标准属性的用法

纵向滚动条变细,表现为宽度变小;横向滚动条变细,表现为高度变小。两者调整的都是厚度。Chromium 的早期实现也是让 scrollbar theme 读取这个属性来计算 thickness 和 margin,没有给页面作者开放一个任意设置手柄长度的盒模型。

WebKit 伪元素提供更细的局部样式

非标准的 ::-webkit-scrollbar 系列伪元素能进一步调整轨道、手柄、圆角和尺寸。在这套 API 中,width 对应纵向条宽度,height 对应横向条高度,还可以通过 :horizontal、:vertical 分别覆盖两个方向。WebKit 的原始介绍

.panel::-webkit-scrollbar {
  width: 10px;
  height: 10px;
}

.panel::-webkit-scrollbar-thumb {
  background: #64748b;
  border-radius: 999px;
}

这套写法没有成为统一的跨浏览器组件 API。标准 scrollbar-color、scrollbar-width 与私有伪元素同时出现时,还要核对当前浏览器究竟采用哪套样式,不能假定它们会按预想叠加。尤其当元素计算出的 scrollbar-color 不是 auto 时,私有伪元素样式可能被忽略;该值也可能从祖先继承而来。颜色属性与回退规则

gutter 控制预留空间,不负责统一外观

如果主要问题是占位式滚动条出现时挤压内容,可以先使用 scrollbar-gutter: stable,让槽位从一开始就存在。如果还希望两侧留白对称,可以使用 stable both-edges:

.panel {
  overflow: auto;
  scrollbar-gutter: stable both-edges;
}

stable 保留经典滚动条的槽位;both-edges 在另一侧也预留对应空间。它能让内容保持稳定、两侧留白对称,代价是两边都会占用宽度。对本来就覆盖在内容上的原生 overlay scrollbar,这个属性不会额外创建槽位,也不会把浏览器切换成另一种滚动条模型。槽位的规范定义

整页预留槽位时,还要注意根元素的规则:设置在 html 上会应用到视口,但不会像某些 overflow 行为那样从 body 自动传播。局部容器则把属性放在实际滚动的节点上。

逻辑尺寸与滚动方向是两套坐标

inline-size、block-size、min-inline-size 和 min-block-size 是普通盒模型的逻辑尺寸,会跟随 writing mode 变化;它们不直接表达「滚动条厚度」或「手柄沿轴长度」。逻辑尺寸说明

因此,不能只把一组 min-width / min-height 换成逻辑属性,就期待横向、纵向手柄自动拥有正确的最小长度。后面选择 OverlayScrollbars,也是在选择一套已经区分滚动方向、轨道厚度和手柄尺寸的组件契约。

旧样式里有时会看到 overflow: overlay。在 CSS Overflow 规范里,它是 auto 的旧别名,不能靠它要求浏览器把原生条画到内容上。如果只想稳住列宽,可以预留槽位;如果希望手柄盖在内容上,同时统一不同平台的外观,就要换一种做法。

为什么选择 OverlayScrollbars

我希望滚动条显隐时内容宽度保持稳定,也希望页面、弹窗和列表能使用一致的外观。因此,能控制源码的自有项目,我优先用 OverlayScrollbars 统一滚动条体验;项目已有满足需求的 Scrollbar 组件时就复用。样式、尺寸同步和手柄拖动交给成熟组件,业务代码保留内容与滚动行为。

OverlayScrollbars 隐藏原生滚动条,生成可定制的覆盖式轨道与手柄,滚轮、触摸等滚动仍然由浏览器处理。它最有用的地方,是把下面几件重复工作集中起来:

  • 滚动条显隐不再改变内容可用宽度,列表和居中布局不需要跟着重排。
  • 页面、弹窗和局部容器使用同一组主题变量,不必分别维护各浏览器的滚动条伪元素。
  • 内容追加、图片加载、字体和容器尺寸变化后,库负责同步手柄几何。
  • 应用继续使用原生滚动位置与事件,并能在组件退出时明确销毁增强。

自己画一个 thumb 并不难,长期成本在于它必须同时跟踪 scrollTop、scrollHeight、clientHeight、内容变化和拖动状态。我的选择是复用库已有的观察与更新机制,不在每个业务面板里重做一套。

增强会增加 JS、节点和观察器,不能据此宣称页面性能更好。OverlayScrollbars 也不负责虚拟列表、聊天自动追到底部、背景滚动锁或焦点管理。原生条已经满足需求,或者第三方编辑器自带了滚动实现时,应保留已有机制,避免叠加两套接管。

在同一份内容上比较显隐

下面的两栏使用相同内容:左栏保留原生条,右栏使用 OverlayScrollbars。先比较显隐时的宽度,再追加内容观察手柄;此演示没有预留 gutter,也没有首帧预隐藏桥接。

滚动条显隐是否改变内容宽度正在加载代码工作区...

在演示中切换左侧原生条的隐藏状态,并观察两栏的 clientWidth;再追加内容、滚动右侧列表。覆盖式手柄的出现不应改变右栏宽度,内容增长也不需要重建实例。如果系统原生条本来就是 overlay,左栏可能同样没有宽度变化,这是系统模型差异,演示会保留实际测量值。

OverlayScrollbars 怎样保留原生滚动

它在原生滚动区域上增加了一套同步的轨道和手柄:原生条被隐藏,但浏览器仍然负责移动内容,覆盖层根据真实滚动状态显示位置。下面按本文演示使用的 2.17.0 解释这套分工;它与 CSS 原生 overlay scrollbar 是两个不同的概念,后者是浏览器自己的滚动条模型。

viewport 承载内容,覆盖层显示位置

viewport 是真正能改变 scrollTop 的节点。滚轮、触摸和键盘操作先作用于这个原生滚动区域;库生成的 track(轨道)和 handle(手柄)则提供位置提示与拖动入口。拖动 handle 时,库会反过来修改真实滚动位置,内容仍然在原生容器中滚动。

真实 viewport 与覆盖层之间的双向同步

图中把滚动条放在稳定外壳中,viewport 保留原节点;这个外壳是滚动条的挂载位置(slot),不必与库定义的 host 是同一个节点。默认初始化也可以生成内部包装;库通过 instance.elements() 暴露 host、viewport、track 和 handle 等节点,接入者不必从 class 名猜谁在滚动。官方实例元素说明

保留原生滚动也不等于覆盖层完全没有成本。浏览器可以照常处理滚动,但手柄绘制、内容观察和初始化仍然有自己的工作。Height 团队在 2022 年介绍自定义滚动条时,也同时关注跨平台一致性与可发现性;这篇文章的中文译文值得参考。一个实用的取舍是:外观可以统一,滚动入口仍应容易发现,轨道也要避开正文和操作按钮。

手柄长度和位置来自两组比例

以正常从上往下滚动的纵向列表为例,先只看四个量:可视高度 V、内容总高度 C、当前滚动距离 S 和轨道长度 T。内容确实溢出时,可以用下面的简化模型建立直觉:

手柄长度 h ≈ T × V / C
滚动进度 p = S / (C - V)
手柄偏移 y = p × (T - h)

第一组比例回答「能看到多少内容」,第二组回答「已经走过多少可滚动距离」。内容高 1000px,可视区和轨道都长 200px,手柄便约为 40px;向下滚动 400px,是总滚动范围 800px 的一半,手柄因此移动其可用行程 160px 的一半,也就是 80px。

可视比例决定手柄长度,滚动进度决定手柄偏移

实际主题还会约束手柄最小、最大长度,所以偏移必须用实际手柄长度计算,不能永远假定它严格等于 T × V / C;没有溢出时,也不应继续计算除以零的进度。横向、RTL、反向布局、缩放和浏览器的取整误差还需要进一步处理。这正是成熟库比一段比例公式多做的工作。

在 2.17.0 的手柄实现里,getViewportPercent() 先算可视范围占比,随后更新手柄长度;位置同步还会按环境选择 ScrollTimeline 动画或滚动状态更新。上面的公式解释的是映射关系,不代表库在每次滚动时都用 JS 重新读取所有尺寸。

内容变化后,更新几何而不是重建实例

滚动位置变化与滚动范围变化要分开:用户滚动时,通常只需要同步手柄位置;追加文本、容器缩小、字体变化或图片加载,则可能需要重新测量范围、调整手柄长度和溢出状态。

库通过尺寸观察、DOM 变化观察与元素事件获得这些更新信号。ResizeObserver 关注尺寸,MutationObserver 关注内容与属性变化;对于仅靠它们无法完整覆盖的图片加载、动画结束等情况,还可以补充 update.elementEvents。观察到变化后,库重新核对几何,不要求业务代码主动重装一遍滚动条。官方更新选项

2.17.0 把 mutation、resize、元素事件和环境变化的防抖分别配置,不能把它们都当成同一个定时轮询。默认 mutation 使用 [0, 33],其中 0 表示借助 requestAnimationFrame 合并调度,33 是最大等待参数;默认 resize 则为 null。只有确实观察到更新过密或漏更新时,才按对应信号调整。项目中的流式文字和图片缩放如何补充信号,见第三篇。

总结

原生滚动条已经提供颜色、厚度与槽位控制。接受平台表现和固定留白时,可以先用 CSS 完成调整;需要覆盖式视觉、统一主题和手柄交互时,OverlayScrollbars 把这部分重复工作集中起来,内容滚动仍留给浏览器。

接入时真正需要保护的是原生 viewport、更新信号和生命周期。具体初始化和主题配置见第二篇:项目接入;首帧回退和常见故障见第三篇:问题排查。