Vercel React View Transitions 实用指南

使用浏览器原生的 document.startViewTransition 在 UI 状态之间进行动画。用 声明什么要过渡，用 startTransition / useDeferredValue / Suspense 触发何时过渡，用 CSS 类控制如何过渡。不支持的浏览器会优雅地跳过动画。

每个 都应该传达一种空间关系或连续性。如果你说不出它传达了什么意思，就不要添加它。

按顺序实现此列表中所有适用的模式：

1 共享元素（name） "同一个东西——进入更深的层级"

3 列表身份（逐项 key） "相同的项，新的排列"

4 状态变化（enter/exit） "有东西出现/消失"

5 路由变化（布局级） "前往一个新地方"

这是一个实现顺序，而不是"选一个"的列表。实现所有适合应用的模式。只有当应用没有某个模式的用例时才跳过它。

层级导航（列表 → 详情） 类型键控的 nav-forward / nav-back 传达空间深度

横向导航（标签页间切换） 裸 （淡入淡出）或 default="none" 没有深度可传达

Suspense 揭示 enter/exit 字符串属性 内容到达

重新验证 / 后台刷新 default="none" 静默——不需要动画

将方向性滑动保留给层级导航（列表 → 详情）和有序序列（上一张/下一张照片、轮播、分页结果）。对于有序序列，方向传达位置："下一项"从右侧滑入，"上一项"从左侧滑入。横向/无序导航（标签页间切换）不应使用方向性滑动——它会错误地暗示空间深度。

在向现有应用添加视图过渡时，逐步遵循 references/implementation.md。 从审计开始——不要跳过它。将 references/css-recipes.md 中的 CSS 配方复制到全局样式表中——不要自己编写动画 CSS。

import { ViewTransition } from 'react';

<ViewTransition>
  <Component />
</ViewTransition>

React 会自动分配一个唯一的 view-transition-name 并在幕后调用 document.startViewTransition。永远不要自己调用 startViewTransition。

enter 在一次过渡期间首次被插入

exit 在一次过渡期间首次被移除

update 内部的 DOM 变更。有嵌套 VT 时，变更应用于最内层

share 命名的 VT 卸载，另一个具有相同 name 的 VT 在同一次过渡中挂载

只有 startTransition、useDeferredValue 或 Suspense 会激活 VT。普通的 setState 不会做动画。

只有出现在任何 DOM 节点之前时才会激活 enter/exit：

// 有效
<ViewTransition enter="auto" exit="auto">
  <div>Content</div>
</ViewTransition>

// 无效——div 包裹了 VT，抑制了 enter/exit
<div>
  <ViewTransition enter="auto" exit="auto">
    <div>Content</div>
  </ViewTransition>
</div>

值："auto"（浏览器交叉淡化）、"none"（禁用）、"class-name"（自定义 CSS），或 { [type]: value } 用于按类型区分的动画。

如果 default 是 "none"，则所有触发器都被关闭，除非被显式列出。

有关现成的动画配方，请参阅 references/css-recipes.md。

用 addTransitionType 标记过渡，这样 VT 可以根据上下文选择不同的动画。多次调用它可以堆叠类型——树中不同的 VT 会对不同的类型做出反应：

startTransition(() => {
  addTransitionType('nav-forward');
  addTransitionType('select-item');
  router.push('/detail/1');
});

传入一个对象将类型映射到 CSS 类。可用于 enter、exit 和 share：

enter 和 exit 不必对称。例如，淡入但方向性滑出：

TypeScript： ViewTransitionClassPerType 要求对象中有 default 键。

对于有多个页面的应用，将类型键控的 VT 提取为可复用的包装组件：

export function DirectionalTransition({ children }: { children: React.ReactNode }) {
  return (
    <ViewTransition
      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
      default="none"
    >
      {children}
    </ViewTransition>
  );
}

router.back() 以及浏览器的后退/前进按钮不会触发视图过渡（popstate 是同步的，与 startViewTransition 不兼容）。改用带有显式 URL 的 router.push()。

类型在导航期间可用，但在随后的 Suspense 揭示期间不可用（那是单独的过渡，没有类型）。页面级 enter/exit 使用类型映射；Suspense 揭示使用简单的字符串属性。

两个 VT 上使用相同的 name——一个卸载、一个挂载——会创建共享元素的变形（morph）：

<ViewTransition name="hero-image">
  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>

// 在另一个视图中——相同的 name
<ViewTransition name="hero-image">
  <img src="/full.jpg" />
</ViewTransition>

{show && (
  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}

{items.map(item => (
  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}

在 startTransition 内部触发。避免在列表和 VT 之间放置包装 。

共享元素和列表身份是相互独立的问题——不要把两者混淆。当列表项包含一个共享元素（例如一张变形为详情视图的图片）时，使用两个嵌套的 边界：

{items.map(item => (
  <ViewTransition key={item.id}>                                      {/* 列表身份 */}
    <Link href={`/items/${item.id}`}>
      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* 共享元素 */}
        <Image src={item.image} />
      </ViewTransition>
      <p>{item.name}</p>
    </Link>
  </ViewTransition>
))}

外层 VT 处理列表重排/进入动画。内层 VT 处理跨路由的共享元素变形。缺少任何一层都意味着该动画静默地不发生。

注意： 如果包装了 ，更改 key 会重新挂载边界并重新获取数据。

更多模式请参阅 references/patterns.md。

每个匹配触发器的 VT 都会在单次 document.startViewTransition 中同时触发。处于不同过渡（导航 vs 之后的 Suspense 解析）中的 VT 不会相互竞争。

没有它，每个 VT 都会在每次过渡时触发浏览器交叉淡化——Suspense 解析、useDeferredValue 更新、后台重新验证都会。始终使用 default="none"，并且只显式启用想要的触发器。

Guide React and Next.js view transitions, shared element animations, route transitions, transition types, and reduced-motion-safe UI state animation.

前端

开发工具

客户端

本文全面解析React与Next.js视图过渡（View Transitions）的实现方法，涵盖组件使用、动画触发器、共享元素变形、Suspense揭示、列表身份及路由过渡等核心模式。提供按优先级排序的实现清单、类型键控动画风格选择、CSS配方及可访问性支持，帮助开发者构建流畅且减少动效安全的UI状态动画。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

Vercel React View Transitions 实用指南

Vercel React View Transitions 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