企业官网建设流程全解析

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI

导读

在 ZCode（AI 编程工作台）的前端 UI 中，侧边栏、工作区面板等组件需要根据窗口尺寸、系统偏好等环境变化做出响应。如果组件直接订阅连续变化的原始数值（如窗口像素宽度），每次像素级变化都会触发 re-render，造成无谓的性能开销。本篇技术指南围绕 ZCode 仓库中 .agents/skills/react-best-practices/rules/rerender-derived-state.md 这条规则，讲解如何通过「订阅派生布尔状态（Subscribe to Derived State）」来降低 re-render 频率，并给出可直接落地 ZCode 的实践方案与源码佐证。

规则定位：重渲染优化家族中的「派生状态」一脉

ZCode 的 AI Agent 在编写、审查、重构 React 代码时，会依据一组来自 Vercel Engineering 的 React/Next.js 性能优化准则工作。这套准则共约 70 条规则、覆盖 8 大类，按影响程度分级（详见 .agents/skills/react-best-practices/SKILL.md）：

本文的主角 rerender-derived-state.md 属于第 5 类「重渲染优化」，impact 级别为 MEDIUM，核心目标是reduces re-render frequency（降低重渲染频率）。它与同目录下的 rerender-derived-state-no-effect.md（渲染期间计算派生值、避免用 effect 同步状态）、rerender-split-combined-hooks.md（拆分依赖独立的 Hook）共同构成「派生状态」优化家族。

核心思想：订阅布尔结果，而非连续数值

规则的原文主张非常精炼：

Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.

即：当组件的 UI 只关心「是否处于某个状态区间」（布尔值）时，应当直接订阅这个布尔值，而不是订阅会产生连续变化的原始数值、再在渲染过程中自行比较。

反例：每个像素都触发 re-render

