View Transitions 跨文档导航怎么接入：same-origin、降级方案与滚动位置恢复

做了多页架构的站点，文章列表和详情分开成两个独立 HTML 文档的场景很多，不少产品都希望点击列表标题时不要整页生硬刷新。接入跨文档版本的 View Transitions 后，页面跳转的衔接感会自然很多，不过它的生效要求比单页场景严格不少：前后两个页面必须同源，还要两端都主动开启能力，除此之外滚动位置恢复、过渡名重复、不兼容浏览器的处理都要单独考虑。

先把多页站点的边界画清楚

这里说的“跨文档”，是点击链接后由浏览器加载另一份文档，而不是在一个 SPA 里调用 document.startViewTransition() 更新 DOM。浏览器需要看到两个页面都愿意参与，且它们的 origin（协议、主机名、端口）一致。比如 https://demo.example.com/list 跳到 https://demo.example.com/detail/42 可以继续验证；跳到另一个端口，即使页面属于同一个团队，也只能按普通导航处理。

从两份 HTML 开始接入最小版本

在列表页和详情页的样式里加入同一段 CSS 配置就可以，这个配置不是 JavaScript 层面的手动开关，只要前后页面发生符合要求的同源链接导航，浏览器会自动尝试拉起过渡流程。

@view-transition {
  navigation: auto;
}

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

如果列表项的标题和详情页标题要做连续移动，再给两边对应元素一个相同的名字。例如列表卡片使用 view-transition-name: article-title-42，详情页也要使用这个值。这个名字不是 class：一份文档里同时出现两个同名元素时，匹配关系就不再明确，列表循环尤其容易踩中。

从“整页淡入”升级到稳定的元素匹配

刚上手配置的时候，建议先只给核心的标题或者封面区域设置过渡名，先把两个页面之间的快照对应逻辑跑通确认没问题，不要一开始就给全站导航栏、列表容器、头像、操作按钮全部加过渡命名。命名的元素越多，出问题的时候越难定位是资源加载、布局偏移还是快照匹配错误导致的闪烁。

/* 两个文档中都只保留一个 article-title-42 */
.article-title[data-article-id="42"] {
  view-transition-name: article-title-42;
}

::view-transition-old(article-title-42),
::view-transition-new(article-title-42) {
  animation-duration: 220ms;
  animation-timing-function: ease-out;
}

真实项目落地的时候，过渡名最好从页面绑定的业务数据里取，不要硬写在组件模板上。列表渲染阶段给每个要做过渡的元素分配唯一和实体 ID 绑定的名称，详情页对应区域用同一个实体 ID 生成的名称就行。如果遇到目标页不存在对应匹配元素的情况，直接让元素正常淡入淡出就好，强行加个空的占位元素来凑过渡效果，后续维护成本反而高很多。

滚动位置不要交给动画猜

视觉过渡完成并不等于历史记录行为正确。用户从列表第 5 屏进入详情，再按返回时，浏览器可能恢复原滚动位置；如果站点在加载时又主动执行 scrollTo(0, 0)，两者就会互相覆盖。列表页应先决定自己是否使用浏览器的历史滚动恢复，再把脚本限制在确实需要的导航场景。

if ("scrollRestoration" in history) {
  history.scrollRestoration = "auto";
}

window.addEventListener("pageshow", (event) => {
  if (event.persisted) {
    // bfcache 恢复时不要再次强制滚到顶部
    return;
  }
});

如果详情页来自站内新导航，顶部滚动可以由正常页面加载决定；如果是返回列表，先观察 pageshow、浏览器历史和 bfcache 的实际行为，再决定是否补偿。不要把“滚到顶部”绑定到每一次 DOMContentLoaded。

上线前按四个现场信号验收

1. 确认在相同协议、主机、端口的环境下，点击列表标题跳转详情，页面没有出现突兀的闪白，同时跳转后的链接仍然支持正常复制、在新标签页打开这些原生链接的常规能力。
2. 关闭本地缓存，模拟图片资源加载缓慢的弱网场景，观察过渡动画执行过程中，还没加载完成的资源会不会出现大面积布局跳动，必要的时候提前给要做过渡的元素预留好稳定的宽高尺寸。
3. 在列表里连续点击不同 ID 的内容条目，检查每个过渡名称同一时间只会对应唯一元素，从旧详情跳新详情的时候，不会把前一个页面的标题元素残留带到新内容里。
4. 在系统设置里开启减少动效选项，切换到不支持 View Transitions 的浏览器访问，确认常规导航、返回后的滚动位置、键盘焦点跳转这些基础体验都不受影响。

调试阶段不用急着把动画时长拉到几百毫秒，跨文档导航做过渡的核心是保证页面状态可信，动画本身只是减少跳转的突兀感。如果页面加载慢、跳转后焦点丢失、返回列表滚动位置错了，反而动画效果越明显，存在的体验问题会越显眼。

常见问题：跨文档 View Transitions 的几个误区

两个页面同站点但不同端口，能不能过渡？

这种情况没办法触发同源校验规则，协议、主机名、端口任意一项不一致，都会直接跨过文档过渡的生效边界，直接保留普通导航逻辑即可。

只在列表页写 @view-transition 可以吗？

不建议这么做，当前页和目标页都要明确开启过渡能力，只要缺了其中一端，浏览器就拿不到完整的跨页过渡执行契约。

为什么同一个标题会在动画中闪两次？

先查同一份文档是否出现重复的 view-transition-name，再查图片尺寸、字体回退和加载时机。命名唯一后仍有问题，再用 DevTools 的动画面板确认快照伪元素。

不支持 View Transitions 的浏览器要写另一套路由吗？

一般不需要额外写复杂的降级判断逻辑，原生的 HTML 链接本身就是最稳妥的降级方案，只要不要把核心业务逻辑绑定在过渡动画执行成功的前提下，就算浏览器不支持该特性，也不会影响页面的正常访问流程。

把过渡当成增强层，而不是导航依赖

跨文档版本 View Transitions 的基础接入成本很低，真正需要仔细处理的都是边界场景：同源关系校验、前后页面两端都开启能力、保证快照名称全局唯一、历史滚动恢复适配、动效偏好适配。先保证普通链接导航在所有环境下都能正常跑通，再先用单个实体标题元素做小范围过渡验证没问题，最后再逐步把能力扩展到封面或者其他局部内容上，排查问题的效率会高很多。