设计视图过渡
了解如何使用视图过渡在 Next.js 应用的导航、加载和内容变化期间传达含义。
在 Web 应用中,路由变化会一次性替换整个页面。一组元素消失,另一组出现,它们之间没有视觉联系。用户选择一张照片缩略图以在另一页面上查看详情。它们是同一张图片,但屏幕上没有任何内容传达这一点。
需要这些过渡的应用通常依赖复杂的动画库,这些库管理挂载/卸载生命周期、跨路由跟踪元素位置并手动协调时间,以动画化元素如何进入、退出和在状态之间移动。
React 的 <ViewTransition> 组件与浏览器的 View Transitions API 集成,以声明方式处理这一切。你为应该保留的元素命名,浏览器会在它们的新旧位置之间制作动画。
本指南介绍四种涵盖最常见情况的模式:共享元素变形、加载状态动画、添加方向性导航,以及同一路由内的内容交叉淡入淡出。
使用 agent 添加视图过渡#
vercel-react-view-transitions skill 会向编码 agent 教授本指南中的模式,以及将其应用于现有应用的 CSS 配方和故障排除方法。
安装该 skill:
npx skills add vercel-labs/agent-skills --skill vercel-react-view-transitions然后向 agent 发出类似这样的提示:
使用 vercel-react-view-transitions skill 为此应用添加视图过渡。或者针对特定过渡发出提示,例如:
- 将缩略图变形为主图
- 在路由之间向前和向后滑动
- 在同一路由内交叉淡入淡出内容
要自行应用这些模式,请按照下面的演练操作。
示例#
作为示例,我们将构建一个名为 Frames 的摄影画廊。
我们将首先将缩略图变形为主图(共享元素),然后将加载骨架动画化为真实内容(Suspense 揭示),为前进和后退导航添加方向性滑动(路由过渡),最后以摄影师标签页之间的交叉淡入淡出(同路由过渡)收尾。
你可以在此处找到此示例中使用的资源:
视图过渡在 App Router 中无需配置即可工作。React 19.3 包含本指南中使用的 <ViewTransition> 组件和 addTransitionType API。
[!NOTE] React 的集成使用了较新的 View Transitions API 功能(过渡类型和
view-transition-class),这些功能在 Chromium 125+ 以及较新版本的 Safari 和 Firefox 中可用。某些动画在 Safari 中的行为可能有所不同。如果没有浏览器支持,你的应用仍可正常工作;只是过渡不会播放动画。
从 React 导入 ViewTransition 组件:
import { ViewTransition } from 'react'<ViewTransition> 动画由 Transitions、<Suspense> 和 useDeferredValue 激活。普通的 setState 调用不会触发它们。在 Next.js 中,使用 <Link>、router.push() 和 router.replace() 的导航属于过渡,因此 <ViewTransition> 动画会自动激活。浏览器历史导航不会触发这些动画。
步骤 1:将缩略图变形为主图#
画廊以网格形式显示照片。点击照片会打开一个详情页,显示同一张图片的更大版本。没有过渡时,缩略图消失,主图出现。两者之间没有视觉联系。用户必须浏览详情页才能确认自己点击的是正确的照片。
在动效设计中,当一个对象在镜头切换中持续存在时,它传达了连续性。观看者明白他们看到的是同一个东西,而不是替代品。这是最重要的过渡模式:共享元素变形。
用相同的 name 将网格缩略图和详情主图都包裹在 <ViewTransition> 中:
import { ViewTransition } from 'react'
import Image from 'next/image'
import Link from 'next/link'
function PhotoGrid({ photos }) {
return (
<div className="grid grid-cols-3 gap-3">
{photos.map((photo) => (
<Link key={photo.id} href={`/photo/${photo.id}`}>
<ViewTransition name={`photo-${photo.id}`}>
<Image src={photo.src} alt={photo.title} />
</ViewTransition>
</Link>
))}
</div>
)
}import { ViewTransition } from 'react'
import Image from 'next/image'
async function PhotoContent({ id }) {
const photo = await getPhoto(id)
return (
<ViewTransition name={`photo-${photo.id}`}>
<div style={{ position: 'relative', aspectRatio: '3 / 2' }}>
<Image src={photo.src} alt={photo.title} fill />
</div>
</ViewTransition>
)
}name 属性创建身份标识。React 会在新旧页面上查找具有相同名称的元素,然后自动在它们的大小和位置之间制作动画。无需其他属性即可实现变形。
现在如果我们点击缩略图,图像会从其网格单元格缩放并重新定位到主图位置。使用 <Link href="/"> 返回画廊会反转变形。用户看到的是一个对象在移动,而不是两个对象在交换。
当目标内容与导航在同一次提交中渲染时,变形会播放,预取(缓存)的页面就是这种情况。如果目标内容先挂起进入 fallback,则不会形成配对,内容到达时会改用其进入动画。
自定义变形动画#
变形无需任何 CSS 即可工作。要自定义它,请添加 share="morph" 以及 default="none"。share 属性会将 morph 类分配给视图过渡,你可以使用 CSS 伪元素来定位它。例如,使用 blur 关键帧在变形过程中柔化效果:
<ViewTransition name={`photo-${photo.id}`} share="morph" default="none">
<Image src={photo.src} alt={photo.title} />
</ViewTransition>将相同的属性添加到步骤 1 的两个代码片段(photo-grid.tsx 和 photo-content.tsx)中。default="none" 可防止每张命名图像在每次无关的过渡中运行自己的交叉淡入淡出。没有它,页面上任何过渡运行时,每个命名的 <ViewTransition> 都会播放动画。当你为命名配对添加 default="none" 时,请保留显式的 share。如果使用 default="none" 而没有 share 属性,该配对会静默停止变形。
::view-transition-group(.morph) {
animation-duration: 400ms;
}
::view-transition-image-pair(.morph) {
animation-name: via-blur;
}
@keyframes via-blur {
30% {
filter: blur(3px);
}
}模糊效果隐藏了过渡期间像素级的插值瑕疵。在 400ms 时,变形速度慢到足以被感知,但又快到感觉直接。
步骤 2:使用 Suspense 揭示为加载状态制作动画#
照片详情页异步加载其内容。当数据仍在传输时,Suspense 边界会显示骨架。当数据解析完成后,骨架会被真实内容替换。
没有过渡时,替换是瞬间完成的。骨架消失,内容突然弹出。
在动效设计中,垂直方向编码层级。内容向上滑动传达“到达”,向下滑动传达“离开”。两者共同创造了一种交接:占位符让位于真实内容。
将 Suspense fallback 包裹在带有退出动画的 ViewTransition 中,将内容包裹在带有进入动画的 ViewTransition 中:
import { Suspense, ViewTransition } from 'react'
export default async function PhotoPage({ params }) {
const { id } = await params
return (
<Suspense
fallback={
<ViewTransition exit="slide-down" default="none">
<PhotoContentSkeleton />
</ViewTransition>
}
>
<ViewTransition enter="slide-up" default="none">
<PhotoContent id={id} />
</ViewTransition>
</Suspense>
)
}与步骤 1 一样,default="none" 可防止此 ViewTransition 在无关的过渡(如共享元素变形)期间播放动画。
CSS 动画使用不对称的时间设置。退出很快(150ms)。进入淡入较慢(210ms),并延迟到退出完成后才开始,而其滑动运动持续时间更长(400ms):
:root {
--duration-exit: 150ms;
--duration-enter: 210ms;
--duration-move: 400ms;
}
::view-transition-old(.slide-down) {
animation:
var(--duration-exit) ease-out both fade reverse,
var(--duration-exit) ease-out both slide-y reverse;
}
::view-transition-new(.slide-up) {
animation:
var(--duration-enter) ease-in var(--duration-exit) both fade,
var(--duration-move) ease-in both slide-y;
}
@keyframes fade {
from {
filter: blur(3px);
opacity: 0;
}
to {
filter: blur(0);
opacity: 1;
}
}
@keyframes slide-y {
from {
transform: translateY(10px);
}
to {
transform: translateY(0);
}
}这种不对称是刻意为之。旧内容应快速离开,以免争夺注意力。新内容应更柔和地到达,让用户有时间感知它。进入淡入上的 var(--duration-exit) 延迟意味着新内容会等待旧内容完全离开后才变得可见。
如果我们刷新页面,骨架会向下滑动并淡出,片刻之后真实内容会向上滑动并淡入。
步骤 3:为导航添加方向性运动#
现在画廊已经有了变形图像和动画加载状态。但页面之间的导航仍然没有方向性信号。前进和后退导航看起来一模一样。用户无法从动画中判断自己是深入了应用还是返回了上一页。
在电影和动画中,水平方向编码空间位置。向左移动表示向前推进(就像在从左到右的语言中翻页)。向右移动表示返回。这一约定根深蒂固,违反它会让人感到迷失方向。
使用 <Link> 上的 transitionTypes 属性来标记前进导航:
<Link href={`/photo/${photo.id}`} transitionTypes={['nav-forward']}>
</Link>相同的模式适用于应用中的其他链接。例如,照片详情页上的上一个/下一个箭头可以使用 nav-back 和 nav-forward 以相应方向制作动画。
对于返回上一页的链接,使用 nav-back:
<Link href="/" transitionTypes={['nav-back']}>
← Gallery
</Link>过渡类型不是自动的。你需要根据应用的导航层级决定哪些链接是“前进”,哪些是“后退”。
然后将页面内容包裹在一个 ViewTransition 中,将过渡类型映射到方向性动画:
<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"
>
</ViewTransition>enter 和 exit 属性接受一个以过渡类型为键的对象。当导航带有 nav-forward 类型时,退出动画将旧内容向左滑动,进入动画将新内容从右侧滑入。default: "none" 确保没有类型的过渡(router.refresh()、Suspense 揭示)不会产生方向性动画。
以相同方式包裹每个参与过渡的页面。要让画廊在前进导航时滑出、在 nav-back 时滑回,其页面需要相同的包裹器。将包裹器放在每个 page.tsx 中,而不是 layout 中。Layout 在导航之间持续存在,因此进入和退出不会在那里触发:
<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"
>
<PhotoGrid photos={photos} />
</ViewTransition>方向性滑动的 CSS:
::view-transition-old(.nav-forward) {
--slide-offset: -60px;
animation:
150ms ease-in both fade reverse,
400ms ease-in-out both slide reverse;
}
::view-transition-new(.nav-forward) {
--slide-offset: 60px;
animation:
210ms ease-out 150ms both fade,
400ms ease-in-out both slide;
}
::view-transition-old(.nav-back) {
--slide-offset: 60px;
animation:
150ms ease-in both fade reverse,
400ms ease-in-out both slide reverse;
}
::view-transition-new(.nav-back) {
--slide-offset: -60px;
animation:
210ms ease-out 150ms both fade,
400ms ease-in-out both slide;
}
@keyframes slide {
from {
translate: var(--slide-offset);
}
to {
translate: 0;
}
}60px 的偏移量足以传达方向,而不会让用户费力追踪屏幕上快速移动的元素。
固定页头#
在方向性滑动期间,页头不应移动。滑动的页头会破坏用户的空间锚点。他们需要一个固定的参照点来理解移动的是内容,而不是整个视口。
为页头分配一个 viewTransitionName 并在 CSS 中抑制其动画:
<header style={{ viewTransitionName: 'site-header' }}>
</header>::view-transition-group(site-header) {
animation: none;
z-index: 100;
}
::view-transition-old(site-header) {
display: none;
}
::view-transition-new(site-header) {
animation: none;
}旧快照上的 display: none 可防止新旧页头同时短暂可见的闪烁。z-index: 100 确保页头渲染在滑动内容之上。
如果我们向前导航到一张照片,内容会向左滑动。如果点击“← Gallery”链接(标记为 nav-back),内容会向右滑动。在这两种过渡中,页头始终保持固定。
浏览器历史导航#
浏览器的后退和前进按钮、历史记录滑动手势、router.back() 和 router.forward() 不会触发视图过渡动画,包括共享元素变形。Next.js 通过 popstate 处理这些导航,为此 React 会跳过视图过渡动画以保留滚动和表单恢复。匹配的 name 属性不会改变这一行为。
要为返回画廊制作动画,请使用上面的 <Link href="/">。它会启动一次新的导航,而不是遍历浏览器历史。匹配的 name 属性启用共享元素变形,transitionTypes={['nav-back']} 选择方向性滑动。
保持页面可交互#
过渡运行时,::view-transition 覆盖层会捕获指针事件,因此动画期间的点击会丢失。让点击穿透到实际页面:
::view-transition {
pointer-events: none;
}这会恢复未命名内容的交互性。在过渡期间,命中测试仍会跳过命名的参与者(如固定的页头),因此请保持过渡简短,避免为那些用户会快速点击的元素命名。
尊重减少动态效果#
方向性滑动模拟视口中的物理移动。这是引发动态敏感的最常见原因。变形、揭示和交叉淡入淡出的风险较小,因为它们影响区域较小或依赖不透明度而非位置。
最简单的方法是禁用所有动画持续时间:
@media (prefers-reduced-motion: reduce) {
::view-transition-old(*),
::view-transition-new(*),
::view-transition-group(*) {
animation-duration: 0s !important;
animation-delay: 0s !important;
}
}没有动画时,内容会瞬间替换,这是浏览器的默认行为。更精细的做法是保留交叉淡入淡出和不透明度过渡,同时移除位置移动。有关更多信息,请参阅“无动画并不总是 prefers-reduced-motion”。
步骤 4:在同一路由内交叉淡入淡出内容#
画廊有一个带标签页的摄影师版块。每个标签页显示不同摄影师的照片,但路由结构相同:/collection/[slug]。在标签页之间点击不像是导航到新页面,而更像是在同一容器内切换内容。
这里使用方向性滑动是错误的。滑动传达的是“去往新地方”,而交叉淡入淡出传达的是“同一地点,不同内容”。容器持续存在(连续性),只有内部的网格发生变化(替换)。
使用 key 设置为当前 slug 的 ViewTransition。当 key 变化时,React 会在旧内容和新内容之间触发过渡:
import { Suspense, ViewTransition } from 'react'
export default async function CollectionPage({ params }) {
const { slug } = await params
return (
<Suspense fallback={<CollectionGridSkeleton />}>
<ViewTransition
key={slug}
name="collection-content"
share="auto"
enter="auto"
default="none"
>
<CollectionGrid slug={slug} />
</ViewTransition>
</Suspense>
)
}share="auto" 和 enter="auto" 属性告诉 React 使用其默认的交叉淡入淡出动画。name 属性为容器提供身份标识,使 React 知道要为哪些内容制作动画。导航触发过渡;key={slug} 的变化使 React 将旧内容和新内容视为退出/进入配对(激活 share),而不是就地更新。
如果在摄影师标签页之间点击,网格会交叉淡入淡出。标签栏和周围的 layout 不会移动。只有照片网格在状态之间过渡。
后续步骤#
现在你已经知道如何使用视图过渡在导航期间传达含义。共享元素传达跨路由的连续性。Suspense 揭示为加载交接制作动画。方向性滑动编码导航历史。交叉淡入淡出表示同一位置内的内容变化。
每种模式为用户回答一个不同的问题:
| 模式 | 传达的含义 |
|---|---|
| 共享元素(变形) | “同一个东西,继续深入” |
| Suspense 揭示 | “数据已加载” |
| 方向性滑动 | “前进 / 返回” |
| 同路由交叉淡入淡出 | “同一地点,不同内容” |
有关 API 详细信息和更多模式:
- Link 的
transitionTypes属性 useRouter,它也在push()和replace()中支持transitionTypes- React
ViewTransition组件 - 本指南的完整 CSS——所有关键帧和视图过渡规则都在一个文件中