View Transitions API 怎样在页面切换时保留共享元素

我第一次把列表页改成详情页过渡时，最容易误解的是“共享元素”并不是浏览器自动猜出来的。真正的关键是：切换前后的同一逻辑元素使用同一个、同时唯一的 view-transition-name，再由 View Transitions API 负责把旧快照和新快照接起来。SPA 用 document.startViewTransition() 包住 DOM 更新；MPA 则让同源的两份文档通过 CSS 选择加入导航过渡。

如果只是同一文档里的状态切换，先包住更新回调；如果是页面跳转，确保来源页和目标页同源，并在两边都声明 @view-transition { navigation: auto; }。共享图片或标题只保留一份对应名称，重名会让过渡失效。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using

先判断：SPA 和 MPA 不是同一套入口

View Transitions API 解决的是“旧视图如何离场、新视图如何进场”的快照协调。默认效果通常是淡入淡出；给元素命名后，浏览器会为它单独建立过渡组。这个命名只表达静态对应关系，不等于给元素永久绑定动画。

SPA：用 startViewTransition 包住状态更新

以“列表卡片进入详情卡片”为例，列表项和详情页主图都可以叫 product-image。关键是同一时刻渲染树里不能出现两个同名元素；如果列表仍保留多个同名卡片，应改成每项唯一名称，或只给当前目标项临时命名。

/* 只给正在参与过渡的逻辑元素命名 */
.product-card.is-active img,
.product-detail img {
  view-transition-name: product-image;
}

/* 共享图片使用独立的旧、新快照动画 */
::view-transition-old(product-image) {
  animation: image-out 180ms ease both;
}

::view-transition-new(product-image) {
  animation: image-in 220ms ease both;
}

@keyframes image-out {
  to { opacity: 0.35; transform: scale(0.96); }
}

@keyframes image-in {
  from { opacity: 0.35; transform: scale(1.04); }
}

function showDetail(id) {
  const update = () => {
    // 这里替换应用状态并重新渲染详情内容
    renderDetail(id);
  };

  if (!document.startViewTransition) {
    // 不支持 API 时仍然完成导航，不把动画当成业务依赖
    update();
    return;
  }

  // 把状态更新交给浏览器，得到可监听 ready/finished 的过渡对象
  const transition = document.startViewTransition(update);
  transition.finished.catch(() => {
    // 过渡被跳过时也不回滚业务状态，只记录可选的调试信息
  });
}

这里的经验是把业务更新和动画控制分开：renderDetail 只负责状态结果，过渡对象只负责动画生命周期。这样即使浏览器跳过动画，用户仍能进入详情页。

MPA：同源页面导航也能保留同一逻辑元素

多页应用不需要把导航改造成 SPA。来源文档和目标文档都加入下面的 CSS，浏览器在同源导航时才会尝试建立跨文档视图过渡：

/* 来源页和目标页都加载这段 CSS */
@view-transition {
  navigation: auto;
}

/* 两页中的同一张主图使用相同名称，名称必须各自唯一 */
.product-hero img {
  view-transition-name: product-image;
}

如果需要根据导航方向或页面身份调整效果，可以在 pageswap 和 pagereveal 中临时设置名称，然后在快照建立后清理。清理很重要：页面进入 BFCache 后，旧名称可能和返回时的新元素同时存在，造成重名。

window.addEventListener("pagereveal", async (event) => {
  // 没有活动过渡时保持普通页面显示
  if (!event.viewTransition) return;

  const hero = document.querySelector(".product-hero img");
  if (!hero) return;

  // 只在新页面快照准备阶段声明共享名称
  hero.style.viewTransitionName = "product-image";
  await event.viewTransition.ready;

  // 快照建立后撤销名称，避免返回缓存造成重复命名
  hero.style.viewTransitionName = "none";
});

最容易踩的四个边界

• 名称重叠：同一时刻两个渲染元素使用相同名称时，过渡可能被跳过。列表场景优先使用唯一 ID，或只在选中项上设置名称。
• 跨域导航：跨文档过渡当前围绕同源文档设计，跨域或重定向链不应当作共享元素一定存在。
• 无 API 降级：始终保留普通 DOM 更新或链接导航；动画是增强效果，不应该阻塞业务。
• 减少动态效果：为 prefers-reduced-motion: reduce 关闭自定义缩放和位移动画，只保留清晰的状态变化。

/* 尊重读者的系统动效偏好 */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation-duration: 1ms;
  }
}

适合谁，以及我的判断

列表—详情、图库主图、文章目录和同源多页站点都适合用共享元素降低“页面突然换掉”的感觉。它不适合拿来掩盖数据加载、跨域跳转或复杂业务状态；先把元素的身份和生命周期说清楚，再决定是否加动画，维护成本会低很多。

相关问题

为什么设置了 view-transition-name 仍然没有动画？

先看是否真的触发了 View Transition，再检查名称是否在同一快照范围内重复，以及 MPA 两份文档是否同源并都写了导航选择加入。

共享元素必须是图片吗？

不是。标题、按钮、卡片或其他可渲染元素都可以参与，重点是切换前后使用同一唯一名称，并根据内容选择合适的旧快照和新快照动画。