CSS View Transitions API 实战：告别 JS 库，用浏览器原生实现丝滑页面过渡

页面切换时的白屏闪烁是 Web 应用体验的老大难问题——开发者为此引入了 Framer Motion、GSAP、Barba.js 等一摞 JS 动画库，增加了 bundle 体积和维护成本。2026 年，CSS View Transitions API 已在 Chrome、Edge、Safari 18+、Firefox 134+ 全面落地，让浏览器原生接管页面过渡动画成为现实。根据 Chrome Platform Status 的数据，View Transitions 的使用量在过去一年增长了 340%，正在快速取代第三方动画方案。

本文不是 API 文档的翻译，而是从实际项目经验出发，手把手教你用 View Transitions 实现同文档过渡、跨文档（MPA）过渡、列表动画、与 Vue/React 框架集成，并附上与传统 JS 方案的性能对比数据。

🎬 一、View Transitions 核心原理

1.1 浏览器做了什么？

View Transitions 的核心机制是快照 + 动画。当你调用 document.startViewTransition() 时，浏览器会：

1. 捕获当前状态的快照（old state）——将当前页面渲染为一张位图
2. 执行你提供的更新回调（通常是 DOM 变更）
3. 捕获新状态的快照（new state）
4. 在两张快照之间执行过渡动画——默认是淡入淡出（crossfade）

这个过程对开发者是透明的，浏览器自动处理了图层合成、动画调度和 GPU 加速。

1.2 最小可运行示例

先看一个最简单的例子——点击按钮切换主题色，带有平滑过渡效果：

// 最小 View Transitions 示例：切换主题色
const btn = document.getElementById('theme-toggle')
btn.addEventListener('click', () => {
  if (!document.startViewTransition) {
    // 降级：不支持则直接切换
    document.documentElement.classList.toggle('dark')
    return
  }
  document.startViewTransition(() => {
    document.documentElement.classList.toggle('dark')
  })
})

/* 让主题色变化带有过渡效果 */
::view-transition-old(root) {
  animation: fade-out 0.3s ease-out;
}
::view-transition-new(root) {
  animation: fade-in 0.3s ease-in;
}
@keyframes fade-out {
  from { opacity: 1; }
  to { opacity: 0; }
}
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

💡 提示：document.startViewTransition() 返回一个 ViewTransition 对象，你可以通过它的 finished Promise 来追踪动画完成时机，或通过 skipTransition() 手动跳过。

1.3 核心 CSS 伪元素结构

View Transitions 创建的 DOM 结构如下：

::view-transition
└── ::view-transition-group(root)
    ├── ::view-transition-image-pair(root)
    │   ├── ::view-transition-old(root)    ← 旧状态快照
    │   └── ::view-transition-new(root)    ← 新状态快照

理解这个结构是自定义动画的关键——你可以针对每一层伪元素设置不同的动画效果。

🚀 二、命名元素过渡：让特定元素独立动画

2.1 view-transition-name 的魔法

默认情况下，整个页面作为一个整体做过渡。但更常见的需求是：让特定元素（如卡片、图片、标题）独立参与过渡，实现"元素从 A 位置移动到 B 位置"的视觉效果。

这通过 CSS 的 view-transition-name 属性实现：

/* 给需要独立过渡的元素命名 */
.product-card {
  view-transition-name: product-card;
}

.product-detail-image {
  view-transition-name: product-image;
}

.page-title {
  view-transition-name: page-title;
}

// SPA 路由切换时，带命名元素的过渡
function navigateToProduct(productId) {
  document.startViewTransition(async () => {
    // 更新 DOM：从列表视图切换到详情视图
    const app = document.getElementById('app')
    app.innerHTML = await renderProductDetail(productId)
  })
}

⚠️ 警告：每个 view-transition-name 在同一时刻必须是唯一的。如果你有多个同类元素（比如列表中的卡片），不能给它们都设同一个名字——否则浏览器会报错。解决方案见下文的列表动画。

2.2 自定义过渡动画

命名元素后，你可以为每个元素定制不同的过渡效果：

/* 产品卡片：从缩放+淡入 */
::view-transition-group(product-card) {
  animation-duration: 0.4s;
  animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
}

::view-transition-old(product-card) {
  animation: scale-down 0.3s ease-out forwards;
}

::view-transition-new(product-card) {
  animation: scale-up 0.3s ease-in forwards;
}

@keyframes scale-down {
  to {
    transform: scale(0.95);
    opacity: 0;
  }
}

@keyframes scale-up {
  from {
    transform: scale(1.05);
    opacity: 0;
  }
}

/* 标题：滑入效果 */
::view-transition-old(page-title) {
  animation: slide-out-left 0.3s ease-out;
}

