View Transitions API 怎样让多页导航保留页面连续感

View Transitions API 可以把普通的多页导航从“旧页面瞬间消失、 新页面突然出现”变成有连续感的视觉切换。多页应用（MPA）不需要先改造成单页应用：只要来源文档和目标文档都声明加入跨文档过渡，再给需要配对的元素设置相同的 view-transition-name，浏览器就能为页面切换创建过渡快照。

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

最稳妥的接入方式是先让普通链接在任何浏览器里照常工作，再用 @view-transition、view-transition-name 和过渡伪元素逐层增强；不支持时不要把导航功能绑定在动画上。

多页导航需要哪些静态关系

View Transition API 同时覆盖 SPA 的同文档状态变化和 MPA 的跨文档导航。本文只讨论 MPA：用户从来源文档点击链接，浏览器切换到目标文档，两个文档共同参与一组视图过渡规则。MDN 将 @view-transition 作为跨文档导航的加入开关，并把 pageswap、pagereveal 作为来源页和目标页的页面事件。

可以把参与边界分成三层：

• 跨文档导航边界：来源文档、目标文档和 @view-transition 决定哪些页面愿意参与过渡。
• 页面事件边界：pageswap 关注来源文档即将离开，pagereveal 关注目标文档即将显示。
• 过渡快照边界：view-transition-name 给元素提供稳定标识，让两个文档里代表同一对象的元素具备匹配关系。

先用最小 CSS 开启跨文档过渡

跨文档过渡的第一步不是写复杂动画，而是让来源页和目标页都加入同一条 CSS 规则。下面的示例假定 /articles/list.html 和 /articles/detail.html 都加载了同一份样式文件。

/* 两个参与导航的文档都要声明加入跨文档视图过渡 */
@view-transition {
  navigation: auto;
}

/* 先保留浏览器默认过渡，确认导航功能不依赖动画 */
body {
  background: #f7f8fb;
  color: #1f2937;
}

navigation: auto 表示让符合条件的导航使用视图过渡。它不是把所有链接都改成 SPA，也不会替代 HTTP 导航。浏览器不识别这条规则时，普通链接仍然可以完成页面跳转，这正是渐进增强的关键。

如果项目使用构建工具，务必保证这份 CSS 同时出现在两个文档中。只给列表页加规则，详情页没有加入，通常无法形成完整的跨文档过渡关系。

用同一个名称配对共享元素

默认过渡适合验证“页面之间已经连起来”，但真正的连续感来自共享元素。例如列表页的文章卡片封面，在详情页中对应一张主图。两边元素使用同一个 view-transition-name，浏览器就能把它们视为同一视觉对象。

    
跨文档导航的视觉连续感
  

这个名称是当前文档参与过渡的稳定标识，不是图片 URL，也不是 HTML 的全局 id。命名时要注意两个边界：

• 同一份视图中过渡名称应保持唯一，避免多个元素争抢同一快照。
• 只给确实代表同一对象的元素配对；不相关元素不要为了“看起来更炫”而复用名称。

当页面上存在多个卡片时，不要让所有封面都写成同一个固定名称。可以让服务端把文章标识编码到样式值中，并保证列表页选中的元素与详情页主图得到同一名称。

// 只为当前文章生成稳定名称，避免同一视图出现多个同名快照
function setArticleTransitionName(element, articleId) {
  if (!element || !articleId) {
    return
  }

  // 文章 ID 来自当前页面数据，不把用户输入直接拼进 CSS 名称
  const safeId = String(articleId).replace(/[^a-zA-Z0-9_-]/g, '-')
  element.style.viewTransitionName = `article-${safeId}`
}

为什么默认过渡不够，以及动画边界怎么定

默认效果可以快速验证接入，但产品界面通常需要控制旧视图淡出、新视图淡入，或者让共享封面保持更明确的连续感。View Transition API 会把过渡内容放在 ::view-transition 覆盖层中，并提供 ::view-transition-old() 与 ::view-transition-new() 访问旧、新视图快照。

/* 只调整过渡覆盖层，不直接改变页面正文的布局 */
::view-transition-old(root) {
  animation: page-out 180ms ease both;
}

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

