CSS View Transitions API 实战：页面过渡动画新范式

2. Vue Router

// router/index.js
import { createRouter, createWebHistory } from 'vue-router';

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

// ✅ 全局路由守卫中包裹 View Transition
router.beforeEach((to, from) => {
  // 检查浏览器支持
  if (!document.startViewTransition) return true;

  return new Promise((resolve) => {
    document.startViewTransition(async () => {
      resolve(true);
      await new Promise((r) => requestAnimationFrame(r));
    });
  });
});

更精细的控制——根据路由设置不同的过渡名称：

// 在组件中动态设置 view-transition-name
// ListPage.vue
<template>
  <div
    v-for="item in items"
    :key="item.id"
    :style="{ viewTransitionName: `item-${item.id}` }"
    @click="goToDetail(item.id)"
  >
    {{ item.name }}
  </div>
</template>

// DetailPage.vue
<template>
  <div :style="{ viewTransitionName: `item-${itemId}` }" class="detail-hero">
    <h1>{{ item.name }}</h1>
  </div>
</template>

3. 封装通用 Hook / Composable

// React: useViewTransition
function useViewTransition(callback) {
  return (...args) => {
    if (!document.startViewTransition) {
      callback(...args);
      return;
    }
    document.startViewTransition(() => callback(...args));
  };
}

// 使用
const handleNavigate = useViewTransition((id) => {
  flushSync(() => navigate(`/detail/${id}`));
});

// Vue: useViewTransition composable
import { nextTick } from 'vue';

export function useViewTransition() {
  const startTransition = async (callback) => {
    if (!document.startViewTransition) {
      await callback();
      return;
    }

    document.startViewTransition(async () => {
      await callback();
      await nextTick();
    });
  };

  return { startTransition };
}

七、列表动画

1. 列表重排过渡

经典的 FLIP 动画问题——列表排序时元素位置变化，需要平滑过渡。View Transitions API 让这一切变得极其简单：

function sortList(sortFn) {
  document.startViewTransition(() => {
    // 给每个列表项设置唯一的 view-transition-name
    document.querySelectorAll('.list-item').forEach((item) => {
      item.style.viewTransitionName = `item-${item.dataset.id}`;
    });

    // 执行排序，更新 DOM
    sortFn();
  });
}

/* 列表项重排时自动做位移动画 */
::view-transition-group(item-*) {
  animation-duration: 0.3s;
  animation-timing-function: ease-in-out;
}

/* 禁用默认的淡入淡出，只保留位移 */
::view-transition-old(item-*) {
  animation: none;
}
::view-transition-new(item-*) {
  animation: none;
}

2. 动态网格过渡

function rearrangeGrid(newLayout) {
  document.startViewTransition(() => {
    // 每个网格项设置唯一 name
    document.querySelectorAll('.grid-item').forEach((item) => {
      item.style.viewTransitionName = `grid-${item.dataset.id}`;
    });

    // 应用新布局
    applyLayout(newLayout);
  });
}

/* 网格项过渡：位移 + 尺寸变化 */
::view-transition-group(grid-*) {
  animation-duration: 0.4s;
  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}

/* 淡入淡出也保留，增加层次感 */
::view-transition-old(grid-*) {
  animation: 0.2s ease fade-out;
}
::view-transition-new(grid-*) {
  animation: 0.2s ease 0.2s fade-in;  /* 延迟淡入，错开节奏 */
}

3. 列表项添加/删除

function addItem(newItem) {
  document.startViewTransition(() => {
    // 现有项设置 name（保持位置过渡）
    document.querySelectorAll('.list-item').forEach((item) => {
      item.style.viewTransitionName = `item-${item.dataset.id}`;
    });

    // 新项不设 name（走 root 的淡入）
    addItemToDOM(newItem);
  });
}

function removeItem(id) {
  document.startViewTransition(() => {
    // 所有项都设 name
    document.querySelectorAll('.list-item').forEach((item) => {
      item.style.viewTransitionName = `item-${item.dataset.id}`;
    });

    // 删除目标项
    document.querySelector(`[data-id="${id}"]`)?.remove();
  });
}

