ZCode 前端重渲染优化：订阅派生布尔状态（Derived State）降低 re-render 频率

导读

在 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）：

优先级	类别	影响程度	前缀
1	Eliminating Waterfalls（消除瀑布流）	CRITICAL	async-
2	Bundle Size Optimization（包体积优化）	CRITICAL	bundle-
3	Server-Side Performance（服务端性能）	HIGH	server-
4	Client-Side Data Fetching（客户端数据获取）	MEDIUM-HIGH	client-
5	Re-render Optimization（重渲染优化）	MEDIUM	rerender-
6	Rendering Performance（渲染性能）	MEDIUM	rendering-
7	JavaScript Performance	LOW-MEDIUM	js-
8	Advanced Patterns（进阶模式）	LOW	advanced-

本文的主角 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 与旧式 addListener API 做了双路兼容。

随后该布尔值被用于控制排队摘要内容的动画开关（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。一个可直接进入 ZCode packages/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 断点（Tailwind sm/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 上系统性降低重渲染频率。