ThemeTransitionToggle：把深浅模式切换设计成一次几何揭幕ThemeTransitionToggle：把深浅模式切换设计成一次几何揭幕

深浅模式切换很容易被写成一个很轻的功能：点一下按钮，改一下 html.dark，再让 CSS Variables 接管颜色。

这当然能工作，但它少了一层体验上的交接。用户看到的不是“一个新的视觉状态被打开”，而是“页面突然换色”。如果项目本身对视觉节奏、主题质感、暗色层次比较敏感，这个瞬间会显得有点粗糙。

ThemeTransitionToggle 想解决的不是“如何切换主题”这个问题，而是另一个更具体的问题：

当整个页面的视觉语义发生变化时，能不能让这次变化从用户的操作点自然展开，并且不牺牲真实 DOM、可访问性和组件复用？

最后的方案是：用浏览器 View Transition API 承接旧主题和新主题的截图层，再用 clip-path 做圆形、椭圆、五角星、菱形、六边形等几何揭幕。按钮本身仍然是一个熟悉的双状态切换控件，图标保留轻微旋转反馈；全屏主题过渡则被封装为一个可复用能力。

封装后的组件已经沉淀到 QiuYe UI：可以在 ThemeTransitionToggle 组件详情页 里查看 API、示例并直接体验切换效果。

一、设计目标：不是炫技，而是把切换变得可控

主题切换动画最怕两件事。

第一是“看起来很酷，但实现很脆”。比如手写一个全屏 overlay，把颜色盖过去，再在某个时刻切主题。这类方案很容易遇到尾帧闪烁、滚动区域露底、真实 DOM 和视觉状态不同步的问题。

第二是“组件很方便，但能力被按钮绑死”。如果主题过渡只能通过某一个按钮触发，那它就很难用在菜单项、快捷键、设置面板、命令面板等场景里。

所以这个组件从一开始就拆成了三层目标：

最终的结构大概是这样：

这个拆法有一个很重要的前提：动画不是主题系统本身。动画只是一次视觉交接；主题状态仍然要由应用自己的主题系统负责。

二、View Transition 的关键认知：你动画的不是 DOM，而是截图

View Transition API 的好处，是它能把一次 DOM 更新包进浏览器管理的过渡流程里。

简化来看，它会做三件事：

1. 记录更新前的页面截图，也就是 ::view-transition-old(root)
2. 执行你传入的 DOM 更新回调
3. 记录更新后的页面截图，也就是 ::view-transition-new(root)

然后你可以对这些伪元素做动画。

主题切换非常适合这个模型，因为主题变化往往影响整个页面：背景色、文字色、边框、阴影、代码块、卡片、图标都可能一起变化。与其试图给每个真实 DOM 元素分别加 transition，不如让浏览器捕获两个稳定画面，再对截图层做一次统一的几何揭幕。

核心代码很短：

1const transition = document.startViewTransition(() => {
2  flushSync(() => {
3    commitThemeUpdate({
4      updateTheme,
5      targetDark,
6      themeClassName,
7    });
8  });
9});
10
11await transition.ready;
12
13const clipPathAnimation = document.documentElement.animate(keyframes, {
14  duration,
15  easing,
16  fill: "both",
17  pseudoElement,
18});

这里最容易忽略的是：startViewTransition 的 callback 里一定要完成真实主题状态的提交。不要先播放动画，再找个时间点切主题。那样视觉层和真实 DOM 会错位，也很容易在动画结束时补一帧旧主题。

三、先关掉默认 crossfade，再建立自己的层级

浏览器默认的 View Transition 会带 crossfade。对普通页面跳转来说，这很合理；但对主题揭幕来说，它会和几何遮罩互相干扰。

我们想要的是非常明确的画面关系：

• 某一层在上面，被 clip-path 打开或收回
• 另一层在下面，作为稳定的目标画面
• 不要额外混合、淡入、默认动画

因此组件会在过渡期间临时注入一段样式：

1::view-transition-old(root),
2::view-transition-group(root),
3::view-transition-image-pair(root),
4::view-transition-new(root) {
5  animation: none !important;
6  mix-blend-mode: normal !important;
7  backface-visibility: hidden;
8  will-change: clip-path;
9}
10
11::view-transition-old(root) {
12  z-index: 1;
13}
14
15::view-transition-new(root) {
16  z-index: 2;
17}

实际实现里，z-index 会根据当前动画层动态调整。因为有些方向需要动 new 层，有些方向需要动 old 层。

这是一类很典型的 View Transition 实践：先把浏览器默认效果清干净，再只保留自己需要的那一个动画属性。

四、方向不是对称的：浅入深扩散，深入浅收束

深浅模式切换看起来是同一个按钮的两次状态翻转，但视觉上并不一定应该完全对称。

在这个组件里，默认策略是：

• 浅色切到深色：扩散 ::view-transition-new(root)，让深色主题从触发点向外打开
• 深色切到浅色：收束 ::view-transition-old(root)，让深色旧画面缩回触发点，露出下方浅色主题

这也是为什么 API 里有 direction：

1function getTransitionLayer(direction, isDark) {
2  if (direction === "enter") return "new";
3  if (direction === "exit") return "old";
4
5  return isDark ? "old" : "new";
6}

auto 不是为了偷懒，而是为了把最常见的主题切换语义固定下来。进入深色时，暗色像一层夜幕展开；回到浅色时，暗色退场，光从下面显出来。

如果某个产品想表达另一种关系，比如永远让新主题从按钮处扩散，也可以把 direction 显式设为 "enter"。

五、覆盖半径要算出来，不要靠感觉猜

几何揭幕最常见的问题是边角漏色。尤其是触发点不在屏幕中心时，100vw、150vmax、200vw 这种经验值都不够可靠。

圆形覆盖的正确模型很简单：从动画原点到视口四个角，取最大距离。

1function getCircleCoverRadius(x: number, y: number, extraRadius: number) {
2  const { width, height } = getViewportSize();
3
4  return (
5    Math.max(
6      Math.hypot(x, y),
7      Math.hypot(width - x, y),
8      Math.hypot(x, height - y),
9      Math.hypot(width - x, height - y),
10    ) + extraRadius
11  );
12}

这里还有一个小细节：视口尺寸不能只看 window.innerWidth。移动端地址栏、缩放、某些桌面浏览器布局场景下，documentElement.clientWidth 和 visualViewport 也可能提供有用信息。因此实现里会取一个更稳的最大值：

1function getViewportSize() {
2  const viewport = window.visualViewport;
3
4  return {
5    width: Math.max(
6      window.innerWidth,
7      document.documentElement.clientWidth,
8      viewport?.width ?? 0,
9    ),
10    height: Math.max(
11      window.innerHeight,
12      document.documentElement.clientHeight,
13      viewport?.height ?? 0,
14    ),
15  };
16}

椭圆会更容易出错。因为 ellipse(rx ry at x y) 的 rx 和 ry 不相等，如果只是把圆形半径乘一个比例，角落很容易漏掉。

这里的做法是先把 y 方向按比例折算回 x 方向，再求最大覆盖半径：

1const ELLIPSE_Y_RATIO = 0.72;
2
3function getEllipseCoverRadii(x: number, y: number, extraRadius: number) {
4  const { width, height } = getViewportSize();
5  const requiredRadiusX = Math.max(
6    Math.hypot(x, y / ELLIPSE_Y_RATIO),
7    Math.hypot(width - x, y / ELLIPSE_Y_RATIO),
8    Math.hypot(x, (height - y) / ELLIPSE_Y_RATIO),
9    Math.hypot(width - x, (height - y) / ELLIPSE_Y_RATIO),
10  );
11  const radiusX = requiredRadiusX + extraRadius / ELLIPSE_Y_RATIO;
12
13  return {
14    radiusX,
15    radiusY: radiusX * ELLIPSE_Y_RATIO,
16  };
17}

对于五角星、菱形、六边形这类 polygon() 图形，覆盖判断更复杂。它们不是各向同性的圆，尖角、凹角、旋转角度都会影响边缘覆盖。

工程上可以先采用“圆形最远角半径 + 图形修正倍率”的方式，保证可控和容易调试：

1const POLYGON_COVER_MULTIPLIERS = {
2  star: 2.6,
3  diamond: 1.5,
4  hexagon: 1.25,
5};
6
7function getPolygonCoverRadii(shape, radius) {
8  const coverRadius = radius * POLYGON_COVER_MULTIPLIERS[shape];
9
10  return {
11    radiusX: coverRadius,
12    radiusY: coverRadius,
13  };
14}

这不是最数学洁癖的写法，但它很好维护：每一种图形的视觉扩张能力不同，用具名倍率表达这件事，比把一段难读的几何推导塞进组件更适合组件库。

六、尾帧防闪：主题要同步，清理要晚一拍

这个组件最值得记录的实践，反而不是动画本身，而是防闪。

主题切换经常会接入 next-themes 或类似方案。它们可能通过 effect、storage、系统主题监听等方式在稍后的时机修正 html class。如果 View Transition 的截图已经完成，而真实 DOM 的 class 在动画尾部又被补切一次，用户就会看到一帧很刺眼的旧主题闪回。

解决思路有两步。

第一，在 View Transition 的 update 阶段同步写入 html.dark，再调用项目自己的更新函数：

1function commitThemeUpdate({
2  updateTheme,
3  targetDark,
4  themeClassName = "dark",
5}) {
6  syncDocumentThemeClass(targetDark, themeClassName);
7  updateTheme();
8}

第二，用 flushSync 确保 React 状态更新在截图捕获阶段完成：

1const transition = document.startViewTransition(() => {
2  flushSync(() => {
3    commitThemeUpdate({ updateTheme, targetDark, themeClassName });
4  });
5});

这可以把真实 DOM、React 状态、View Transition 的 new snapshot 尽量对齐到同一个阶段。

但仅仅这样还不够。动画结束后如果立刻 cancel() 动画并移除临时样式，浏览器可能还没把最后一帧稳定绘制出来。于是实现里会等两次 requestAnimationFrame 再清理：

1function waitForNextPaint() {
2  if (document.visibilityState === "hidden") {
3    return Promise.resolve();
4  }
5
6  return new Promise<void>((resolve) => {
7    window.requestAnimationFrame(() => {
8      window.requestAnimationFrame(() => resolve());
9    });
10  });
11}

最终清理流程是：

1try {
2  await transition.ready;
3  clipPathAnimation = document.documentElement.animate(keyframes, options);
4
5  await Promise.allSettled([
6    transition.finished,
7    clipPathAnimation.finished,
8  ]);
9} finally {
10  await waitForNextPaint();
11  clipPathAnimation?.cancel();
12  style.remove();
13  onFinish?.();
14}

这就是很多动画组件里容易漏掉的一拍：完成不等于已经稳定呈现。先让浏览器把完成态画出来，再移除辅助层。

七、时间曲线：全屏过渡不要盲目追求“弹”

最开始我也很自然地想把它做成更明显的 spring 手感。毕竟按钮图标旋转有弹性，主题揭幕是不是也应该弹一下？

实际体验并不好。

全屏 clip-path 和一个小图标的运动感知完全不同。小图标的轻微回弹会显得灵动；但全屏遮罩如果尾段突然慢下来，或者半径出现过强的“弹性停靠”，用户会明显感觉页面在拖沓。

最终默认值收敛成：

1const DEFAULT_TRANSITION_DURATION = 580;
2const DEFAULT_TRANSITION_EASING = "cubic-bezier(0.17,0.84,0.44,1)";

这个曲线的特点是启动足够干脆，中后段不会突然肉下来。它不像强 spring 那样有明显 overshoot，也不会像普通 ease-out 一样把尾段拉得过长。

这里有一个实践经验：全屏状态切换的动效要比微交互更克制。
按钮可以有旋转、缩放、图标切换；整页主题切换最好保持一个稳定、直接、可预期的节奏。

因此 ThemeTransitionToggle 把两类时间拆开：

这两个动画应该互相呼应，但不应该绑成同一个参数。

八、触发器：按钮是双状态控件，不是一次性播放按钮

主题按钮不是普通 action button。它表达的是一个持续状态：当前是浅色还是深色，下一次点击会去哪里。

所以 ThemeTransitionToggle 复用了组件库里的 DualStateToggle：

1<DualStateToggle
2  active={isDark}
3  activeIcon={darkIcon}
4  inactiveIcon={lightIcon}
5  activeLabel={darkLabel}
6  inactiveLabel={lightLabel}
7  shape={buttonShape}
8  effect={effect}
9  transitionDuration={transitionDuration}
10  disabled={disabled || isTransitioning}
11  aria-pressed={isDark}
12  onClick={handleClick}
13/>

这里的关键不是“用了哪个按钮组件”，而是几个交互边界：

• 图标状态由 isDark 决定，而不是动画内部自己猜
• 过渡期间按钮禁用，避免多次并发切换
• aria-pressed 表达当前状态
• aria-label 表达下一次操作
• 按钮形状 buttonShape 和揭幕形状 shape 分开配置

最后一点很重要。按钮可以是方形、圆形，也可以和 Header 里的其他 icon button 保持统一；但全屏揭幕可以是圆、椭圆、五角星。这两者属于不同层级的设计语言，不应该被一个 shape 属性混在一起。

九、API 分层：函数、Hook、组件各做一件事

为了让能力不被按钮锁死，组件暴露了三层 API。

第一层是底层函数：

1await runThemeViewTransition({
2  isDark,
3  targetDark: !isDark,
4  origin: { x: event.clientX, y: event.clientY },
5  shape: "circle",
6  duration: 580,
7  easing: "cubic-bezier(0.17,0.84,0.44,1)",
8  updateTheme: () => setTheme(isDark ? "light" : "dark"),
9});

它适合命令面板、菜单项、快捷键、自定义坐标触发等场景。

第二层是 Hook：

1const { run, isTransitioning } = useThemeTransition({
2  isDark,
3  shape: "ellipse",
4  updateTheme: () => setTheme(isDark ? "light" : "dark"),
5});
6
7return (
8  <button disabled={isTransitioning} onClick={(event) => run(event)}>
9    Toggle theme
10  </button>
11);

Hook 适合你已经有自己的按钮样式，只想接入过渡能力的场景。

第三层才是开箱即用组件：

1<ThemeTransitionToggle
2  isDark={resolvedTheme === "dark"}
3  onToggle={(nextDark) => setTheme(nextDark ? "dark" : "light")}
4  shape="star"
5/>

这个分层让组件库能力更耐用：今天它服务 Header 主题按钮，明天也可以服务设置抽屉、命令面板、作品展示页的视觉切换。

十、兼容与降级：好动画不应该成为必需品

View Transition API 仍然不是所有环境都完整支持。再加上用户可能开启 prefers-reduced-motion，所以这类全屏动画必须有降级路径。

runThemeViewTransition 的判断很直接：

1const shouldFallback =
2  !isViewTransitionSupported() ||
3  (respectReducedMotion && shouldReduceMotion());
4
5if (shouldFallback) {
6  commitThemeUpdate({ updateTheme, targetDark, themeClassName });
7  onFallback?.();
8  onFinish?.();
9  return;
10}

这里的原则是：降级时不要伪装成另一个复杂动画。直接完成真实主题切换，保持状态正确，比在不稳定环境里模拟一套半残缺效果更可靠。

动画是体验增强，不是主题功能的依赖。

十一、这次组件沉淀下来的几个实践

写完 ThemeTransitionToggle 后，我觉得这类“全局视觉状态切换”可以沉淀成一张检查表。

这些点看起来都不大，但它们决定了组件从“Demo 很好看”走向“项目里真的能用”。

结语

ThemeTransitionToggle 的核心并不是“用 View Transition API 做了一个圆形动画”。真正重要的是它把一次主题切换拆成了几个清晰的层次：

• 主题状态由应用真实提交
• 视觉交接交给浏览器截图层
• 几何形状只负责揭幕叙事
• 触发器只负责状态表达和微交互
• 降级路径保证功能不依赖动画

当这些边界清楚之后，深浅模式切换就不再只是改一个 class。它变成了一次可感知、可复用、可维护的界面场景交接。

这也是我很喜欢 View Transition API 的地方：它没有要求我们抛弃真实 DOM，也没有强迫我们把所有状态变化都动画化。它只是给了一个很好的中间层，让旧画面和新画面可以有一次体面交接。