React 视图过渡
使用浏览器原生 document.startViewTransition 在不同 UI 状态之间制作动画。用 <ViewTransition> 声明什么,用 startTransition / useDeferredValue / Suspense 触发何时,用 CSS 类控制如何。不支持的浏览器会优雅地跳过动画。
何时添加动画
每个 <ViewTransition> 都应传达空间关系或连续性。如果你无法说明它传达了什么,就不要添加它。
按此顺序实现列表中所有适用的模式:
| 优先级 | 模式 | 传达的信息 |
|---|---|---|
| 1 | 共享元素 (name) | “同一个东西,更深入了” |
| 2 | Suspense 揭示 | “数据已加载” |
| 3 | 列表标识 (每个项目 key) | “相同项目,新排列” |
| 4 | 状态变化 (enter/exit) | “某物出现/消失了” |
| 5 | 路由变化 (布局级别) | “前往新地方” |
这是实现顺序,不是“挑选一个”的列表。实现适合应用的所有模式。只有当应用没有使用场景时才跳过某个模式。
选择动画风格
| 上下文 | 动画 | 原因 |
|---|---|---|
| 层级导航(列表 → 详情) | 类型键控的 nav-forward / nav-back | 传达空间深度 |
| 横向导航(标签页到标签页) | 裸 <ViewTransition>(淡入淡出)或 default="none" | 没有深度需要传达 |
| Suspense 揭示 | enter/exit 字符串属性 | 内容到达 |
| 重新验证 / 后台刷新 | default="none" | 静默,不需要动画 |
将方向性滑动保留给层级导航(列表 → 详情)和有序序列(上一张/下一张照片、轮播、分页结果)。对于有序序列,方向传达位置:“下一张”从右侧滑入,“上一张”从左侧滑入。横向/无序导航(标签页到标签页)不应使用方向性滑动。这会错误地暗示空间深度。
可用性
- Next.js: 不要安装
react@canary:App Router 已在内部捆绑了 React canary。ViewTransition开箱即用。npm ls react可能显示一个看起来稳定的版本;这是预期的。 - 没有 Next.js: 安装
react@canary react-dom@canary(ViewTransition不在稳定的 React 中)。 - 浏览器支持:Chromium 111+, Firefox 144+, Safari 18.2+。在不支持的浏览器上优雅降级。
实现工作流程
在为现有应用添加视图过渡时,逐步遵循 references/implementation.md。 从审计开始,不要跳过。将 references/css-recipes.md 中的 CSS 配方复制到全局样式表中,不要编写自己的动画 CSS。
核心概念
<ViewTransition> 组件
import { ViewTransition } from 'react';
<ViewTransition>
<Component />
</ViewTransition>
React 自动分配一个唯一的 view-transition-name 并在后台调用 document.startViewTransition。永远不要自己调用 startViewTransition。
动画触发器
| 触发器 | 触发时机 |
|---|---|
| enter | <ViewTransition> 在过渡期间首次插入 |
| exit | <ViewTransition> 在过渡期间首次移除 |
| update | <ViewTransition> 内部的 DOM 突变。对于嵌套的 VT,突变应用于最内层的那个 |
| share | 命名 VT 卸载而另一个同名 name 在同一个过渡中挂载时 |
只有 startTransition、useDeferredValue 或 Suspense 能激活 VT。常规 setState 不会产生动画。
关键放置规则
<ViewTransition> 只有在它出现在任何 DOM 节点之前时才会激活 enter/exit:
// 有效
<ViewTransition enter="auto" exit="auto">
<div>内容</div>
</ViewTransition>
// 无效,div 包裹了 VT,抑制了 enter/exit
<div>
<ViewTransition enter="auto" exit="auto">
<div>内容</div>
</ViewTransition>
</div>
使用视图过渡类定义样式
属性
值:"auto"(浏览器交叉淡入淡出)、"none"(禁用)、"class-name"(自定义 CSS)或 { [type]: value } 用于类型特定的动画。
<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
如果 default 是 "none",所有触发器都关闭,除非明确列出。
CSS 伪元素
::view-transition-old(.class):即将离开的快照::view-transition-new(.class):即将进入的快照::view-transition-group(.class):容器::view-transition-image-pair(.class):旧 + 新配对
参见 references/css-recipes.md 获取现成的动画配方。
过渡类型
用 addTransitionType 标记过渡,以便 VT 可以根据上下文选择不同的动画。多次调用以堆叠类型,树中不同的 VT 对不同的类型做出反应:
startTransition(() => {
addTransitionType('nav-forward');
addTransitionType('select-item');
router.push('/detail/1');
});
传递一个对象将类型映射到 CSS 类。适用于 enter、exit和 share:
<ViewTransition
enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
default="none"
>
<Page />
</ViewTransition>
enter 和 exit 不必对称。例如,淡入但方向性滑出:
<ViewTransition
enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
default="none"
>
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() 和浏览器返回按钮
router.back() 和浏览器的后退/前进按钮不会触发视图过渡(popstate 是同步的,与 startViewTransition 不兼容)。请改用带有显式 URL 的 router.push()。
类型和 Suspense
类型在导航期间可用,但在随后的 Suspense 揭示期间不可用(单独的过渡,没有类型)。对页面级别的 enter/exit 使用类型映射;对 Suspense 揭示使用简单的字符串属性。
共享元素过渡
两个 VT 具有相同的 name,一个卸载,一个挂载,会创建一个共享元素变形:
<ViewTransition name="hero-image">
<img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>
// 在另一个视图中,同名
<ViewTransition name="hero-image">
<img src="/full.jpg" />
</ViewTransition>
- 一次只能挂载一个具有给定
name的 VT。使用唯一的名称(photo-${id})。注意可重用组件:如果一个带有命名 VT 的组件同时在模态框/弹出框和页面中渲染,两者同时挂载会破坏变形。要么使名称有条件(通过属性),要么将命名 VT 移出共享组件到特定的消费者中。 share优先于enter/exit。仔细考虑每个导航路径:当没有形成匹配的对时(例如,目标页面没有相同的name),enter/exit会触发。考虑这些路径上元素是否需要回退动画。- 永远不要在带有共享变形的页面上使用淡出退出。改用方向性滑动。
常见模式
进入/退出
{show && (
<ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}
列表重排
{items.map(item => (
<ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}
在 startTransition 内部触发。避免在列表和 VT 之间使用包装 <div>。
在列表标识中组合共享元素
共享元素和列表标识是独立的关注点,不要混淆它们。当列表项包含一个共享元素时(例如,一个会变形为详情视图的图像),使用两个嵌套的 <ViewTransition> 边界:
{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 强制重新进入
<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
<ResultsGrid />
</ViewTransition>
注意: 如果包裹 <Suspense>,更改 key 会重新挂载边界并重新获取数据。
Suspense 回退到内容
简单交叉淡入淡出:
<ViewTransition>
<Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>
方向性揭示:
<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
<ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>
更多模式,参见 references/patterns.md。
多个 VT 如何交互
每个匹配触发器的 VT 在单个 document.startViewTransition 中同时触发。不同过渡中的 VT(导航与后续 Suspense 解决)不会竞争。
大量使用 default="none"
没有它,每个 VT 在每个过渡上都会触发浏览器的交叉淡入淡出。Suspense 解决、useDeferredValue 更新、后台重新验证。始终使用 default="none" 并仅显式启用所需的触发器。
两种模式共存
模式 A. 方向性滑动: 每个页面上的类型键控 VT,在导航期间触发。 模式 B. Suspense 揭示: 简单字符串属性,在数据加载时触发(没有类型)。
它们共存是因为它们在不同的时刻触发。两者上的 default="none" 可以防止交叉干扰。始终将 enter 与 exit 配对。将方向性 VT 放在页面组件中,而不是布局中。
嵌套 VT 限制
当父 VT 退出时,内部的嵌套 VT 不会触发它们自己的 enter/exit,只有最外层的 VT 会执行动画。页面导航期间的逐项交错动画目前无法实现。参见 react#36135 了解实验性的选择加入修复。
Next.js 集成
有关 Next.js 设置(experimental.viewTransition 标志、next/link 上的 transitionTypes 属性、App Router 模式、服务器组件),请参见 references/nextjs.md。
可访问性
始终将 references/css-recipes.md 中的减少动画 CSS 添加到全局样式表中。
参考文件
references/implementation.md:分步实现工作流程。references/patterns.md:模式、动画时序、事件 API、故障排除。references/css-recipes.md:现成的 CSS 动画配方。references/nextjs.md:Next.js App Router 模式和服务器组件详情。
完整编译文档
有关所有参考文件展开的完整指南:AGENTS.md
