尧图网站建设 
Polar 前端实践用 useSWRSubscription 去重全局事件监听器Deduplicate Global Event Listeners【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar本文基于 Polar 仓库clients/apps/web前端工程中收录的 Vercel React Best Practices 规则集讲解其中client-event-listeners规则如何用 SWR 的useSWRSubscription()将全局事件监听器如键盘快捷键从N 个组件实例 N 个监听器收敛为N 个组件实例 1 个监听器。读完你将掌握该规则背后的性能问题、正确的改造范式、适用边界以及它在 Polar 前端代码中的真实触发场景。规则背景它来自哪里、何时触发本规则是 Polar 仓库clients/apps/web/.agents/skills/vercel-react-best-practices技能包中 64 条性能规则之一。该技能包由 Vercel 工程团队维护面向编写、审查、重构 React / Next.js 代码的 AI Agent 与 LLM按影响级别CRITICAL → LOW分为 8 大类规则文件按area-前缀分类存放在 rules/ 目录下。client-event-listeners.md属于第 4 类「Client-Side Data Fetching」MEDIUM-HIGH其 frontmatter 元数据为title: Deduplicate Global Event Listenersimpact: LOWimpactDescription: single listener for N componentstags: client, swr, event-listeners, subscription完整规则清单、类别优先级与使用说明见 SKILL.md同一主题下还有一条相邻规则 client-passive-event-listeners.md滚动/触摸监听器使用{ passive: true }两者常被一起审查。何时应用该规则编写或重构任何会向window/document注册全局监听器的自定义 Hook、在审查代码时发现多个组件各自addEventListener、以及需要保证监听器生命周期与组件卸载严格同步时。问题剖析为什么 N 个实例会注册 N 个监听器先看规则文档给出的反面教材function useKeyboardShortcut(key: string, callback: () void) { useEffect(() { const handler (e: KeyboardEvent) { if (e.metaKey e.key key) { callback() } } window.addEventListener(keydown, handler) return () window.removeEventListener(keydown, handler) }, [key, callback]) }这段代码的问题在于每次调用该 Hook 都会在useEffect中向window注册一个独立的keydown监听器。当应用里多个组件如 Profile 页同时注册metap、metak快捷键或列表页为每个条目复用该 Hook都调用useKeyboardShortcut时window上会叠加注册 N 个几乎做同样事情的回调。从实现细节看这类写法还隐藏着两个更深的缺陷依赖数组决定重绑频率useEffect依赖[key, callback]只要调用方传入的callback引用变化内联箭头函数每次渲染都是新引用监听器就会被卸载再重绑一次造成高频抖动。每个实例全量遍历判断每个监听器都会收到每一次keydown由各实例自行判断e.key是否匹配。N 个实例 N 次判断 N 个回调执行。这种模式正是 Polar 前端工程中真实存在的形态。例如 CompassPage.tsx/dashboard/[organization]/(header)/compass/CompassPage.tsx#L64-L72) 中为了响应 Escape 键返回上一页在useEffect里直接window.addEventListener(keydown, onKey)并在清理函数中移除——单一组件如此写无可厚非但若多个页面/组件都各自注册快捷键监听就会逐步累积成规则文档描述的N 实例 N 监听器问题。正确范式用 useSWRSubscription 收敛监听器规则给出的正确实现核心思想是把注册监听器这件事从组件实例的useEffect提升到 SWR 的全局订阅层让所有实例共享同一个订阅、同一个底层监听器。import useSWRSubscription from swr/subscription // Module-level Map to track callbacks per key const keyCallbacks new Mapstring, Set() void() function useKeyboardShortcut(key: string, callback: () void) { // Register this callback in the Map useEffect(() { if (!keyCallbacks.has(key)) { keyCallbacks.set(key, new Set()) } keyCallbacks.get(key)!.add(callback) return () { const set keyCallbacks.get(key) if (set) { set.delete(callback) if (set.size 0) { keyCallbacks.delete(key) } } } }, [key, callback]) useSWRSubscription(global-keydown, () { const handler (e: KeyboardEvent) { if (e.metaKey keyCallbacks.has(e.key)) { keyCallbacks.get(e.key)!.forEach((cb) cb()) } } window.addEventListener(keydown, handler) return () window.removeEventListener(keydown, handler) }) } function Profile() { // Multiple shortcuts will share the same listener useKeyboardShortcut(p, () { /* ... */ }) useKeyboardShortcut(k, () { /* ... */ }) // ... }该方案的三个关键机制SWR 按 key 去重订阅useSWRSubscription(global-keydown, ...)的第一个参数是订阅 key。SWR 的全局缓存以 key 为维度做去重——只要还有组件持有同一个 key 的订阅底层订阅函数就只执行一次最后一个组件卸载时订阅自动清理return () window.removeEventListener(...)随之执行。这正是共享全局事件监听器的根本保证与同技能包中client-swr-dedup规则用 SWR 做请求级自动去重同源。模块级 Map 承载回调注册表keyCallbacks是一个模块级module-levelMapstring, Set() void键是快捷键字符值是该键对应的回调集合。每个 Hook 实例只做两件事把自己的callback加入对应Set组件卸载时移除而不直接接触window。单一监听器集中分发唯一的window监听器只负责按e.key查表Map.get/Set.forEach把事件分发到对应回调。注册 N 个快捷键最终在window上只有一个keydown监听器Profile组件里metap与metak共享同一监听器。注意该实现同样依赖useEffect清理函数来管理keyCallbacks的增删因此对回调引用频繁变化仍较敏感在极频繁变化场景下可参考本技能包中advanced-event-handler-refs把事件处理器存入 refs与advanced-use-latest用 ref 保持最新回调两条 LOW 级进阶规则来加固。何时使用该范式快捷键系统、全局命令面板、自定义组合键如编辑器的metas保存需要在多个路由/多个组件里注册同一类全局键盘事件的场景配合 SWR 已有缓存基础设施的工程无需为去重引入额外依赖。何时不必使用事件仅与单个组件生命周期强绑定如仅在一个页面的useEffect里注册一次 Escape 处理参见 CompassPage.tsx/dashboard/[organization]/(header)/compass/CompassPage.tsx#L64-L72) 这类单实例场景直接addEventListener反而更直白使用 React 合成事件系统或第三方事件总线如mitt、EventEmitter已有统一订阅管理时需要调用preventDefault()的触摸/滚动手势场景——这类场景应参考 client-passive-event-listeners.md 的{ passive: true }约定且无法简单套用订阅去重模型。实现前提与依赖说明该方案依赖useSWRSubscription它由 SWR 以独立子路径swr/subscription导出。在 Polar 前端工程中SWR 是客户端数据获取的核心依赖技能包内client-swr-dedup、client-event-listeners两条规则都以 SWR 为底座因此引入该 API 无需新增第三方库。使用时注意确保项目安装的 SWR 版本包含useSWRSubscriptionswr/subscription子模块自 SWR 1.x 中期引入并持续演进订阅函数返回值必须是清理函数或undefined否则 SWR 会提示订阅未正确清理订阅 key 使用稳定的全局字符串如global-keydown避免不同模块各写各的 key 导致去重失效。规则在技能包中的定位该规则在vercel-react-best-practices技能包中的完整编号为4.1 Deduplicate Global Event Listeners见 AGENTS.md 第 4 章 Client-Side Data Fetching影响级别 LOWsingle listener for N components。它属于渐进式增量改进一档不解决最致命的水瀑布async-CRITICAL或包体积bundle-CRITICAL问题但当应用规模增长、全局事件监听器数量失控时能显著降低window上的监听器基数与每次事件的分发成本。将其与client-swr-dedup请求去重、client-passive-event-listeners滚动性能配合可系统性优化客户端数据获取与事件处理链路。【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Polar 前端实践：用 useSWRSubscription 去重全局事件监听器（Deduplicate Global Event Listeners）
Polar 前端实践用 useSWRSubscription 去重全局事件监听器Deduplicate Global Event Listeners【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar本文基于 Polar 仓库clients/apps/web前端工程中收录的 Vercel React Best Practices 规则集讲解其中client-event-listeners规则如何用 SWR 的useSWRSubscription()将全局事件监听器如键盘快捷键从N 个组件实例 N 个监听器收敛为N 个组件实例 1 个监听器。读完你将掌握该规则背后的性能问题、正确的改造范式、适用边界以及它在 Polar 前端代码中的真实触发场景。规则背景它来自哪里、何时触发本规则是 Polar 仓库clients/apps/web/.agents/skills/vercel-react-best-practices技能包中 64 条性能规则之一。该技能包由 Vercel 工程团队维护面向编写、审查、重构 React / Next.js 代码的 AI Agent 与 LLM按影响级别CRITICAL → LOW分为 8 大类规则文件按area-前缀分类存放在 rules/ 目录下。client-event-listeners.md属于第 4 类「Client-Side Data Fetching」MEDIUM-HIGH其 frontmatter 元数据为title: Deduplicate Global Event Listenersimpact: LOWimpactDescription: single listener for N componentstags: client, swr, event-listeners, subscription完整规则清单、类别优先级与使用说明见 SKILL.md同一主题下还有一条相邻规则 client-passive-event-listeners.md滚动/触摸监听器使用{ passive: true }两者常被一起审查。何时应用该规则编写或重构任何会向window/document注册全局监听器的自定义 Hook、在审查代码时发现多个组件各自addEventListener、以及需要保证监听器生命周期与组件卸载严格同步时。问题剖析为什么 N 个实例会注册 N 个监听器先看规则文档给出的反面教材function useKeyboardShortcut(key: string, callback: () void) { useEffect(() { const handler (e: KeyboardEvent) { if (e.metaKey e.key key) { callback() } } window.addEventListener(keydown, handler) return () window.removeEventListener(keydown, handler) }, [key, callback]) }这段代码的问题在于每次调用该 Hook 都会在useEffect中向window注册一个独立的keydown监听器。当应用里多个组件如 Profile 页同时注册metap、metak快捷键或列表页为每个条目复用该 Hook都调用useKeyboardShortcut时window上会叠加注册 N 个几乎做同样事情的回调。从实现细节看这类写法还隐藏着两个更深的缺陷依赖数组决定重绑频率useEffect依赖[key, callback]只要调用方传入的callback引用变化内联箭头函数每次渲染都是新引用监听器就会被卸载再重绑一次造成高频抖动。每个实例全量遍历判断每个监听器都会收到每一次keydown由各实例自行判断e.key是否匹配。N 个实例 N 次判断 N 个回调执行。这种模式正是 Polar 前端工程中真实存在的形态。例如 CompassPage.tsx/dashboard/[organization]/(header)/compass/CompassPage.tsx#L64-L72) 中为了响应 Escape 键返回上一页在useEffect里直接window.addEventListener(keydown, onKey)并在清理函数中移除——单一组件如此写无可厚非但若多个页面/组件都各自注册快捷键监听就会逐步累积成规则文档描述的N 实例 N 监听器问题。正确范式用 useSWRSubscription 收敛监听器规则给出的正确实现核心思想是把注册监听器这件事从组件实例的useEffect提升到 SWR 的全局订阅层让所有实例共享同一个订阅、同一个底层监听器。import useSWRSubscription from swr/subscription // Module-level Map to track callbacks per key const keyCallbacks new Mapstring, Set() void() function useKeyboardShortcut(key: string, callback: () void) { // Register this callback in the Map useEffect(() { if (!keyCallbacks.has(key)) { keyCallbacks.set(key, new Set()) } keyCallbacks.get(key)!.add(callback) return () { const set keyCallbacks.get(key) if (set) { set.delete(callback) if (set.size 0) { keyCallbacks.delete(key) } } } }, [key, callback]) useSWRSubscription(global-keydown, () { const handler (e: KeyboardEvent) { if (e.metaKey keyCallbacks.has(e.key)) { keyCallbacks.get(e.key)!.forEach((cb) cb()) } } window.addEventListener(keydown, handler) return () window.removeEventListener(keydown, handler) }) } function Profile() { // Multiple shortcuts will share the same listener useKeyboardShortcut(p, () { /* ... */ }) useKeyboardShortcut(k, () { /* ... */ }) // ... }该方案的三个关键机制SWR 按 key 去重订阅useSWRSubscription(global-keydown, ...)的第一个参数是订阅 key。SWR 的全局缓存以 key 为维度做去重——只要还有组件持有同一个 key 的订阅底层订阅函数就只执行一次最后一个组件卸载时订阅自动清理return () window.removeEventListener(...)随之执行。这正是共享全局事件监听器的根本保证与同技能包中client-swr-dedup规则用 SWR 做请求级自动去重同源。模块级 Map 承载回调注册表keyCallbacks是一个模块级module-levelMapstring, Set() void键是快捷键字符值是该键对应的回调集合。每个 Hook 实例只做两件事把自己的callback加入对应Set组件卸载时移除而不直接接触window。单一监听器集中分发唯一的window监听器只负责按e.key查表Map.get/Set.forEach把事件分发到对应回调。注册 N 个快捷键最终在window上只有一个keydown监听器Profile组件里metap与metak共享同一监听器。注意该实现同样依赖useEffect清理函数来管理keyCallbacks的增删因此对回调引用频繁变化仍较敏感在极频繁变化场景下可参考本技能包中advanced-event-handler-refs把事件处理器存入 refs与advanced-use-latest用 ref 保持最新回调两条 LOW 级进阶规则来加固。何时使用该范式快捷键系统、全局命令面板、自定义组合键如编辑器的metas保存需要在多个路由/多个组件里注册同一类全局键盘事件的场景配合 SWR 已有缓存基础设施的工程无需为去重引入额外依赖。何时不必使用事件仅与单个组件生命周期强绑定如仅在一个页面的useEffect里注册一次 Escape 处理参见 CompassPage.tsx/dashboard/[organization]/(header)/compass/CompassPage.tsx#L64-L72) 这类单实例场景直接addEventListener反而更直白使用 React 合成事件系统或第三方事件总线如mitt、EventEmitter已有统一订阅管理时需要调用preventDefault()的触摸/滚动手势场景——这类场景应参考 client-passive-event-listeners.md 的{ passive: true }约定且无法简单套用订阅去重模型。实现前提与依赖说明该方案依赖useSWRSubscription它由 SWR 以独立子路径swr/subscription导出。在 Polar 前端工程中SWR 是客户端数据获取的核心依赖技能包内client-swr-dedup、client-event-listeners两条规则都以 SWR 为底座因此引入该 API 无需新增第三方库。使用时注意确保项目安装的 SWR 版本包含useSWRSubscriptionswr/subscription子模块自 SWR 1.x 中期引入并持续演进订阅函数返回值必须是清理函数或undefined否则 SWR 会提示订阅未正确清理订阅 key 使用稳定的全局字符串如global-keydown避免不同模块各写各的 key 导致去重失效。规则在技能包中的定位该规则在vercel-react-best-practices技能包中的完整编号为4.1 Deduplicate Global Event Listeners见 AGENTS.md 第 4 章 Client-Side Data Fetching影响级别 LOWsingle listener for N components。它属于渐进式增量改进一档不解决最致命的水瀑布async-CRITICAL或包体积bundle-CRITICAL问题但当应用规模增长、全局事件监听器数量失控时能显著降低window上的监听器基数与每次事件的分发成本。将其与client-swr-dedup请求去重、client-passive-event-listeners滚动性能配合可系统性优化客户端数据获取与事件处理链路。【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考