1. 先从一次业务迭代说起自定义滚动条为何成了“工程”1.1 需求演进从改颜色到覆盖式UI自定义滚动条这事我刚入行那会儿觉得是个不起眼的活。设计稿上给滚动条标了个 #CCCCCC我打开控制台写一段::-webkit-scrollbar-thumb就交差了。那时候自定义滚动条约等于“换个颜色”改完收工下一屏继续切图。真正让我意识到这事需要被认真对待的是一次数据可视化大屏项目。需求方提了三件事第一滚动条必须变窄变淡不能抢图表的风头第二滚动条要自动隐藏鼠标离开滚动区域就消失第三在某些内嵌列表里滚动条样式要跟页面整体主题一起切换白天模式窄滚动条带浅色渐变夜间模式滚动条变成细线发光。我当时第一反应是这有什么难的加个overflow: overlay不就完事了吗。等到真去实现被现实抽了好几个嘴巴。Chrome 在较新版本里已经逐步弱化了overlay支持Firefox 根本不吃这一套而::-webkit-scrollbar这套私有伪元素方案在 Firefox 上完全是废的。更麻烦的是那几个带复杂交互动效的列表光改scrollbar-width根本满足不了视觉稿的要求——设计稿里滚动条是圆角胶囊靠近内容边缘还有半透明遮罩鼠标悬停时滑块的亮度和宽度都有动画。从我这些年的经验看一旦自定义滚动条的需求涉及到下面四项中的任意两项它就从一个 CSS 问题变成了工程问题滚动条UI需要跟随状态变化悬停、拖拽、自动隐藏、主题切换滚动容器的内容长度不固定需要实时感知内容变化对滑块与内容滚动位置的同步精度有要求比如拖动滑块要做到逐帧对齐项目需要同时兼容 WebKit、Firefox、Blink 的新旧版本所以这篇文章我不打算给一段“万能CSS代码”就完事而是完整拆解我在这类需求上踩过的坑、用过的方案、以及最终的工程化设计。核心思路可以先说透了自定义滚动条的正确姿势不是去美化浏览器原生的滚动条而是用一层“看起来是滚动条、实际上只是UI”的覆盖层替代原生滚动条在视觉上的存在感同时让原生滚动行为在底层照常工作。1.2 这篇文章适合谁看如果你是刚接触前端的同学这篇文章帮你建立“滚动条不只是 overflow: auto” 的完整认知如果你已经在项目里被自定义滚动条折磨过这篇文章提供一个可以直接落地的封装方案如果你是在面试中被问到“如何实现自定义滚动条”看完这篇文章你会知道怎么从样式、行为、性能、无障碍四个维度去组织答案而不是甩出三行::-webkit-scrollbar。说白了自定义滚动条是一道非常典型的前端工程题。它考的不是你会背多少API而是你在一个看似微小的交互细节上有没有能力做系统性的取舍。2. 浏览器原生滚动条的可控范围与硬边界2.1 三大阵营的现状先把手上的牌摆清楚。2025年这个时间点各浏览器的滚动条样式方案大概是这样一幅局面引擎代表性浏览器样式方案当前状态WebKit/BlinkChrome、Edge、Safari部分::-webkit-scrollbar系列伪元素成熟但属于非标准属性有被调整的风险GeckoFirefoxscrollbar-widthscrollbar-color官方标准支持有限只有颜色和宽度两档新标准方案Chrome 121scrollbar-width、scrollbar-color逐步覆盖 Firefox 已有的能力但同样不提供细粒度伪元素这里最尴尬的一点在于主流的、能真正定制滚动条外观的能力在::-webkit-scrollbar上但它在标准化的道路上一直走得慢吞吞。Chrome 倒是把scrollbar-width和scrollbar-color这两个标准属性带上了可这两个属性能控制的颜色和粗细无法满足复杂设计稿。Firefox 的scrollbar-color只能设置轨道和滑块的颜色滑块长度、圆角、悬浮态、动画一概不管。Safari 对::-webkit-scrollbar的支持也不是完全对齐 Chrome 的某些伪元素在 Safari 里效果达不到预期。所以现实就是任何想对滚动条做精细视觉定制的需求都不能指望只靠原生 CSS 一个方案吃遍所有浏览器。2.2 原生CSS方案的适用边界尽管原生方案有限制但我依然建议你先把这层能力用足用白不用。如果设计稿只有两档要求——颜色对了、大小粗了细了——直接上原生方案最安全、性能最好。具体的写法这里不展开太多给一个我项目里在用的最小基础样式/* 标准属性Firefox Chrome 新版都吃 */ .scrollable-area { scrollbar-width: thin; scrollbar-color: rgba(100, 116, 139, 0.4) transparent; } /* WebKit 系列针对桌面 Chrome/Edge/Safari 做精细定制 */ .scrollable-area::-webkit-scrollbar { width: 6px; } .scrollable-area::-webkit-scrollbar-thumb { background: rgba(100, 116, 139, 0.4); border-radius: 999px; } .scrollable-area::-webkit-scrollbar-thumb:hover { background: rgba(100, 116, 139, 0.7); }有个技术细节要提醒很多文章说::-webkit-scrollbar作用在html上可以用width: 6px控制页面滚动条但真正工程化的时候我们通常不为整个页面做定制滚动条而是为某个容器做。如果要做页面级别建议作用在*选择器上然后单独覆盖而不是只写html否则不同元素出现滚动条时的样式会不一致。原生方案真正的边界在以下几点没有状态机悬停、按下、滚动中这些状态要靠伪类兜着能做的动画只有过渡而且 WebKit 的某些版本对滚动条过渡支持不稳定没有自动隐藏只能通过scrollbar-width: none粗暴隐藏但那样就失去了滚动条应有的视觉提示横向滚动条与纵向滚动条无法独立精细控制::-webkit-scrollbar:horizontal和:vertical可以分别设置但也只限于颜色尺寸做不到设计稿里那些悬浮交互移动端其实不需要你操心Android 和 iOS 上滚动条多数时候是透明的或覆盖式的用户根本看不见。你费劲定制的样式在移动端反而可能变成一条丑陋的固定黑边如果你只是做个后台管理页面、内部工具原生方案足够了。但你要是做的产品是给大量外部用户用的且视觉团队对细节有执念请往下看。2.3 我踩过的原生方案坑这里分享两个实际踩过的问题帮大家少走弯路。第一scrollbar-width: thin在 Firefox 里不是所有版本都能和scrollbar-color搭配出预期效果。早期版本里thin会把滑块和轨道一起压缩视觉上滚动区域整体凹进去一块。解决方式简单粗暴干脆不在 Firefox 上追求完全一致的视觉让 Firefox 用户用系统原生的细滚动条把精细定制留给 Chrome/Edge/Safari 这套用户群更大的平台。第二Chrome 新版本对::-webkit-scrollbar的某些组合开始提示弃用警告。我在某个项目里用了::-webkit-scrollbar-track-piece和::-webkit-scrollbar-corner的组合结果控制台一片告警。虽然不是不能用但这种非标准能力依赖越深将来升级浏览器的风险就越大。这也是我在新项目里越来越倾向覆盖式方案的原因之一。3. 覆盖式滚动条的核心设计替身UI正主滚动3.1 一句话说透设计思路原生方案不够用的时候我在工程上选择的做法是做一个覆盖在滚动容器之上的“替身滚动条”UI它的作用是模拟原生滚动条的视觉表现但它本身完全不具备滚动能力真正的滚动行为仍然由底层容器的 overflow: auto 接管。很多新手第一次做自定义滚动条的时候脑子里的方案是这样的把容器的overflow-y设置成hidden然后监听wheel事件手动修改容器的scrollTop。这个方案我强烈不建议。原因有三滚轮事件的preventDefault()行为在各浏览器不一致键盘滚动、滚动捕捉、触摸板惯性滚动全都丢失scrollTop手动赋值和浏览器原生滚动的节奏始终对不上容易产生掉帧和延迟。更重要的是一旦移动端用户用触摸手势滚动你会发现原生滚动体验完全被破坏那种“卡一下才能动”的体验很难看。正确的做法是保留原生滚动只替换视觉。外层容器的overflow-y保持auto原生滚动条要么被彻底隐藏要么被覆盖。我们在容器内层或容器旁边放置一个绝对定位的轨道和滑块滑块的位置、高度通过监听scroll事件计算出来保持和滚动进度 1:1 同步。用户对滑块的拖拽操作本质上也只是“把滑块移动到某个位置然后把容器 scrollTop 设置到对应位置”滚动行为本身还是交给浏览器。3.2 结构设计滚动层、轨道层、滑块层我在工程化封装时的 DOM 结构如下以纵向滚动条为例div classscrollbar-container div classscrollbar-content tabindex0 !-- 实际滚动的子内容 -- /div div classscrollbar-track div classscrollbar-thumb/div /div /divscrollbar-container定位上下文负责限制整体尺寸设置position: relativescrollbar-content真正产生滚动的元素设overflow-y: auto同时负责接收键盘焦点scrollbar-track轨道层绝对定位在容器右侧设pointer-events: auto接收拖拽事件scrollbar-thumb滑块层绝对定位在轨道内部高度和位置由 JS 动态计算对于 WebKit 内核的浏览器记得给scrollbar-content设置scrollbar-width: none或::-webkit-scrollbar { display: none; }把原生滚动条视觉隐藏掉。这里有个兼容细节scrollbar-width: none已经是标准属性支持度不错但如果还跑在比较老的 Electron 版本里可能要继续靠 webkit 伪元素隐藏。3.3 滑块几何计算从比例到像素滑块的核心计算就两个数滑块高度和滑块偏移量。滑块高度本质上是“可视区域占整个滚动内容的比例”。公式thumbHeight trackHeight * (clientHeight / scrollHeight)举个例子容器可视高度 500px内容总高度 2000px轨道高度也是 500px。那么滑块高度是500 * (500 / 2000) 125px。这个公式的意义在于内容越长滑块越短用户一眼就能看出剩余内容还有很多。滑块偏移量把当前滚动位置线性映射到轨道上的可用范围thumbTop (scrollTop / (scrollHeight - clientHeight)) * (trackHeight - thumbHeight)注意分母是scrollHeight - clientHeight因为当滚动条滚到底时scrollTop等于这个差值此时滑块应该正好贴到轨道底端。轨道上滑块的可用移动距离是trackHeight - thumbHeight两部分对应转译成比例。实际工程中我会加上最小高度限制避免内容超长时滑块缩成一个几乎看不见的点。通常设个min-height: 24px。但如果内容实在太长滑块长度低于最小值后拖拽时的精度会变差此时可以考虑按比例放大滑块并同步修正偏移这个话题后面拖拽部分会细说。3.4 自动隐藏的两种实现机制自动隐藏是我遇到最多的需求之一。实现方式有两种工程上各有适用场景。第一种是overlay 式。轨道层使用绝对定位叠在内容上面默认opacity: 0鼠标悬停在滚动容器边缘、或者内容滚动时轨道和滑块浮现一段时间通常 600ms 到 1s无操作后淡出。这种方式适合视觉上不想让滚动条占据额外空间的产品缺点是滑块浮在内容上方某些高亮文本或图形会被遮挡。第二种是位移式。容器布局时预留轨道宽度滚动条默认缩到容器边缘之外用transform: translateX()或轨道父级宽度变化需要时滑入。这种适合内容区需要完整展示的场景缺点是需要保证父级不裁剪或者布局预留空间工程上比 overlay 稍微复杂一些。我封装时通常把两种机制通过配置项切换视觉上默认走 overlay如果想要内容完全不被遮挡就切到位移式。实现自动隐藏时需要注意一个细节滚轮滚动这类高频事件里如果每次滚动都重置隐藏定时器实际上用户在高频滚动时滚动条会一直处于显示状态等停下来了再开始计时隐藏。这个逻辑用事件节流内部维护一个 timer 即可我在后面事件绑定部分会连同性能一起讲。4. 事件绑定与高频性能调优别让滚动条拖垮滚动4.1 你该监听谁不该监听谁很多新手做自定义滚动条上来就给容器绑一堆事件scroll、wheel、mouseenter、mouseleave、mousemove、mouseup、touchmove然后发现页面卡得不行。问题不在于事件绑定了多少而在于你在高频回调里做了什么。我的事件绑定策略分三类滚动位置同步只监听scroll事件被动监听在回调里计算滑块位置尺寸同步用ResizeObserver监听容器和内容尺寸变化不占用交互线程拖拽交互仅在用户按下滑块时才在document上临时绑定mousemove和mouseup松手即解绑划重点scroll事件一定要用被动监听即绑定的时候传{ passive: true }。原因很简单监听器内部不调用preventDefault()主动声明被动可以让浏览器在滚动主线程上不等待这个监听器执行完就继续滚动显著降低卡顿感。如果你没有显式传passive在某些浏览器版本里滚动性能会差一大截。this.content.addEventListener(scroll, this.onScroll, { passive: true, });ResizeObserver 也很好理解容器尺寸变化比如侧边栏折叠时轨道高度和滑块高度都要重新计算。内容尺寸变化比如异步加载了更多列表项时总滚动高度变了滑块比例也要变。这个观察器是异步批处理的比scroll里做尺寸检测要高效得多。4.2 rAF 节流把每帧的同步放到帧末滚动事件的触发频率远超渲染帧率如果scroll回调里直接改 DOM每帧可能被触发多次白白浪费渲染。我的做法是给“更新滑块位置”套一层requestAnimationFrame节流handleScroll() { if (!this.rafId) { this.rafId requestAnimationFrame(() { this.syncThumbPosition(); this.rafId null; }); } }一次性讲明白这个节流为什么好用。requestAnimationFrame会在浏览器开始渲染一帧之前执行回调保证了这一帧内的滚动位置读取和滑块位置写入都是针对同一帧状态不会出现滑块比内容慢半拍或者快半拍的问题。当一帧内滚动事件被触发 10 次我们只在帧末同步一次既保证了视觉同步又把 DOM 操作压缩到最小值。这里提一个工程细节组件销毁时一定要cancelAnimationFrame否则组件已卸载回调却还在执行轻则报警告重则操作已释放的 DOM 引用。4.3 拖拽滑块的完整交互链拖拽是自定义滚动条交互里最容易出问题的部分。我踩过的坑包括拖拽时页面文本被选中、鼠标移出组件范围后拖拽失效、滑块拖拽速度与内容滚动速度偏移。完整流程可以拆成四步第一步按下thumb 上绑定 pointerdown。记录按下时的鼠标 Y 坐标和滑块的当前 top 值。如果支持 PointerEvent现在主流浏览器基本都支持直接用setPointerCapture把指针捕获到滑块上这样鼠标移出组件范围也不会丢事件根本不需要在 document 上临时绑定。第二步移动pointermove。计算deltaY 当前坐标 - 按下的坐标得到新滑块 top 按下时滑块 top deltaY。然后算出新 top 对应的滚动位置const percent newThumbTop / (trackHeight - thumbHeight); const scrollTop percent * (scrollHeight - clientHeight);第三步约束边界。把newThumbTop夹在[0, trackHeight - thumbHeight]之间。边界处理不好滑块会被拖出轨道。第四步释放pointerup。释放指针捕获清理临时状态。这里有一个看似小但影响体验的细节按下滑块之后应该立刻设置user-select: none防止拖拽过程中页面文本被选中。用 PointerEvent 可以在按下时给 body 加一个类释放时移除。4.4 键盘滚动与触摸板的天然兼容前面强调过滚动行为交给原生容器那么大一个天然优势就是键盘方向键滚动、空格 PageDown、Home/End 键滚动全部天然有效。你不需要写任何额外的键盘事件监听只要保证容器本身可以接收焦点设置tabindex0这些行为浏览器全部帮你搞定。触摸板惯性滚动也一样。MacBook 触控板上的惯性滚动是一个高频、减速、持续的scroll事件序列由于滚动行为是原生的滑块同步只是单纯地“跟着 scrollTop 走”惯性响应非常自然。如果当初选择手动维护scrollTop的方案这里就全崩了。还有一个小细节当焦点在容器内用户按下方向键滚动时浏览器滚动的是容器内容而不是页面。如果你想让页面感知到容器滚动位置可以由容器内收到焦点滚动时抢焦点也可以靠focus事件转移这取决于交互设计不是滚动条组件本身的责任。5. 无障碍与边界处理验收时最容易翻车的三件事5.1 键盘用户到底能不能滚动我以前犯过一个错误为了让自定义滚动条视觉上更好看把pointer-events: none加在了整个滚动区域上。结果键盘用户根本无法交互。后来才明白无障碍的底线是自定义滚动条永远不能阻塞用户的滚动能力。正确做法是滚动容器本身必须有焦点tabindex0滑块不需要 tabindex。用户敲键盘时容器收到方向键事件后正常滚动滚动位置再由我们的 scroll 监听同步到滑块UI上。滑块本身可以视为纯装饰和鼠标交互元素。还要给容器加上roleregion和aria-label描述其滚动能力这样屏幕阅读器也能知道这是一个可滚动区域。5.2 prefers-reduced-motion 的适配自动隐藏时轨道淡入淡出通常通过 CSS transition 实现。有用户开启了“减少动态效果”的系统偏好这时过渡动画反而会造成不适。我的处理是检测prefers-reduced-motion: reduce命中后直接去掉过渡让轨道在显示/隐藏之间瞬切或者干脆固定显示不隐藏。media (prefers-reduced-motion: reduce) { .scrollbar-track { transition: none; } }这个细节在验收时一般不测但产品一旦被无障碍评审机构盯上这属于硬伤。提前做好不亏。5.3 Windows 上 overlay 滚动条的双轨问题Windows 系统的某些 Chrome 版本默认 overlay 滚动条在内容上面浮现内容会有不同程度的偏移或遮挡。当我们的自定义轨道层也叠在内容上时会出现“两套滚动条影子”的观感短暂的闪烁后原生 overlay 滚动条隐藏自定义滚动条出现。解决方式是检测 overlay 滚动条支持情况。在工程上我会依据window.innerWidth - document.documentElement.clientWidth是否大于零来判断是否存在 overlay 滚动条通常是 15px 左右。如果检测到系统 overlay 滚动条就把覆盖式滚动条的判断交给组件内部自动调整让轨道层位置与滚动行为错开尽量不与原生滚动条视觉冲突。说一个实在的经验真正稳妥的策略是用scrollbar-gutter: stable为内容层预留滚动条空间同时在轨道层增加一个补偿宽度。这样系统 overlay 滚动条出现时内容不会横向抖动我们的自定义轨道只要做轻微偏移就能对齐。具体偏移量依系统而定需要写个小工具函数。5.4 容器边缘双击与内容聚焦的策略另一个低频但真实的需求用户在滚动区域内滚动时如果内容下面有空隙滚轮一冲容易冲到容器底部。如果你希望用户点按轨道空白处能翻页类似原生滚动条点击轨道翻页可以给轨道加一个点击事件算出点击位置与滑块位置的关系按比例翻页。但如果产品没有这个需求就不要加加上反而容易误触。6. 封装成组件接口设计、主题化与工程落地6.1 对外API怎么设计做工程化封装最终要交付一个别人能直接用的组件。我的接口设计通常长这样interface ScrollbarOptions { /** 是否自动隐藏 */ autoHide?: boolean; /** 自动隐藏延迟毫秒 */ autoHideDelay?: number; /** 轨道位置覆盖式还是侧边式 */ mode?: overlay | siderail; /** 是否最小滑块高度 */ minThumbHeight?: number; /** 主题变量 */ theme?: Recordstring, string; }组件暴露的方法一般有update()手动重新计算滑块尺寸和位置、destroy()解除监听、回收内存、on(event, handler)滚动状态回调。实际使用中最容易被遗忘的是update()。当容器内部的 DOM 节点是动态渲染的时候内容高度在ResizeObserver触发之前可能还没更新完成此时调用update()能强制同步。我的经验是在异步数据加载完成后主动调用一次而不等观察器自己反应能避免几百毫秒的滑块尺寸闪烁。6.2 用CSS变量做主题化跨项目复用意味着组件内部不能写死颜色。我把颜色和尺寸全部抽象成 CSS 变量.custom-scrollbar { --sb-track-width: 6px; --sb-thumb-radius: 999px; --sb-thumb-bg: rgba(100, 116, 139, 0.4); --sb-thumb-bg-hover: rgba(100, 116, 139, 0.6); --sb-thumb-bg-active: rgba(100, 116, 139, 0.8); --sb-track-bg: transparent; }使用时上层只需要修改变量值就能获得一套完全不同的外观。这也是工程化组件的标准姿势行为由 JS 负责外观由 CSS 变量负责。不仅组件内部不会因为颜色改动重新发版业务方也能在运行时通过修改 CSS 变量实现主题切换比如昼夜模式的动态切换只需要在根节点切换>