View Transitions API 处理跨页面导航动画

做一个多页面站点时，列表页点击卡片进入详情页，最容易出现的体验是“整页突然白一下，再重新出现”。View Transitions API 可以把这次跨文档导航交给浏览器合成动画：来源页和目标页保持同源，并且两页都在 CSS 中选择加入，浏览器就能为页面状态建立过渡。

先记住一个边界：跨页面导航不是调用 document.startViewTransition()。后者适合同一文档里的 SPA DOM 更新；MPA 的跨文档过渡由链接导航触发，核心入口是 @view-transition 规则。

先区分跨文档与单文档过渡

如果点击链接后 URL 和文档一起变化，这是跨文档过渡；如果只在当前页面替换列表内容，则是同文档过渡。两者都会使用旧视图、新视图和 CSS 动画，但触发方式不同。跨文档场景不需要也不能在点击事件里强行包一层 startViewTransition，否则你只是给当前文档做了一个局部更新，不能替代下一份 HTML 的导航。

让两个同源页面共同选择加入

把下面的规则放到来源页和目标页都能加载到的 CSS 中。实际项目可以让构建产物共享这段基础样式；关键不是文件名相同，而是两份参与导航的文档都明确选择加入。

/* 两个参与导航的同源页面都要加载这条规则 */
@view-transition {
  navigation: auto;
}

/* 给真正需要跨页面连续运动的对象分配稳定名称 */
.product-card {
  view-transition-name: product-card;
}

/* 用无障碍偏好关闭动画，但不影响链接本身的导航 */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*) {
    animation-duration: 1ms;
  }
}

这里的 navigation: auto 只表示允许符合条件的同源导航产生过渡，不代表所有跳转都一定动画。跨源地址、页面没有共同选择加入、导航加载过慢，或用户设置了减少动态效果时，都应按普通页面导航理解。

为跨页面对象建立稳定的配对名称

默认过渡适合整页淡入淡出，但卡片到详情页通常希望图片或标题有连续运动感。可以让来源页的卡片和目标页的详情对象使用同一个唯一名称。名字在同一份过渡快照里不能被多个同时存在的元素重复占用，否则配对关系会变得不明确。

/* 列表页和详情页中，逻辑对应的对象使用同名标识 */
.product-card,
.product-detail {
  view-transition-name: product-card;
}

/* 默认是交叉淡化，这里把新旧图像对改成轻微上移 */
::view-transition-old(product-card) {
  animation: product-out 180ms ease both;
}

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

@keyframes product-out {
  to { opacity: 0; transform: translateY(-8px); }
}

@keyframes product-in {
  from { opacity: 0; transform: translateY(8px); }
}

这段 CSS 只描述动画层，不负责改变页面数据。旧页面对象会被捕获为旧视图，新页面对象成为新视图，浏览器再把它们组织到 View Transition 的伪元素树中。图片比例、容器尺寸和字体跳动越稳定，视觉结果越自然。

处理方向、超时与降级

列表进入详情和详情返回列表往往需要相反方向。跨文档场景可以在 pageswap 或 pagereveal 事件中读取当前导航上下文，再给过渡类型或元素命名；如果只是第一版，先使用统一的淡入淡出更稳妥，等页面结构稳定后再增加方向差异。

不要把动画当成业务成功条件。导航请求失败、目标页没有及时完成、浏览器不支持该能力时，链接仍应按照普通方式打开目标文档。对用户设置了减少动态效果的情况，可直接缩短过渡动画：

/* 兼容性和无障碍优先：动画被关闭时仍保留正常页面切换 */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: none;
  }
}

上线前的五项检查

排查时先看“是否同源”和“目标页是否也选择加入”，再看 CSS 是否真的进入两页。若基础过渡能出现而局部对象没有连续运动，通常是名称重复、元素尺寸差异过大，或目标页没有给对应对象分配同名标识。

延伸问答

跨页面导航能直接调用 document.startViewTransition 吗？

不能把它当作跨文档入口。跨文档过渡由符合条件的导航触发；startViewTransition 主要用于同文档 DOM 更新。

两页必须使用完全相同的 HTML 吗？

不需要。需要一致的是同源条件、选择加入规则，以及希望连续运动的对象能够用稳定名称表达对应关系。

为什么写了 CSS 仍然没有动画？

先检查两页是否都加载规则，再确认不是跨源跳转、地址栏打开、重新加载或浏览器兼容性限制；最后检查页面是否启用了减少动态效果。