View Transition API 怎么给跨文档导航添加过渡

我第一次给多页站点做页面切换时，直觉是拦截链接、自己控制离场动画，再等动画结束后修改地址。这个方案能跑，但历史记录、刷新、异常中断都要额外处理。后来换成 View Transition API 的跨文档模式，基础过渡实际上只需要让当前页和目标页同时选择加入，普通链接仍然保持普通链接。

直接结论：如果两个页面同源，并且两个文档都包含 @view-transition { navigation: auto; }，浏览器就可以在普通导航时捕获旧页面快照并过渡到新页面。基础用法不需要 JavaScript。

官方文档：https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API

先用最小代码跑通跨文档过渡

我会先把下面的规则放进列表页与详情页共同加载的样式表。这里最容易忽略的不是语法，而是“两个文档都要有”：只有出发页声明，或者只有到达页声明，都不是完整的跨文档选择加入。

/* 当前文档与目标文档都要加载这条规则 */
@view-transition {
  navigation: auto;
}

链接本身不需要特殊属性，也不用在点击事件里调用阻止默认行为：

查看文章详情

第一次验证时，我建议不要急着做共享元素，先观察整页是否出现默认淡入淡出。默认效果来自根元素的旧、新快照；这一步能成立，说明导航类型、同源边界和双端声明已经通过。

过渡状态如何从旧文档流向新文档

把过程理解成一条状态生命周期，比背 API 更容易排错。导航发生后，浏览器先判断这是不是允许参与的同源导航，再检查当前文档与目标文档是否都选择加入。条件满足后，旧文档被捕获为静态快照，新文档则完成加载并提供新视图，二者进入临时的过渡伪元素树。动画结束，这批过渡快照就被清理，页面回到正常渲染状态。

图1：跨文档过渡先经过同源与双端选择加入检查，再把旧文档快照和新文档视图放入过渡树。

这也解释了一个常见误会：跨文档模式不是让旧页面继续保持可交互，再把新页面盖上去。旧侧参与动画的是捕获后的图像；新侧对应的是新文档的视图。把它看成“旧静态快照 → 临时过渡树 → 新文档”更准确。

我会把第一版时长控制在 200～400 毫秒，先只调根快照组：

/* root 表示默认的整页快照组 */
::view-transition-group(root) {
  animation-duration: 320ms;
  animation-timing-function: ease-out;
}

这里的 320 毫秒是我的体验选择，不是规范要求。内容型站点过长会让每次点链接都像在等开场动画；过短又看不出空间连续性。

默认 root 过渡与命名元素有什么区别

默认情况下，浏览器会为根视图创建过渡，视觉上接近整页交叉淡化。如果我希望列表页的文章封面“移动”到详情页主图位置，就给两边对应元素相同的 view-transition-name。

/* 列表页：本次导航中只能有一个可见元素使用这个名字 */
.article-card__cover {
  view-transition-name: article-hero;
}

/* 详情页：用相同名称接住旧页面的对应元素 */
.article-detail__hero {
  view-transition-name: article-hero;
}

相同名称会让这两个元素进入独立的命名快照组。浏览器生成的结构可以概括为 ::view-transition-group(article-hero)，其中包含 image-pair，再向下分成 old 与 new。我们真正定制离场和入场效果时，通常就是针对这两个分支。

图2：同名元素被分配到独立快照组，旧卡片和新主图分别进入 old 与 new 伪元素。

这里有一条硬边界：同一时刻参与渲染的元素中，view-transition-name 必须唯一。列表里十张卡片都写死为 article-hero，不是“浏览器会自动挑我点击的那张”，而是很可能因为名称重复直接跳过过渡。我的做法是只在即将导航的卡片上赋名，或者为可见项生成唯一名字。

给共享元素定制离场与入场动画

基础共享过渡稳定后，再定制 old 和 new。下面的动画刻意保持克制：旧封面稍微缩小并淡出，新主图从轻微放大回到正常尺寸。

/* 旧封面使用离场动画 */
::view-transition-old(article-hero) {
  animation: hero-out 260ms ease-in both;
}

/* 新主图使用入场动画 */
::view-transition-new(article-hero) {
  animation: hero-in 340ms ease-out both;
}

/* 旧视图淡出并轻微缩小 */
@keyframes hero-out {
  to {
    opacity: 0;
    transform: scale(0.96);
  }
}

/* 新视图从轻微放大状态回落 */
@keyframes hero-in {
  from {
    opacity: 0;
    transform: scale(1.04);
  }
}

跨文档过渡有一个实践细节：伪元素的样式要由目标文档提供。如果列表到详情和详情返回列表都要有一致体验，我会把这些规则放进两个页面共享的 CSS，而不是只写在出发页。

减少动态效果与不支持浏览器的降级

@view-transition 目前仍不是所有常用浏览器都完整支持的能力，因此应该把它当作渐进增强。它的好处是：不支持时链接依旧按原方式导航，核心功能不会消失。不要为了“统一动画”再加一套阻断式跳转逻辑，反而会破坏这个天然降级路径。

/* 用户偏好减少动态效果时，将过渡压缩为近乎即时 */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*) {
    animation-duration: 0.01ms;
  }
}

如果页面包含视频、复杂滤镜或大量命名元素，我也会先保留 root 过渡，只为一个真正有导航语义的主视觉命名。命名越多，视觉竞争和维护成本越高，并不一定更高级。

过渡没出现时按这四类问题排查

1. 不是同源导航：协议、主机或端口不同，或者中途发生跨源重定向，都不能按同源跨文档过渡处理。
2. 只有一端声明：确认当前文档与目标文档最终加载的 CSS 都包含 @view-transition { navigation: auto; }。
3. 命名元素重复：检查当前渲染树中是否有多个可见元素使用相同 view-transition-name；重复名称可能让过渡被跳过。
4. 运行环境尚未支持：先确认浏览器对跨文档 View Transition 与 @view-transition 的支持情况。降级成普通导航是预期行为，不应被当成业务故障。

我的调试顺序始终是“只开 root → 确认双端与同源 → 增加一个命名元素 → 最后写自定义动画”。这样每一步只引入一个变量，定位问题会比一次性复制完整特效快得多。

最后把边界记成一句话

跨文档 View Transition 的核心不是用 CSS 模拟页面切换，而是让两个同源文档共同授权浏览器管理一次旧快照到新视图的生命周期。先用双端 navigation: auto 跑通默认 root 过渡，再用唯一的 view-transition-name 拆出关键元素，最后才定制 old/new 动画，这条路线最稳。

参考资料：

• https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API
• https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using
• https://developer.mozilla.org/en-US/docs/Web/CSS/@view-transition
• https://developer.mozilla.org/en-US/docs/Web/CSS/view-transition-name
• https://developer.chrome.com/docs/web-platform/view-transitions/cross-document