View Transition API 跨文档过渡怎么落地：同源导航、@view-transition 与降级检查

传统多页站点点击链接时，旧页面直接消失，新页面从零开始重绘，用户会明显感觉到生硬的跳转感。现在可以把 index.html 和 detail.html 这样的同源页面接入 View Transition API：两边各自加入 CSS 授权配置，浏览器负责截取新旧状态并播放过渡效果，业务 JavaScript 不用额外接管导航逻辑。真正要留意的是同源限制、唯一的 view-transition-name、首屏稳定性，以及不支持该特性的浏览器必须保留正常链接跳转行为。

跨文档过渡解决的不是路由，而是页面切换的等待链

View Transition API 不会把 MPA 硬改成 SPA，也不会替服务器渲染页面。一次跨文档过渡仍然从普通的同源链接触发：当前页面提交导航，浏览器先保存旧页面的快照，等目标页面完成关键内容解析，再把新旧两个状态交给 CSS 动画系统处理。用户看到的是连贯的过渡动画，站点本身仍保留可直接分享的URL、原生前进后退和原有服务端渲染逻辑。

先用两份同源页面完成最小接入

下面的示例假设两个页面文件都部署在同一个站点下，例如 https://demo.example.com/index.html 与 https://demo.example.com/detail.html。把这段 CSS 同时加到两份页面里，配置名必须完全一致：

@view-transition {
  navigation: auto;
}

@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*) {
    animation-duration: 1ms;
  }
}

这一步只是允许浏览器在导航时尝试触发过渡效果，它没有改动链接的默认语义，也不要求页面引入额外的前端框架。可以先单独打开两个页面，再到开发者工具里确认对应CSS规则确实加载完成；如果其中某一页漏掉了 opt-in 配置，最常见的表现就是直接回到原来的硬跳转。

用 view-transition-name 把商品缩略图接到详情页

默认过渡效果会处理整个根视图。如果首页的商品缩略图和详情页的主图需要做成像同一个对象平滑移动的效果，就给它们设置完全相同的名称，同时保证每个页面里只有一个对应元素绑定这个名称：

/* index.html 与 detail.html 都有这条规则 */
.book-cover {
  view-transition-name: book-cover;
}

/* 详情页可以单独调整共享元素的动画 */
::view-transition-group(book-cover) {
  animation-duration: 280ms;
  animation-timing-function: ease-out;
}

这个名称只是前后页的匹配键，不是数据库ID。列表页如果同时展示六本书的封面，就别给六张图片都写成 book-cover，不然会直接造成匹配冲突。实际项目里可以在服务端渲染时把书籍ID拼进样式名，同时提前过滤空值和不符合CSS标识符规范的字符。

SPA 和 MPA 的 API 入口不要混用

如果页面只是在同一个文档里替换局部列表内容，才需要显式调用 document.startViewTransition()：

function changePanel(render) {
  if (!document.startViewTransition) {
    render();
    return;
  }

  const transition = document.startViewTransition(() => render());
  transition.finished.catch(() => {
    // 动画被跳过时，DOM 更新仍然已经完成
  });
}

跨文档导航则直接用原生链接触发就行，不要给每一个 都绑定拦截器再手动模拟页面切换，这种操作很容易破坏浏览器默认的新窗口打开、键盘导航、后退操作和服务端错误页跳转逻辑。两种模式可以共存，但边界要理清楚：SPA 模式负责处理「同一文档内的DOM更新」，MPA模式负责处理「同源页面之间的导航跳转」。

支持范围与上线前检查

View Transition API 不同能力段的浏览器支持进度并不完全统一。MDN 把 Document.startViewTransition() 和相关接口列入了较新的 Baseline 通用能力集；跨文档过渡能力还受浏览器版本、同源导航规则和页面 opt-in 配置的多重影响。不要只靠自己日常用的Chrome版本就判定全量兼容，至少要在目标用户覆盖的 Chromium、Safari 和 Firefox 几个主流版本里都跑一遍测试。

这里不用急着调整动画时长参数，先在不支持过渡特性的浏览器里验证链接跳转、焦点状态、滚动位置和错误页逻辑，确认完整功能路径都正常之后，再去调整视觉细节。View Transition API 的作用是弱化切页的突兀感，不能用来给页面加载性能做背书。

常见问题：跨文档 View Transition 的边界

跨域页面能不能做跨文档过渡？

当前公开的浏览器实现要求参与导航的所有页面同源。不同协议、主机名或者端口的导航都会被判定为跨源，这类场景就按普通页面跳转做设计就好。

MPA 还需要调用 startViewTransition 吗？

基础跨文档过渡完全不需要。普通同源导航配合两页的CSS opt-in配置就可以跑通；startViewTransition() 是专门面向SPA的文档内更新场景的。

不支持 View Transition API 会白屏吗？

符合渐进增强规范的正常实现不会出现这个问题。不支持的浏览器会直接忽略新增的CSS规则，链接仍按默认逻辑导航；如果出现白屏，优先排查页面本身的加载逻辑有没有问题。

为什么 view-transition-name 写了却没有移动效果？

先检查前后两页是否同源、两边的名称是否完全一致、同页面内有没有重复命名，再确认目标元素有没有在首屏渲染阶段就被动态替换，最后再去排查动画CSS的配置。

把过渡当作增强层，而不是页面契约

适合落地的推进顺序是：先保证普通MPA导航的核心逻辑完全稳定，再给两页加上 @view-transition 配置，最后再为单个明确的共享元素添加唯一名称。每新增一个动画效果，都要在开启动画减弱偏好、禁用自定义CSS、使用旧版本浏览器的场景下再复查一遍。这样即使过渡效果被浏览器跳过，页面的URL、内容、焦点状态和返回路径都能正常工作，这种视觉体验升级才不会反过来绑架原有业务结构。