function Sidebar() { const width = useWindowWidth(); // updates continuously const isMobile = width < 768; return <nav className={isMobile ? "mobile" : "desktop"} />; }

问题剖析：

• useWindowWidth()以连续数值订阅窗口宽度，每当窗口尺寸变化（哪怕 1px），都会触发一次新的 state 更新与组件 re-render；
• 拖拽缩放窗口的整个过程中，该组件会以极高的频率重复渲染；
• 对于Sidebar这种只关心「是否移动端」二值状态的组件，绝大多数渲染的isMobile值与上一次完全相同，属于浪费。

正例：仅在布尔值翻转时 re-render

function Sidebar() { const isMobile = useMediaQuery("(max-width: 767px)"); return <nav className={isMobile ? "mobile" : "desktop"} />; }

• useMediaQuery("(max-width: 767px)")底层基于 CSS Media Query，由浏览器原生计算并仅在查询结果翻转（true ↔ false）时通知组件；
• 组件只在布尔值发生变化时 re-render，窗口从 1200px 拖到 768px 过程中只经历一次状态翻转，而不是上百次像素级更新。

断点选择的细节：max-width 与 min-width 的语义

规则示例中的断点写法值得注意：反例用width < 768，正例则写成(max-width: 767px)，两者语义等价，但断点必须严格对齐，避免出现 768px 整数像素处的歧义：

• width < 768⇔(max-width: 767px)：严格小于 768 视为移动端；
• width <= 768⇔(max-width: 768px)：768 及以下视为移动端；
• width >= 768⇔(min-width: 768px)：768 及以上视为桌面端。

在实际落地时，建议把断点常量抽成统一来源（如 Tailwind 的sm/md断点），并保持useMediaQuery查询串与 CSS 样式断点完全一致，避免 JS 与 CSS 两套判断在临界像素处结果不一致。

仓库源码佐证：ZCode 中真实的布尔派生订阅实践

该规则并非纸上谈兵，ZCode 的前端源码中已有同构实践。以 packages/ui/src/ToolCallBlocks/QueuedSummaryContent.tsx 中的usePrefersReducedMotion为例（第 61-89 行）：

function usePrefersReducedMotion() { const [prefersReducedMotion, setPrefersReducedMotion] = useState(false); useEffect(() => { if (typeof window === "undefined" || typeof window.matchMedia !== "function") { return; } const query = window.matchMedia("(prefers-reduced-motion: reduce)"); const update = () => { setPrefersReducedMotion(query.matches); }; update(); if (typeof query.addEventListener === "function") { query.addEventListener("change", update); return () => { query.removeEventListener("change", update); }; } query.addListener(update); return () => { query.removeListener(update); }; }, []); return prefersReducedMotion; }

对照规则可以发现三处关键设计：

1. 只订阅布尔值：query.matches返回的是(prefers-reduced-motion: reduce)是否命中的布尔结果，而非任何连续数值；
2. 仅在变化时通知：通过query.addEventListener("change", update)订阅媒体查询结果翻转事件，状态只在翻转时更新；
3. 服务端/旧浏览器兼容：组件在window不存在或matchMedia不可用时提前返回；对新式addEventListener与旧式addListenerAPI 做了双路兼容。

随后该布尔值被用于控制排队摘要内容的动画开关（shouldAnimateQueuedSummaryContent({ enabled, disableAnimation, reducedMotion })），即：仅在prefers-reduced-motion翻转时组件才需要重新渲染来决定「是否播放动画」，这与规则「订阅派生布尔状态、降低 re-render 频率」的意图完全一致。

类似的matchMedia布尔订阅在 ZCode UI 中还有多处，例如：

• packages/ui/src/TaskListItem.tsx 第 160-161 行用window.matchMedia("(hover: none)").matches判断触屏设备；
• packages/ui/src/WorkspaceSidebarItem.tsx 第 268-269 行同样订阅(hover: none)；
• packages/ui/src/ToolCallBlocks/renderers/EditInlineDiffContent.tsx 第 25 行用window.matchMedia("(prefers-color-scheme: dark)").matches判断深色主题；
• packages/ui/src/WorkspaceGroupedTasksSection.tsx 第 460 行在交互回调中即时查询(prefers-reduced-motion: reduce)。

这些用法共同印证：在 ZCode 的 UI 代码中，「把环境状态折叠成布尔值再订阅」是贯穿一致的模式。

可复用实现：为 ZCode 编写通用 useMediaQuery

为了让该规则在 ZCode 中可被反复套用，可以将usePrefersReducedMotion的写法泛化为通用 Hook。一个可直接进入 ZCodepackages/ui/src/hooks目录的参考实现如下：

import { useEffect, useState } from "react"; export function useMediaQuery(query: string): boolean { const [matches, setMatches] = useState(() => { if (typeof window === "undefined" || typeof window.matchMedia !== "function") { return false; } return window.matchMedia(query).matches; }); useEffect(() => { if (typeof window === "undefined" || typeof window.matchMedia !== "function") { return; } const mediaQueryList = window.matchMedia(query); const update = () => { setMatches(mediaQueryList.matches); }; update(); if (typeof mediaQueryList.addEventListener === "function") { mediaQueryList.addEventListener("change", update); return () => { mediaQueryList.removeEventListener("change", update); }; } // 兼容旧版 Safari 的 addListener API mediaQueryList.addListener(update); return () => { mediaQueryList.removeListener(update); }; }, [query]); return matches; }

随后，usePrefersReducedMotion可以简化为useMediaQuery("(prefers-reduced-motion: reduce)")，本文开头的Sidebar也可以直接使用useMediaQuery("(max-width: 767px)")。实现要点：

• 用「惰性初始值」调用useState，首帧即拿到正确的布尔结果，避免初始渲染时出现「先桌面后移动」的闪烁（对应 rerender-lazy-state-init.md 的实践）；
• change事件仅在媒体查询结果翻转时触发，天然把 re-render 频率压缩到布尔翻转粒度；
• effect 依赖query字符串，可在断点变化时重建订阅。

适用边界与注意事项

1. 不要用布尔订阅替代所有尺寸逻辑：如果组件本身需要连续宽度值来做布局计算（如按比例分配空间），useMediaQuery无法替代useWindowWidth。该规则只适用于「UI 只关心区间归属」的场景。
2. 断点一致性：媒体查询断点必须与 CSS 断点（Tailwindsm/md等）对齐，并在临界像素处明确归边语义。
3. 服务端渲染兼容：useMediaQuery在 SSR 环境没有window，需像usePrefersReducedMotion一样返回安全的默认值；如果涉及水合不一致，可参考 rendering-hydration-no-flicker.md 用内联脚本先行注入初值。
4. 与派生状态家族其他规则协同：渲染期间应直接计算派生值而非塞进 effect（见 rerender-derived-state-no-effect.md）；一个 Hook 内若混有多个依赖独立的计算，应拆分为多个 Hook（见 rerender-split-combined-hooks.md）。若项目启用了 React Compiler，部分依赖追踪优化会自动完成，但仍建议保留清晰的布尔订阅写法。

小结

rerender-derived-state规则的落地要点可以概括为一句话：把连续值折叠成布尔值、让浏览器原生媒体查询替你监听翻转，组件只在布尔翻转时 re-render。ZCode 前端仓库中 QueuedSummaryContent.tsx 的usePrefersReducedMotion与多处matchMedia布尔订阅已经验证了这一模式，开发者可直接借鉴并泛化为通用的useMediaQuery，在侧边栏、面板、列表等响应式 UI 上系统性降低重渲染频率。

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI