View Transition API 在 SPA 状态切换中的降级方案

SPA 切换列表、详情或筛选条件时，View Transition API 最稳妥的接入方式是“渐进增强”：把真实的状态更新写进一个唯一回调，支持 API 时用 document.startViewTransition() 包住它，不支持时直接执行同一个回调。这样动画缺席只会影响视觉效果，不会影响内容更新、焦点恢复和错误提示。

让动画成为增强层，DOM 更新始终有基础路径

同文档视图过渡由浏览器保存旧视图、执行更新回调，再为新旧状态生成视觉过渡。它适合 SPA，但不应该成为路由或渲染的前置条件。判断标准很简单：当前浏览器没有 document.startViewTransition，或者用户明确减少动态效果，就调用普通更新函数。

function updateView(nextState) {
  // 统一状态更新入口，避免动画路径和降级路径产生两套结果。
  const updateDom = () => {
    renderPage(nextState);
    restoreFocusAfterRender();
  };

  // 尊重系统的减少动态效果偏好，动画不是功能成功的条件。
  const reduceMotion = window.matchMedia?.(
    '(prefers-reduced-motion: reduce)'
  ).matches;

  // 不支持 API 或用户关闭动态效果时，直接完成同一份 DOM 更新。
  if (reduceMotion || typeof document.startViewTransition !== 'function') {
    updateDom();
    return;
  }

  // 支持 API 时只增加视觉层，业务渲染仍由 updateDom 负责。
  const transition = document.startViewTransition(updateDom);
  transition.updateCallbackDone.catch(() => {
    // 更新失败时由应用自己的提示机制接管，不把动画当作成功标志。
    announce('视图更新失败，请重试');
  });
  return transition;
}

这里的关键不是把 if 写得多复杂，而是让两条路径接收相同的状态和相同的渲染函数。否则常见结果是：支持动画的浏览器更新了新组件，不支持的浏览器却漏掉了列表滚动位置、加载状态或错误提示。

把降级条件分成能力、偏好和更新结果

“能不能做动画”至少包含三层判断。能力检测决定 API 是否可调用；用户偏好决定即使能调用也要不要启动视觉动画；更新结果决定页面是否真的切换成功。这三件事不要混成一个布尔值。

降级并不等于“什么都不管”。如果切换后主标题变化，应将焦点放到新的标题或内容容器；如果只是异步刷新列表，则可以让原来的焦点保留，并用 aria-live 提示结果。动画层被跳过时，这些业务和可访问性行为仍然要执行。

用承诺边界处理更新完成、焦点恢复和动画 CSS

startViewTransition 返回的对象有不同阶段的承诺。更新回调成功后，updateCallbackDone 才完成；动画全部结束后才是 finished。大多数 SPA 不需要等待动画结束才能继续处理数据，因此可以把错误提示、焦点恢复和状态机推进放在 DOM 更新一侧。

async function navigate(nextState) {
  // 让路由先记录目标状态，渲染函数只负责把状态映射到 DOM。
  const transition = updateView(nextState);

  // 降级路径没有 ViewTransition 对象，不能假设一定存在 finished。
  if (!transition?.updateCallbackDone) {
    return;
  }

  try {
    // 这里只等待 DOM 更新完成，不把动画时长加入业务链路。
    await transition.updateCallbackDone;
    announce('视图已更新');
  } catch (error) {
    // 更新回调异常时保留原状态，并交给应用的错误边界处理。
    reportViewError(error);
  }
}

/* 视觉规则只描述过渡，不承担数据更新和成功判断。 */
::view-transition-old(root),
::view-transition-new(root) {
  /* 短暂淡化可以提升状态切换的连续感。 */
  animation-duration: 180ms;
}

@media (prefers-reduced-motion: reduce) {
  /* CSS 再提供一层保护，避免未来入口遗漏时出现强动画。 */
  ::view-transition-group(root) {
    animation-duration: 1ms !important;
  }
}

如果一次切换可能连续触发多次，应用还应在自己的路由层做请求取消或状态版本判断。View Transition API 只负责视图快照和过渡，不会替你解决过期请求覆盖新状态的问题。

常见问题

不支持 View Transition API 时需要安装 polyfill 吗？

通常不需要。SPA 的核心是 DOM 状态更新，直接执行更新回调就能保留功能；polyfill 若模拟快照和交互层，复杂度可能超过动画收益。

为什么减少动态效果时不只依赖 CSS？

CSS 可以压低动画时长，但 JavaScript 入口仍可能创建过渡对象、延后焦点处理或改变错误链路。入口处直接走普通更新更清晰，也更容易测试。

应该等待 finished 再跳转到下一页吗？

只有下一步确实依赖视觉动画结束时才等待 finished。普通路由和业务状态应以 DOM 更新回调的完成为准，避免把动画时长变成接口响应的一部分。