View Transition API 怎么为同文档状态切换加动画

同一个页面里切换筛选条件、展开详情或替换列表时，DOM 往往会瞬间变成新状态。View Transition API 的做法不是替你重写渲染逻辑，而是在一次 DOM 更新前后保存视图状态，再让 CSS 动画接管两张状态快照。实际接入时，核心只有一层兼容封装：支持 API 的浏览器走过渡，不支持时仍直接更新 DOM。

先把状态更新放进过渡入口

先把“数据请求”和“状态写入”分开。数据已经准备好后，再把真正改变 DOM 的函数交给 startViewTransition；这样页面不会因为网络等待而冻结。下面的例子用筛选按钮切换卡片视图，旧浏览器直接执行同一个更新函数。

function renderCards(filter) {
  // 这里只负责把已有状态写入 DOM，不在过渡回调里发网络请求。
  cardsPanel.replaceChildren(...makeCards(filter));
}

async function applyFilter(filter) {
  // 先取数据，让用户在等待期间仍能操作页面。
  const data = await loadCards(filter);
  const update = () => renderCards(data);

  if (!document.startViewTransition) {
    // 不支持 API 时保留完整功能，只取消动画。
    update();
    return;
  }

  const transition = document.startViewTransition(update);
  transition.finished.catch((error) => {
    // 动画失败不应阻断页面状态，记录后交给统一日志系统。
    console.warn('view transition skipped', error);
  });
}

调用后，浏览器先捕获旧状态，再调用更新回调，随后捕获新状态并建立过渡树。回调可以返回 Promise，但不建议把慢网络请求塞进去；回调等待期间渲染会被抑制，适合等待很短的 DOM 收尾，而不是承担数据加载。

用 CSS 伪元素控制默认淡入淡出

不写任何 CSS 时，根视图通常表现为交叉淡化。它不是给真实 DOM 追加一个节点，而是把旧、新状态放到视图过渡伪元素树中。理解这棵树后，定制动画就不必猜选择器。

/* 只调整过渡快照的节奏，不改真实卡片布局。 */
::view-transition-old(root) {
  animation: fade-out 160ms ease both;
}

::view-transition-new(root) {
  animation: fade-in 220ms ease 40ms both;
}

@keyframes fade-out {
  to { opacity: 0; }
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(6px); }
  to { opacity: 1; transform: translateY(0); }
}

@media (prefers-reduced-motion: reduce) {
  /* 尊重系统减少动效偏好，保留状态更新但取消动画。 */
  ::view-transition-old(root),
  ::view-transition-new(root) {
    animation: none;
  }
}

根视图适合整块内容的淡入淡出；如果只想让标题或卡片保持连续，就给目标元素设置唯一名称，再针对对应的 group 写规则。动画期间不要直接对真实元素做第二次结构改动，否则快照和实际状态容易错位。

为局部元素建立稳定的对应关系

view-transition-name 是前后两个状态之间的“配对键”。例如列表中的详情卡片可以在筛选前后继续使用同一个名字，浏览器就能把它们视作同一个过渡对象。名称必须在参与捕获的同一时刻唯一；多个元素共用一个名字会导致 ready 失败。

处理异步更新与失败边界

需要观察不同阶段时，可以按 Promise 的职责分工：updateCallbackDone 关注 DOM 更新回调是否完成，ready 表示伪元素和动画即将启动，finished 表示新状态已经可见且可交互。工程上通常把请求放在过渡外，把临时 class 的清理放在 finished，并为 API 不存在、命名冲突和用户减少动效偏好保留直接更新路径。

上线前按目标浏览器矩阵确认同文档和跨文档能力，不要把“能看到淡入”当成唯一验收标准：还要检查快速连续点击、空列表、异步失败、重复名称和回退后是否仍可操作。

常见问题

为什么包住了 DOM 更新却没有动画？

先确认浏览器存在 document.startViewTransition，再检查回调是否真的改变了可见 DOM，以及是否有重复的 view-transition-name。不支持时出现直接切换属于预期降级。

网络请求应该写在过渡回调里吗？

通常不应该。先请求并准备数据，再在回调里同步写入新状态；只有很短的字体、图片或 DOM 收尾等待才适合放进回调。

如何让用户关闭动效？

用 prefers-reduced-motion: reduce 取消过渡动画，或者在应用设置中调用 skipTransition()，但两种方式都应继续完成 DOM 更新。