八、性能考量与渐进增强

1. 性能原理

View Transitions 的性能关键在于：截图和动画。

• 截图：浏览器将旧/新状态光栅化为位图，这个操作在合成线程执行，不阻塞主线程。
• 动画：伪元素层的动画在 GPU 合成，和 CSS transform/opacity 动画一样高效。
• DOM 更新：updateCallback 中的 DOM 操作在主线程，这是唯一可能卡顿的环节。

2. 性能优化建议

/* ❌ 避免对大区域做复杂动画 */
::view-transition-group(root) {
  animation: 1s complex-animation;  /* 整个页面都在动画，GPU 压力大 */
}

/* ✅ 只对需要的元素做过渡 */
.special-element {
  view-transition-name: special;  /* 只这一个元素动画 */
}

::view-transition-group(root) {
  animation: none;  /* root 不做动画 */
}

3. 渐进增强

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

/* JS 中的渐进增强 */
function updateWithTransition(updateFn) {
  if (!document.startViewTransition) {
    // 不支持时直接更新，无动画
    updateFn();
    return;
  }

  document.startViewTransition(updateFn);
}

九、常见陷阱与兼容性

陷阱 1：view-transition-name 不唯一

/* ❌ 两个可见元素同名的后果：过渡被跳过 */
.card:first-child { view-transition-name: card; }
.card:last-child  { view-transition-name: card; }

/* ✅ 每个元素唯一 name */
.card { view-transition-name: var(--vt-name); }
// JS: card.style.setProperty('--vt-name', `card-${id}`);

陷阱 2：过渡期间 DOM 不可交互

过渡期间，伪元素层覆盖在真实 DOM 之上。用户点击按钮可能没反应。解决方案：

/* 短过渡通常无影响。如果确实需要交互： */
::view-transition-old(root),
::view-transition-new(root) {
  pointer-events: auto;  /* 允许点击穿透 */
}

/* 或者干脆缩短过渡时间 */
::view-transition-group(root) {
  animation-duration: 150ms;
}

陷阱 3：React 中 startViewTransition 回调不生效

// ❌ React 18 自动批处理，DOM 可能不会立即更新
document.startViewTransition(() => {
  setState(newValue);  // 不会立即渲染
});

// ✅ 用 flushSync 强制同步渲染
import { flushSync } from 'react-dom';
document.startViewTransition(() => {
  flushSync(() => {
    setState(newValue);  // 立即渲染，浏览器能截取新快照
  });
});

陷阱 4：跨页面过渡时 name 未提前设置

// ❌ 页面加载后才设置 name，浏览器已经截取了快照
window.addEventListener('load', () => {
  // 太晚了！
  document.querySelector('.hero').style.viewTransitionName = 'hero';
});

// ✅ 在 CSS 中静态设置，或在 pagereveal 事件中动态设置
// CSS 方式：
.hero { view-transition-name: hero; }

// JS 方式：
document.addEventListener('pagereveal', (e) => {
  if (e.viewTransition) {
    document.querySelector('.hero').style.viewTransitionName = 'hero';
  }
});

陷阱 5：忘记清理动态设置的 name

// ❌ 列表项切换后 name 残留
function showPage(page) {
  // 旧页面的 name 还在，可能和新页面冲突
  document.startViewTransition(() => {
    renderNewPage(page);
  });
}

// ✅ 过渡前清理旧 name，设置新 name
function showPage(page) {
  // 先清理
  document.querySelectorAll('[style*="view-transition-name"]')
    .forEach(el => el.style.viewTransitionName = 'none');

  document.startViewTransition(() => {
    renderNewPage(page);
    // 为新页面元素设置 name
    document.querySelectorAll('.card').forEach(card => {
      card.style.viewTransitionName = `card-${card.dataset.id}`;
    });
  });
}

兼容性速查（2026 年 6 月）

十、速查表