::view-transition-new(page-title) {
  animation: slide-in-right 0.3s ease-in;
}

@keyframes slide-out-left {
  to { transform: translateX(-30px); opacity: 0; }
}

@keyframes slide-in-right {
  from { transform: translateX(30px); opacity: 0; }
}

2.3 性能对比：View Transitions vs JS 动画库

以下是实测数据（Chrome 126，M1 MacBook Air，100 个元素同时过渡）：

⚡ **关键结论：**View Transitions 在性能上与手写 CSS 动画持平，但开发体验远优于手写。它能自动处理"旧状态快照 → 新状态"的中间帧计算，这是纯 CSS transitions 做不到的。

🔗 三、跨文档过渡（MPA View Transitions）

3.1 为多页面应用添加过渡

View Transitions 最令人兴奋的特性之一是跨文档过渡——无需 SPA 框架，传统的多页面应用（MPA）也能有丝滑的页面切换效果。

只需在 CSS 中声明：

/* 在目标页面的 CSS 中启用跨文档过渡 */
@view-transition {
  navigation: auto;
}

然后在两个页面中使用相同的 view-transition-name，浏览器会自动在页面导航时执行过渡动画：

/* 列表页和详情页共用的过渡命名 */
.hero-image {
  view-transition-name: hero;
  contain: layout;
}

/* 两页共用的过渡动画定义 */
::view-transition-group(hero) {
  animation-duration: 0.5s;
  animation-timing-function: ease-in-out;
}

// 可选：通过 JS 控制跨文档过渡的条件
// 只有同源导航才启用过渡
if (window.navigation) {
  window.navigation.addEventListener('navigate', (event) => {
    if (!event.canIntercept || event.hashChange) return

    // 检查是否同源
    const dest = new URL(event.destination.url)
    if (dest.origin !== location.origin) return

    event.intercept({
      async handler() {
        const response = await fetch(dest.pathname)
        const html = await response.text()
        document.startViewTransition(() => {
          document.documentElement.innerHTML = html
        })
      }
    })
  })
}

📌 **记住：**跨文档过渡要求两个页面都在同一个源（origin）下，且目标页面必须声明 @view-transition { navigation: auto; }。目前 Safari 的支持度稍落后，需要用 <meta name="view-transition" content="same-origin"> 作为回退。

3.2 与 SPA 框架集成

在 Vue 和 React 中集成 View Transitions 非常自然：

// Vue 3 路由集成示例（router/index.ts）
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [/* ... */]
})

// 全局前置守卫中启用 View Transition
router.beforeResolve((to, from) => {
  if (from.path === to.path) return

  // 检查浏览器支持
  if (!document.startViewTransition) return

  // 阻止导航，用 View Transition 包裹
  return new Promise((resolve) => {
    const transition = document.startViewTransition(async () => {
      resolve()
      // 等待 DOM 更新完成
      await nextTick()
    })
  })
})

// React 集成示例（使用 useViewTransition hook）
import { useSyncExternalStore } from 'react'

// 轻量级 View Transition 状态管理
function useViewTransition() {
  const startTransition = (callback) => {
    if (!document.startViewTransition) {
      callback()
      return
    }
    document.startViewTransition(callback)
  }
  return { startTransition }
}

// 在路由切换组件中使用
function PageTransition({ children, routeKey }) {
  const { startTransition } = useViewTransition()

  useEffect(() => {
    startTransition(() => {
      // React 的 DOM 更新由 startTransition 自动包裹
    })
  }, [routeKey])

  return <div key={routeKey}>{children}</div>
}

📋 四、列表动画与动态命名

4.1 解决列表元素命名冲突

前文提到，view-transition-name 必须唯一。对于动态列表，需要在运行时为每个元素生成唯一名称：

// 为列表中的每个元素动态分配 view-transition-name
function updateListWithTransition(newItems) {
  document.startViewTransition(() => {
    const list = document.getElementById('product-list')

    // 先为旧元素分配基于数据 ID 的唯一名称
    list.querySelectorAll('[data-id]').forEach(el => {
      el.style.viewTransitionName = `item-${el.dataset.id}`
    })

    // 更新 DOM
    list.innerHTML = newItems.map(item => `
      <div class="product-card" data-id="${item.id}"
           style="view-transition-name: item-${item.id}">
        <img src="${item.image}" alt="${item.name}"
             style="view-transition-name: img-${item.id}">
        <h3 style="view-transition-name: title-${item.id}">${item.name}</h3>
        <p>¥${item.price}</p>
      </div>
    `).join('')
  })
}

/* 列表项的过渡动画：位移 + 缩放 */
::view-transition-group(*) {
  animation-duration: 0.4s;
  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}

/* 旧列表项淡出 */
::view-transition-old(*) {
  animation: fade-out 0.25s ease-out forwards;
}

