企业官网建设流程全解析

Polar 前端性能实践：为 React 滚动事件启用 Passive 事件监听器

【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar

本篇技术指南以 Polar 前端仓库内置的 Vercel React Best Practices 技能规则 为主体，系统讲解{ passive: true }对 touch、wheel、scroll 等滚动相关事件的性能影响、适用场景与反模式，并结合 Polar 代码库中的真实实现（useStickToBottom）给出可直接落地的工程实践。读完本文，你将理解被动事件监听器消除滚动延迟的底层原理，掌握在 React/Next.js 项目中正确声明 passive 并避免preventDefault()失效陷阱的完整方案。

背景：滚动"卡顿"的根源与 passive 的由来

浏览器通常把滚动交由独立的合成器线程处理，以保持 60fps 的流畅度。但当你通过addEventListener()监听touchstart、touchmove、wheel等事件时，情况发生了变化：浏览器无法预知监听器内部是否会调用preventDefault()来取消默认滚动行为，因此必须等待所有监听器在主线程执行完毕，才能决定是否继续滚动。

这一"先执行 JS、再决定滚动"的串行等待，正是触屏与滚轮操作出现肉眼可见延迟（scroll delay）的直接原因——监听器越多、执行越慢，延迟越明显。

Passive（被动）事件监听器正是针对这一问题的标准化方案：当你向浏览器声明passive: true，即承诺该监听器不会调用preventDefault()，合成器线程便无需等待，可以立即开始滚动。这正是规则文件 frontmatter 中impact: MEDIUM、impactDescription: eliminates scroll delay caused by event listeners的含义所在。

规则核心：给 touch 与 wheel 监听器显式声明 passive

Polar 技能包中的规则原文给出了明确的改法。先看错误写法——监听器未声明任何选项，浏览器出于安全会保守地等待执行结果：

useEffect(() => { const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX) const handleWheel = (e: WheelEvent) => console.log(e.deltaY) document.addEventListener('touchstart', handleTouch) document.addEventListener('wheel', handleWheel) return () => { document.removeEventListener('touchstart', handleTouch) document.removeEventListener('wheel', handleWheel) } }, [])

正确写法——为不需要阻止默认行为的监听器显式传入{ passive: true }：

useEffect(() => { const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX) const handleWheel = (e: WheelEvent) => console.log(e.deltaY) document.addEventListener('touchstart', handleTouch, { passive: true }) document.addEventListener('wheel', handleWheel, { passive: true }) return () => { document.removeEventListener('touchstart', handleTouch) document.removeEventListener('wheel', handleWheel) } }, [])

注意一个容易被忽略的细节：removeEventListener无需（也不必）重复传入{ passive: true }——浏览器匹配监听器是否相同只依赖capture标志，passive不参与匹配。上面的清理函数写法是正确的。

何时启用 passive，何时必须关闭

规则文件最后给出了两条清晰的判断准则，它们是决定passive取值的关键：

判断口诀很简单：只"读"事件，不"拦"事件，就用 passive；要拦截默认行为，就必须passive: false。

仓库实战：Polar 中 useStickToBottom 的 passive 用法

Polar 代码库中有一个非常契合本规则的真实案例：useStickToBottom.ts。该 Hook 用于让滚动容器在流式内容（如 AI 对话输出、实时增长的区块、图表高度变化）增长时始终"贴底"，同时不干扰用户主动滚动。

其核心思路是：通过ResizeObserver观察内容变化，用requestAnimationFrame把滚动写入合并到每帧至多一次，并在scroll事件中只读滚动位置来判定"是否处于底部"：

const onScroll = () => { const distance = scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight stickRef.current = distance < STICK_THRESHOLD_PX } const scrollTarget = scroller === document.scrollingElement ? window : scroller scrollTarget.addEventListener('scroll', onScroll, { passive: true })

关键点在于（源码第 60-79 行）：

• onScroll仅计算滚动距离并写入stickRef，从不调用preventDefault()，属于典型"只读滚动状态"场景，因此{ passive: true }完全正确且必要；
• 它同时配合ResizeObserver与requestAnimationFrame做写入合并，从"监听端不阻塞"与"写入端不频繁"两个方向共同保证滚动流畅；
• 在组件卸载的清理函数中同步removeEventListener与observer.disconnect()，避免泄漏——这与规则示例中的 useEffect 清理模式一脉相承。

从这个案例可以提炼出适用 passive 的判别特征：事件处理器内部只做状态记录、UI 同步或数据上报，不改变浏览器默认行为。

深入原理：passive 的底层机制与三个易错点

1. 默认值并不总是 false

规范层面addEventListener的passive默认值为false，但浏览器对部分事件类型在部分目标上会覆盖默认值。例如 Chrome 自 56 起对window、document、body上注册的touchstart/touchmove默认启用 passive 语义。依赖这类隐式默认值并不可靠（wheel事件与自定义目标上的行为因浏览器而异），显式声明{ passive: true }才是跨浏览器一致的稳妥做法。

2. passive 监听器中的 preventDefault() 会失效

一旦监听器以passive: true注册，在其中调用preventDefault()将被静默忽略（并触发控制台警告）。因此绝不能给"需要拦截默认行为"的监听器盲目加上 passive——这会让手势/缩放等自定义交互静默失效，且难以排查。

3. React 合成事件系统的隐含 passive

Polar 前端基于 React/Next.js（见 clients/apps/web 的 package.json）。从 React 17 起的事件委托实现看，React 在根容器上对touchstart、touchmove、wheel等事件以 passive 方式注册，因此在这些合成事件处理器中调用preventDefault()不会生效。如果需要实现自定义滑动、缩放等必须阻止默认行为的交互，应改用原生addEventListener并显式传入{ passive: false }，而不能依赖onTouchMove等合成事件。

兼容性注意

老旧浏览器会把options对象当作useCapture布尔值处理（对象转布尔恒为true），导致监听器意外变成捕获阶段注册。现代浏览器已无此问题，但若需兼容远古环境，可先做特性检测再决定是否传 options。

如何在 Polar 代码库中自查与落地

该规则文件属于技能包 Section 4 "Client-Side Data Fetching"（影响级别 MEDIUM-HIGH），与同节的 client-event-listeners.md（全局事件监听器去重） 共同构成客户端事件处理规范；完整编译版见 AGENTS.md，规则文件结构与 impact 级别定义见 README.md。

在 Polar 仓库中自查时，可聚焦clients/apps/web/src下的addEventListener调用（如 CompassHistoryMenu.tsx、appealCaseUnread.ts 等），逐一确认：

1. 监听touch、wheel、scroll类事件且不调用preventDefault()的，是否都声明了{ passive: true }；
2. 需要自定义手势/缩放、依赖preventDefault()的，是否用原生监听并显式{ passive: false }（而非依赖 React 合成事件）；
3. 每个 useEffect 中的addEventListener是否都有对应的removeEventListener清理；
4. 事件处理器内是否有同步的昂贵计算——passive 只是消除"等待"，监听器本身执行过慢仍会拖慢主线程。

小结

{ passive: true }是一个性价比极高的滚动性能优化：一行声明即可向浏览器交出"不会拦截滚动"的承诺，换取合成器线程的即时滚动。其适用边界非常清晰——纯观察型监听器（埋点、日志、状态记录）启用 passive；需要拦截默认行为的手势与缩放交互必须关闭。Polar 仓库中的 useStickToBottom 正是"只读滚动状态 + passive 监听 + rAF 写入合并"的标准范式，可作为新代码的参照模板。

【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar