NNext.js 中文网 GitHub

设计视图过渡

了解如何使用视图过渡在 Next.js 应用的导航、加载和内容变化期间传达含义。

在 Web 应用中,路由变化会一次性替换整个页面。一组元素消失,另一组出现,它们之间没有视觉联系。用户选择一张照片缩略图以在另一页面上查看详情。它们是同一张图片,但屏幕上没有任何内容传达这一点。

需要这些过渡的应用通常依赖复杂的动画库,这些库管理挂载/卸载生命周期、跨路由跟踪元素位置并手动协调时间,以动画化元素如何进入、退出和在状态之间移动。

React 的 <ViewTransition> 组件与浏览器的 View Transitions API 集成,以声明方式处理这一切。你为应该保留的元素命名,浏览器会在它们的新旧位置之间制作动画。

本指南介绍四种涵盖最常见情况的模式:共享元素变形、加载状态动画、添加方向性导航,以及同一路由内的内容交叉淡入淡出。

使用 agent 添加视图过渡#

vercel-react-view-transitions skill 会向编码 agent 教授本指南中的模式,以及将其应用于现有应用的 CSS 配方和故障排除方法。

安装该 skill:

Terminal
npx skills add vercel-labs/agent-skills --skill vercel-react-view-transitions

然后向 agent 发出类似这样的提示:

prompt
使用 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 组件:

tsx
import { ViewTransition } from 'react'

<ViewTransition> 动画由 Transitions、<Suspense> 和 useDeferredValue 激活。普通的 setState 调用不会触发它们。在 Next.js 中,使用 <Link>、router.push() 和 router.replace() 的导航属于过渡,因此 <ViewTransition> 动画会自动激活。浏览器历史导航不会触发这些动画。

步骤 1:将缩略图变形为主图#

画廊以网格形式显示照片。点击照片会打开一个详情页,显示同一张图片的更大版本。没有过渡时,缩略图消失,主图出现。两者之间没有视觉联系。用户必须浏览详情页才能确认自己点击的是正确的照片。

在动效设计中,当一个对象在镜头切换中持续存在时,它传达了连续性。观看者明白他们看到的是同一个东西,而不是替代品。这是最重要的过渡模式:共享元素变形。

用相同的 name 将网格缩略图和详情主图都包裹在 <ViewTransition> 中:

components/photo-grid.tsx
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>
  )
}
app/photo/[id]/photo-content.tsx
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 关键帧在变形过程中柔化效果:

tsx
<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 属性,该配对会静默停止变形。

app/globals.css
::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 中:

app/photo/[id]/page.tsx
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):

app/globals.css
: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 属性来标记前进导航:

components/photo-grid.tsx
<Link href={`/photo/${photo.id}`} transitionTypes={['nav-forward']}>
  
</Link>

相同的模式适用于应用中的其他链接。例如,照片详情页上的上一个/下一个箭头可以使用 nav-back 和 nav-forward 以相应方向制作动画。

对于返回上一页的链接,使用 nav-back:

app/photo/[id]/page.tsx
<Link href="/" transitionTypes={['nav-back']}>
  ← Gallery
</Link>

过渡类型不是自动的。你需要根据应用的导航层级决定哪些链接是“前进”,哪些是“后退”。

然后将页面内容包裹在一个 ViewTransition 中,将过渡类型映射到方向性动画:

app/photo/[id]/page.tsx
<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 在导航之间持续存在,因此进入和退出不会在那里触发:

app/page.tsx
<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:

app/globals.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 中抑制其动画:

components/header.tsx
<header style={{ viewTransitionName: 'site-header' }}>
  
</header>
app/globals.css
::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 覆盖层会捕获指针事件,因此动画期间的点击会丢失。让点击穿透到实际页面:

app/globals.css
::view-transition {
  pointer-events: none;
}

这会恢复未命名内容的交互性。在过渡期间,命中测试仍会跳过命名的参与者(如固定的页头),因此请保持过渡简短,避免为那些用户会快速点击的元素命名。

尊重减少动态效果#

方向性滑动模拟视口中的物理移动。这是引发动态敏感的最常见原因。变形、揭示和交叉淡入淡出的风险较小,因为它们影响区域较小或依赖不透明度而非位置。

最简单的方法是禁用所有动画持续时间:

app/globals.css
@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 会在旧内容和新内容之间触发过渡:

app/collection/[slug]/page.tsx
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 详细信息和更多模式:

Next.js 中文网