/* 新列表项淡入 */
::view-transition-new(*) {
  animation: fade-in 0.25s ease-in forwards;
}

@keyframes fade-out {
  to { opacity: 0; scale: 0.95; }
}

@keyframes fade-in {
  from { opacity: 0; scale: 1.05; }
}

⚠️ 警告：不要在包含大量元素的列表上使用 View Transitions（超过 50 个命名元素）。浏览器需要为每个命名元素生成快照位图，元素过多会导致内存飙升和动画卡顿。对于大列表，建议只对可见区域内的元素应用过渡。

4.2 共享元素过渡：列表 → 详情的经典模式

电商 App 中最常见的动画就是「列表中的图片放大为详情页的 Hero 图」。用 View Transitions 实现：

/* 列表页：图片使用特定命名 */
.product-list .product-image {
  view-transition-name: shared-image;
  contain: layout;
}

/* 详情页：Hero 图使用相同命名 */
.product-detail .hero-image {
  view-transition-name: shared-image;
  contain: layout;
  width: 100%;
  aspect-ratio: 16/9;
  object-fit: cover;
}

/* 共享元素的过渡：同时改变位置和尺寸 */
::view-transition-group(shared-image) {
  animation-duration: 0.5s;
  animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
}

/* 整体页面的背景过渡 */
::view-transition-old(root) {
  animation: fade-out 0.3s ease-out;
}

::view-transition-new(root) {
  animation: fade-in 0.3s ease-in;
}

这种模式在没有 View Transitions 之前，需要用 FLIP 动画技术（First, Last, Invert, Play）手动计算位置差，代码量至少 50 行以上。现在只需 CSS 声明即可。

⚡ 五、生产环境注意事项

5.1 无障碍（Accessibility）支持

View Transitions 内置了对 prefers-reduced-motion 的支持：

/* 尊重用户的减少动画偏好 */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*) {
    animation-duration: 0.01ms !important;
  }
  ::view-transition-old(*) {
    animation: none !important;
  }
  ::view-transition-new(*) {
    animation: none !important;
  }
}

// JS 层面也可以跳过动画
async function navigateWithTransition(updateFn) {
  if (!document.startViewTransition) {
    await updateFn()
    return
  }

  const transition = document.startViewTransition(updateFn)

  // 如果用户偏好减少动画，立即跳过
  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
    transition.skipTransition()
  }

  await transition.finished
}

5.2 与 CSS 框架的兼容性

5.3 常见坑点与避坑指南

❌ 坑 1：view-transition-name 与 z-index 冲突 View Transitions 创建的伪元素位于最顶层（top layer），会遮盖 position: fixed 和 z-index: 9999 的元素。解决方案是在动画期间临时调整目标元素的 z-index。

❌ 坑 2：快照不包含 iframe 和 video 浏览器的快照机制不会捕获 iframe 内容和正在播放的 video，这些元素在过渡期间会显示为空白。

❌ 坑 3：SPA 中的滚动位置丢失 过渡完成后，页面滚动位置可能被重置。需要在 transition.finished 回调中手动恢复：

// 保存并恢复滚动位置
async function navigateWithScrollRestore(updateFn) {
  const scrollY = window.scrollY
  const transition = document.startViewTransition(updateFn)
  await transition.finished
  window.scrollTo(0, scrollY)
}

✅ 推荐做法：

• 用 contain: layout 限制过渡元素的布局影响范围
• 过渡动画时长控制在 200ms-500ms，过长会让用户感觉迟钝
• 对移动端使用更短的动画时长（200-300ms）
• 始终提供 prefers-reduced-motion 的降级方案

📝 总结

CSS View Transitions API 是近年来浏览器平台最有价值的新增 API 之一。它让页面过渡动画从「需要引入 30KB JS 库 + 手写 FLIP 计算」变成了「几行 CSS 声明」，开发体验和运行性能都有质的提升。

核心要点回顾：

• 🔹 同文档过渡用 document.startViewTransition() + CSS 伪元素
• 🔹 跨文档过渡用 @view-transition { navigation: auto; } 声明
• 🔹 命名元素过渡用 view-transition-name 实现共享元素动画
• 🔹 列表动画需要动态生成唯一的 view-transition-name
• 🔧 性能优于所有 JS 动画方案，因为动画在合成器线程（compositor thread）中执行
• 🔧 始终处理 prefers-reduced-motion 无障碍场景

相关工具推荐：

• 📦 View Transitions API - MDN 文档
• 📦 Astro 内置 View Transitions — 框架级别的集成参考
• 📦 Page Transition Adapters — TC39 提案跟踪
• 🧰 jsjson.com JSON 格式化工具 — 开发中处理 JSON 数据的在线工具