尧图网页设计 
OpenMontage 前端性能优化用 Passive 事件监听器消除滚动卡顿延迟【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage滚动是 Web 页面最高频的交互之一而一个未声明passive的touch/wheel事件监听器就可能让整个页面的滚动产生可感知的延迟。本文基于 OpenMontage 仓库中.agents/skills/vercel-react-best-practices技能体系内的 client-passive-event-listeners.md 规则文档系统讲解被动事件监听器的原理、正确写法、适用边界并结合仓库源码结构给出可落地的代码审查清单。读完本文你将掌握如何为滚动相关监听器添加{ passive: true }、何时必须放弃 passive以及在 React 组件中如何安全地注册与清理这些监听器。一、规则背景来自 Vercel 工程团队的 React 性能规范该文档是 OpenMontage 仓库.agents/skills/vercel-react-best-practices技能包中的一条独立规则文件位于 rules/client-passive-event-listeners.md。整个技能包由 Vercel Engineering 维护、采用 MIT 协议发布目标是给 Agent 和 LLM 在「编写、审查、重构 React/Next.js 代码」时提供可自动执行的性能优化指南。规则文件通过 YAML frontmatter 声明元信息--- title: Use Passive Event Listeners for Scrolling Performance impact: MEDIUM impactDescription: eliminates scroll delay caused by event listeners tags: client, event-listeners, scrolling, performance, touch, wheel ---其中impact: MEDIUM中等优先级属于「渐进式性能提升」范畴位于技能包 8 个类别中第 4 类「Client-Side Data Fetching / 客户端侧优化」前缀client-之下impactDescription一句话概括收益——消除由事件监听器导致的滚动延迟tags便于检索的标签明确覆盖touch与wheel两类滚动来源事件。根据技能包入口 SKILL.md 的说明这套体系共包含 65 条规则、覆盖 8 个类别按优先级从 CRITICAL消除瀑布流请求、包体积优化到 LOW进阶模式排列每条规则文件都遵循 rules/_template.md 规定的「问题说明 错误示例 正确示例 适用上下文」四段式结构并可被构建脚本编译进长文版 AGENTS.md本文主题对应的完整章节位于其中 4.2 节。二、原理为什么滚动会被事件监听器拖慢浏览器处理滚动事件时存在一个关键环节滚动阻塞scroll blocking。对于touchstart、touchmove、wheel等与滚动相关的监听器浏览器在每次事件触发时都会等待监听器回调执行完毕再判断回调中是否调用了preventDefault()——因为一旦调用preventDefault()浏览器就必须取消默认的滚动行为。这条规则文档对此的描述非常精确Browsers normally wait for listeners to finish to check ifpreventDefault()is called, causing scroll delay.也就是说只要监听器没有声明passive浏览器就必须以「最坏情况」假设你会调用preventDefault()从而在每个事件帧内先跑完 JS 回调再决定是否滚动。当回调内部有日志输出、埋点上报、状态计算等耗时操作时这段等待时间就会直接叠加到滚动响应延迟上造成滚动「发沉」「跟手性差」的体验问题。passive 选项的语义向addEventListener传入{ passive: true }即向浏览器承诺「该监听器绝不会调用preventDefault()」。浏览器据此可以跳过上述等待环节在事件回调尚未执行完毕时就开始滚动渲染实现「即时滚动」。三、错误写法未声明 passive 的滚动监听器规则文档给出的错误示例在 React 组件中通过useEffect直接向document注册监听器且未传入任何选项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) } }, [])问题点在于touchstart与wheel都是滚动敏感事件未声明passive意味着每个事件都要经过「等待回调 → 检查 preventDefault」的完整流程回调只做了console.log典型埋点 / 追踪场景根本不需要preventDefault()等待纯属浪费从 React 最佳实践角度看这段代码虽然正确地做了清理return中移除监听器但仍属于「监听全局事件且不做去重」的模式——它与同目录下的姊妹规则 client-event-listeners.mdDeduplicate Global Event Listeners讨论的「N 个组件实例 N 个全局监听器」问题同源。四、正确写法为 touch 与 wheel 监听器启用 passive规则文档给出的正确示例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) } }, [])与错误写法唯一的差异就是第三个参数{ passive: true }——正是这一处修改让浏览器得以跳过滚动阻塞检查。代码审查要点可对照检查removeEventListener 必须与 addEventListener 匹配removeEventListener不需要也不应该传入passive但若你在注册时使用了capture: true移除时也必须传相同的 capture 标志否则监听器无法被正确解除会造成泄漏useEffect 清理函数不可省略在 React 中注册全局监听器务必在useEffect的返回函数中移除避免组件卸载后监听器残留空依赖数组[]的语义示例中监听器只注册一次回调通过闭包捕获即可若回调依赖了组件的 props/state则应考虑使用 ref 持有最新回调可参见技能包第 8 类 Advanced Patterns 中的advanced-event-handler-refs规则而不是简单地把依赖加进数组导致反复注册/注销。五、适用边界何时使用 passive何时必须放弃规则文档以两行明确的结论划定了边界Use passive when:tracking/analytics, logging, any listener that doesnt callpreventDefault().Dont use passive when:implementing custom swipe gestures, custom zoom controls, or any listener that needspreventDefault().展开说明如下✅ 应该使用 passive 的场景埋点 / 追踪tracking / analytics如记录用户触摸坐标、滚轮 delta 用于行为分析只读数据、不改写默认行为日志输出logging调试期或线上日志采集任何不需要调用preventDefault()的监听器只要回调不阻止默认行为一律应声明passive: true。❌ 不能使用 passive 的场景自定义滑动手势custom swipe gestures例如移动端「左滑删除」「滑动切换 Tab」等需要touchstart/touchmove上调用preventDefault()来抑制浏览器原生滚动此时声明 passive 会直接导致preventDefault()失效并触发浏览器控制台警告自定义缩放控件custom zoom controls通过wheel事件实现 Ctrl滚轮缩放等交互同样依赖preventDefault()任何需要preventDefault()的监听器。两条补充工程经验passive 监听器内调用preventDefault()是无效的现代浏览器会在控制台输出类似 Unable to preventDefault inside passive event listener invocation 的警告。因此若业务演进后回调需要新增阻止默认行为的能力必须同步移除passive选项手势场景可考虑 CSStouch-action替代对于「禁用某区域内原生触摸滚动、改由 JS 接管」的需求优先用touch-action: none声明区域行为再注册非 passive 监听器处理手势能显著减少对preventDefault()的依赖。六、浏览器默认行为的背景知识需要说明的是现代浏览器已经在部分场景默认启用 passive。作为背景参考——Chrome 自 56 版本起对注册在window、document和body上的touchstart、touchmove监听器默认视为 passive其他主流浏览器也相继有类似演进。但这不意味着可以省略passive: true该默认行为只覆盖特定目标节点如document级的特定事件注册在具体元素上的wheel/touch监听器行为因浏览器而异显式声明passive是跨浏览器、跨宿主环境含 React SSR 同构场景下唯一可靠的做法也让代码意图对 Agent、LLM 与后续维护者一目了然。七、在本仓库中的应用这套规则如何落地OpenMontage 作为一个开源 Agent 视频制作系统12 条生产级 pipeline、100 工具、700 Agent 技能与生产知识文件其技能体系本身就是给 AI 编码助手使用的「知识库」。vercel-react-best-practices技能包在仓库中的组织方式恰好示范了这类规则应该如何沉淀为机器可读、可执行的规范入口SKILL.md 声明技能名称、触发条件编写/审查/重构 React/Next.js 代码、65 条规则的 8 大类优先级表以及「何时应用」清单单条规则rules/client-passive-event-listeners.md 采用统一模板含 frontmatter 元信息与正反示例编译产物AGENTS.md 将全部规则编译为 3500 行的长文指南本主题对应 4.2 节「Use Passive Event Listeners for Scrolling Performance」构建流水线据 README.md维护者通过pnpm build从rules/生成 AGENTS.md用pnpm validate校验规则文件用pnpm extract-tests提取供 LLM 评测的测试用例。这种「frontmatter 元信息 正反示例 影响分级 自动编译」的结构正是为了让 Agent 在代码生成与审查阶段能够精准检索到对应规则并直接套用。本文所讲的 passive 事件监听器规则就是其中第 4 类「Client-Side Data Fetching / 客户端优化」MEDIUM-HIGH 优先级类别下的一条典型实践。八、落地清单审查 React 代码时的快速检查在 OpenMontage 的技能文件语境下无论你用它驱动 Agent 审查代码还是人工 review遇到以下代码模式请按清单核对扫描目标事件touchstart、touchmove、wheel、scroll相关的addEventListener调用检查第三个参数确认是否携带{ passive: true }或{ passive: false }的显式声明判断回调职责回调是否调用了preventDefault()不调用 → 必须补passive: true埋点、日志、只读统计调用 → 保持非 passive并确认监听器未注册在默认 passive 的 document/window 节点上造成行为不一致核对清理逻辑useEffect是否返回移除监听器的清理函数removeEventListener的 capture 标志是否与注册时一致考虑去重若同一全局事件会被多个组件实例监听参考 client-event-listeners.md 的useSWRSubscription()共享单监听器方案将 N 个监听器合并为 1 个。总结为touch与wheel事件监听器添加{ passive: true }是投入产出比极高的滚动性能优化一行参数声明换来浏览器跳过滚动阻塞检查、实现即时滚动。它的适用前提是「监听器不需要调用preventDefault()」——埋点、日志、统计类监听器应无脑启用而自定义滑动、缩放等需要抑制默认行为的交互则必须保持非 passive。在 OpenMontage 仓库的vercel-react-best-practices技能体系中这条规则以标准化的 frontmatter 正反示例结构存在可作为 Agent 自动审查与人工 code review 的通用检查依据。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMontage 前端性能优化：用 Passive 事件监听器消除滚动卡顿延迟
OpenMontage 前端性能优化用 Passive 事件监听器消除滚动卡顿延迟【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage滚动是 Web 页面最高频的交互之一而一个未声明passive的touch/wheel事件监听器就可能让整个页面的滚动产生可感知的延迟。本文基于 OpenMontage 仓库中.agents/skills/vercel-react-best-practices技能体系内的 client-passive-event-listeners.md 规则文档系统讲解被动事件监听器的原理、正确写法、适用边界并结合仓库源码结构给出可落地的代码审查清单。读完本文你将掌握如何为滚动相关监听器添加{ passive: true }、何时必须放弃 passive以及在 React 组件中如何安全地注册与清理这些监听器。一、规则背景来自 Vercel 工程团队的 React 性能规范该文档是 OpenMontage 仓库.agents/skills/vercel-react-best-practices技能包中的一条独立规则文件位于 rules/client-passive-event-listeners.md。整个技能包由 Vercel Engineering 维护、采用 MIT 协议发布目标是给 Agent 和 LLM 在「编写、审查、重构 React/Next.js 代码」时提供可自动执行的性能优化指南。规则文件通过 YAML frontmatter 声明元信息--- title: Use Passive Event Listeners for Scrolling Performance impact: MEDIUM impactDescription: eliminates scroll delay caused by event listeners tags: client, event-listeners, scrolling, performance, touch, wheel ---其中impact: MEDIUM中等优先级属于「渐进式性能提升」范畴位于技能包 8 个类别中第 4 类「Client-Side Data Fetching / 客户端侧优化」前缀client-之下impactDescription一句话概括收益——消除由事件监听器导致的滚动延迟tags便于检索的标签明确覆盖touch与wheel两类滚动来源事件。根据技能包入口 SKILL.md 的说明这套体系共包含 65 条规则、覆盖 8 个类别按优先级从 CRITICAL消除瀑布流请求、包体积优化到 LOW进阶模式排列每条规则文件都遵循 rules/_template.md 规定的「问题说明 错误示例 正确示例 适用上下文」四段式结构并可被构建脚本编译进长文版 AGENTS.md本文主题对应的完整章节位于其中 4.2 节。二、原理为什么滚动会被事件监听器拖慢浏览器处理滚动事件时存在一个关键环节滚动阻塞scroll blocking。对于touchstart、touchmove、wheel等与滚动相关的监听器浏览器在每次事件触发时都会等待监听器回调执行完毕再判断回调中是否调用了preventDefault()——因为一旦调用preventDefault()浏览器就必须取消默认的滚动行为。这条规则文档对此的描述非常精确Browsers normally wait for listeners to finish to check ifpreventDefault()is called, causing scroll delay.也就是说只要监听器没有声明passive浏览器就必须以「最坏情况」假设你会调用preventDefault()从而在每个事件帧内先跑完 JS 回调再决定是否滚动。当回调内部有日志输出、埋点上报、状态计算等耗时操作时这段等待时间就会直接叠加到滚动响应延迟上造成滚动「发沉」「跟手性差」的体验问题。passive 选项的语义向addEventListener传入{ passive: true }即向浏览器承诺「该监听器绝不会调用preventDefault()」。浏览器据此可以跳过上述等待环节在事件回调尚未执行完毕时就开始滚动渲染实现「即时滚动」。三、错误写法未声明 passive 的滚动监听器规则文档给出的错误示例在 React 组件中通过useEffect直接向document注册监听器且未传入任何选项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) } }, [])问题点在于touchstart与wheel都是滚动敏感事件未声明passive意味着每个事件都要经过「等待回调 → 检查 preventDefault」的完整流程回调只做了console.log典型埋点 / 追踪场景根本不需要preventDefault()等待纯属浪费从 React 最佳实践角度看这段代码虽然正确地做了清理return中移除监听器但仍属于「监听全局事件且不做去重」的模式——它与同目录下的姊妹规则 client-event-listeners.mdDeduplicate Global Event Listeners讨论的「N 个组件实例 N 个全局监听器」问题同源。四、正确写法为 touch 与 wheel 监听器启用 passive规则文档给出的正确示例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) } }, [])与错误写法唯一的差异就是第三个参数{ passive: true }——正是这一处修改让浏览器得以跳过滚动阻塞检查。代码审查要点可对照检查removeEventListener 必须与 addEventListener 匹配removeEventListener不需要也不应该传入passive但若你在注册时使用了capture: true移除时也必须传相同的 capture 标志否则监听器无法被正确解除会造成泄漏useEffect 清理函数不可省略在 React 中注册全局监听器务必在useEffect的返回函数中移除避免组件卸载后监听器残留空依赖数组[]的语义示例中监听器只注册一次回调通过闭包捕获即可若回调依赖了组件的 props/state则应考虑使用 ref 持有最新回调可参见技能包第 8 类 Advanced Patterns 中的advanced-event-handler-refs规则而不是简单地把依赖加进数组导致反复注册/注销。五、适用边界何时使用 passive何时必须放弃规则文档以两行明确的结论划定了边界Use passive when:tracking/analytics, logging, any listener that doesnt callpreventDefault().Dont use passive when:implementing custom swipe gestures, custom zoom controls, or any listener that needspreventDefault().展开说明如下✅ 应该使用 passive 的场景埋点 / 追踪tracking / analytics如记录用户触摸坐标、滚轮 delta 用于行为分析只读数据、不改写默认行为日志输出logging调试期或线上日志采集任何不需要调用preventDefault()的监听器只要回调不阻止默认行为一律应声明passive: true。❌ 不能使用 passive 的场景自定义滑动手势custom swipe gestures例如移动端「左滑删除」「滑动切换 Tab」等需要touchstart/touchmove上调用preventDefault()来抑制浏览器原生滚动此时声明 passive 会直接导致preventDefault()失效并触发浏览器控制台警告自定义缩放控件custom zoom controls通过wheel事件实现 Ctrl滚轮缩放等交互同样依赖preventDefault()任何需要preventDefault()的监听器。两条补充工程经验passive 监听器内调用preventDefault()是无效的现代浏览器会在控制台输出类似 Unable to preventDefault inside passive event listener invocation 的警告。因此若业务演进后回调需要新增阻止默认行为的能力必须同步移除passive选项手势场景可考虑 CSStouch-action替代对于「禁用某区域内原生触摸滚动、改由 JS 接管」的需求优先用touch-action: none声明区域行为再注册非 passive 监听器处理手势能显著减少对preventDefault()的依赖。六、浏览器默认行为的背景知识需要说明的是现代浏览器已经在部分场景默认启用 passive。作为背景参考——Chrome 自 56 版本起对注册在window、document和body上的touchstart、touchmove监听器默认视为 passive其他主流浏览器也相继有类似演进。但这不意味着可以省略passive: true该默认行为只覆盖特定目标节点如document级的特定事件注册在具体元素上的wheel/touch监听器行为因浏览器而异显式声明passive是跨浏览器、跨宿主环境含 React SSR 同构场景下唯一可靠的做法也让代码意图对 Agent、LLM 与后续维护者一目了然。七、在本仓库中的应用这套规则如何落地OpenMontage 作为一个开源 Agent 视频制作系统12 条生产级 pipeline、100 工具、700 Agent 技能与生产知识文件其技能体系本身就是给 AI 编码助手使用的「知识库」。vercel-react-best-practices技能包在仓库中的组织方式恰好示范了这类规则应该如何沉淀为机器可读、可执行的规范入口SKILL.md 声明技能名称、触发条件编写/审查/重构 React/Next.js 代码、65 条规则的 8 大类优先级表以及「何时应用」清单单条规则rules/client-passive-event-listeners.md 采用统一模板含 frontmatter 元信息与正反示例编译产物AGENTS.md 将全部规则编译为 3500 行的长文指南本主题对应 4.2 节「Use Passive Event Listeners for Scrolling Performance」构建流水线据 README.md维护者通过pnpm build从rules/生成 AGENTS.md用pnpm validate校验规则文件用pnpm extract-tests提取供 LLM 评测的测试用例。这种「frontmatter 元信息 正反示例 影响分级 自动编译」的结构正是为了让 Agent 在代码生成与审查阶段能够精准检索到对应规则并直接套用。本文所讲的 passive 事件监听器规则就是其中第 4 类「Client-Side Data Fetching / 客户端优化」MEDIUM-HIGH 优先级类别下的一条典型实践。八、落地清单审查 React 代码时的快速检查在 OpenMontage 的技能文件语境下无论你用它驱动 Agent 审查代码还是人工 review遇到以下代码模式请按清单核对扫描目标事件touchstart、touchmove、wheel、scroll相关的addEventListener调用检查第三个参数确认是否携带{ passive: true }或{ passive: false }的显式声明判断回调职责回调是否调用了preventDefault()不调用 → 必须补passive: true埋点、日志、只读统计调用 → 保持非 passive并确认监听器未注册在默认 passive 的 document/window 节点上造成行为不一致核对清理逻辑useEffect是否返回移除监听器的清理函数removeEventListener的 capture 标志是否与注册时一致考虑去重若同一全局事件会被多个组件实例监听参考 client-event-listeners.md 的useSWRSubscription()共享单监听器方案将 N 个监听器合并为 1 个。总结为touch与wheel事件监听器添加{ passive: true }是投入产出比极高的滚动性能优化一行参数声明换来浏览器跳过滚动阻塞检查、实现即时滚动。它的适用前提是「监听器不需要调用preventDefault()」——埋点、日志、统计类监听器应无脑启用而自定义滑动、缩放等需要抑制默认行为的交互则必须保持非 passive。在 OpenMontage 仓库的vercel-react-best-practices技能体系中这条规则以标准化的 frontmatter 正反示例结构存在可作为 Agent 自动审查与人工 code review 的通用检查依据。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考