/* 共享封面单独控制，避免页面整体动画掩盖对象连续性 */
::view-transition-group(article-cover) {
  animation-duration: 260ms;
}

@keyframes page-out {
  to { opacity: 0; }
}

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

这里的 root 是整页默认视图的名称，article-cover 对应前面设置的共享元素名称。过渡伪元素属于浏览器生成的视觉层，不应该拿来承载业务内容、焦点管理或可访问性文本。

把页面事件用于条件判断，而不是替代链接

跨文档导航还可以通过 pageswap 和 pagereveal 获取过渡对象，适合按导航方向、历史记录条目或页面状态做轻量调整。事件代码应该是可选增强：即使事件不存在，链接也要能正常工作。

// 来源文档离开前只记录可选的过渡类型，不阻断普通导航
window.addEventListener('pageswap', (event) => {
  const transition = event.viewTransition
  if (!transition) {
    return
  }

  // 只保存静态类型信息，后续 CSS 可以按类型选择过渡样式
  transition.types.add('article-navigation')
})

// 目标文档显示前读取同一过渡对象；不存在时保持页面默认渲染
window.addEventListener('pagereveal', (event) => {
  const transition = event.viewTransition
  if (!transition) {
    return
  }

  // types 只用于样式分支，不在这里替换页面内容或阻止焦点恢复
  if (transition.types.has('article-navigation')) {
    document.documentElement.dataset.transition = 'article'
  }
})

不要把事件回调写成导航的唯一入口，也不要在事件中重复请求正文。事件的职责是给已经发生的页面切换提供上下文，正文加载、链接权限和错误页仍由原有的页面流程负责。

兼容性和减少动态效果要一起处理

View Transitions API 的支持情况会随浏览器和具体能力变化，跨文档导航还涉及 CSS 规则、伪元素和页面事件几个层面。生产代码应把它当作增强能力：保留完整的普通 HTML 导航、清晰的焦点移动和可读的页面内容。

/* 用户明确减少动态效果时，保留内容层，只取消视觉动画 */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(root),
  ::view-transition-new(root),
  ::view-transition-group(article-cover) {
    animation-duration: 1ms;
    animation-iteration-count: 1;
  }
}

这段规则不是对所有设备的支持检测，而是尊重用户偏好。对于能力检测，可以在脚本中判断相关接口是否存在，但不要因为检测不到就隐藏链接或阻止页面访问：

// 能力检测只决定是否附加增强行为，默认导航仍然存在
const canUseViewTransition = 'ViewTransition' in window

if (canUseViewTransition) {
  document.documentElement.classList.add('view-transition-ready')
}

同时检查键盘焦点、屏幕阅读器阅读位置和页面标题。过渡快照可能让旧、新视觉层在很短时间内同时存在，但业务语义仍应只保留在真实 DOM 内容中。

一套适合发布前的接入清单

常见问题

View Transitions API 只能用于单页应用吗？

不是。它既支持同文档状态变化，也支持多页应用中的跨文档导航。本文使用的是后者，核心是两个文档共同声明参与过渡，并使用稳定的元素名称建立视觉匹配。

为什么设置了 view-transition-name 却没有连续动画？

先检查两个页面是否都启用了跨文档过渡，名称是否完全一致且在各自页面唯一，再检查浏览器是否支持对应的跨文档能力。即使匹配失败，也不应影响普通页面导航。

可以在 pageswap 里阻止用户离开页面吗？

不要把页面事件当作通用拦截器。离开确认、表单未保存提示和权限校验应使用各自的页面机制；pageswap 更适合读取导航上下文和调整过渡。

默认动画和自定义伪元素应该先做哪一个？

先用默认过渡确认两页接入和共享名称都成立，再只覆盖需要改变的伪元素。这样更容易区分“参与关系没有建立”和“动画样式写错”这两类问题。

多页导航的连续感并不来自一套复杂动画，而来自清晰的边界：文档决定参与，元素名称决定匹配，伪元素决定表现，普通链接和用户偏好负责兜底。按这个顺序接入，既能保留传统多页应用的可靠性，也能把 View Transitions API 的增强效果控制在可维护范围内。