v3.16
Nuxt on GitHub

过渡

使用 Vue 或原生浏览器视图过渡 API 在页面和布局之间应用过渡效果。
Nuxt 利用 Vue 的 <Transition> 组件在页面和布局之间应用过渡效果。

页面过渡

你可以启用页面过渡，为所有 页面 自动应用过渡效果。

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    pageTransition: { name: 'page', mode: 'out-in' }
  },
})
如果你同时更改了布局和页面，此处设置的页面过渡不会运行。相反，你应该设置 布局过渡。

要在页面之间添加过渡效果，请在 app.vue 中添加以下 CSS：

<template>
  <NuxtPage />
</template>

<style>
.page-enter-active,
.page-leave-active {
  transition: all 0.4s;
}
.page-enter-from,
.page-leave-to {
  opacity: 0;
  filter: blur(1rem);
}
</style>

这会在页面导航时产生以下效果：

要为某个页面设置不同的过渡效果，可以在该页面的 definePageMeta 中设置 pageTransition 键：

<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'rotate'
  }
})
</script>

访问“关于”页面时将添加 3D 旋转效果：

布局过渡

你可以启用布局过渡，为所有 布局 自动应用过渡效果。

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    layoutTransition: { name: 'layout', mode: 'out-in' }
  },
})

要在页面和布局之间添加过渡效果，请在 app.vue 中添加以下 CSS：

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

<style>
.layout-enter-active,
.layout-leave-active {
  transition: all 0.4s;
}
.layout-enter-from,
.layout-leave-to {
  filter: grayscale(1);
}
</style>

这会在页面导航时产生以下效果：

与 pageTransition 类似，你可以使用 definePageMeta 为页面组件应用自定义 layoutTransition：

pages/about.vue
<script setup lang="ts">
definePageMeta({
  layout: 'orange',
  layoutTransition: {
    name: 'slide-in'
  }
})
</script>

全局设置

你可以使用 nuxt.config 全局自定义这些默认过渡名称。

pageTransition 和 layoutTransition 键接受 TransitionProps 作为 JSON 可序列化的值，你可以在其中传递 name、mode 和其他有效的自定义 CSS 过渡属性。

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    pageTransition: {
      name: 'fade',
      mode: 'out-in' // 默认值
    },
    layoutTransition: {
      name: 'slide',
      mode: 'out-in' // 默认值
    }
  }
})
如果你更改了 name 属性，还需要相应地重命名 CSS 类。

要覆盖全局过渡属性，可以使用 definePageMeta 为单个 Nuxt 页面定义页面或布局过渡，并覆盖在 nuxt.config 文件中全局定义的任何页面或布局过渡。

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'bounce',
    mode: 'out-in' // 默认值
  }
})
</script>

禁用过渡

可以为特定路由禁用 pageTransition 和 layoutTransition：

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  pageTransition: false,
  layoutTransition: false
})
</script>

或在 nuxt.config 中全局禁用：

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    pageTransition: false,
    layoutTransition: false
  }
})

JavaScript 钩子

对于高级用例，你可以使用 JavaScript 钩子为 Nuxt 页面创建高度动态和自定义的过渡效果。

这种方式非常适合使用 JavaScript 动画库，例如 GSAP。

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'custom-flip',
    mode: 'out-in',
    onBeforeEnter: (el) => {
      console.log('进入之前...')
    },
    onEnter: (el, done) => {},
    onAfterEnter: (el) => {}
  }
})
</script>
了解更多关于 Transition 组件中可用的 JavaScript 钩子。

动态过渡

要使用条件逻辑应用动态过渡，可以利用内联 中间件 为 to.meta.pageTransition 分配不同的过渡名称。

<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'slide-right',
    mode: 'out-in'
  },
  middleware (to, from) {
    if (to.meta.pageTransition && typeof to.meta.pageTransition !== 'boolean')
      to.meta.pageTransition.name = +to.params.id! > +from.params.id! ? 'slide-left' : 'slide-right'
  }
})
</script>

<template>
  <h1>#{{ $route.params.id }}</h1>
</template>

<style>
.slide-left-enter-active,
.slide-left-leave-active,
.slide-right-enter-active,
.slide-right-leave-active {
  transition: all 0.2s;
}
.slide-left-enter-from {
  opacity: 0;
  transform: translate(50px, 0);
}
.slide-left-leave-to {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-enter-from {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-leave-to {
  opacity: 0;
  transform: translate(50px, 0);
}
</style>

页面现在会在前往下一个 id 时应用 slide-left 过渡，前往上一个 id 时应用 slide-right：

使用 NuxtPage 的过渡

当在 app.vue 中使用 <NuxtPage /> 时，可以通过 transition 属性配置过渡效果，以全局启用过渡。

app.vue
<template>
  <div>
    <NuxtLayout>
      <NuxtPage :transition="{
        name: 'bounce',
        mode: 'out-in'
      }" />
    </NuxtLayout>
  </div>
</template>
请记住，这种页面过渡无法通过单个页面上的 definePageMeta 覆盖。

视图过渡 API（实验性）

Nuxt 提供了一个实验性的 视图过渡 API 实现（参见 MDN）。这是一个令人兴奋的新方式，可以实现原生浏览器过渡效果，尤其是在不同页面上无关元素之间的过渡。

你可以在 https://nuxt-view-transitions.surge.sh 查看演示，以及 StackBlitz 上的源码。

Nuxt 的集成正在积极开发中，但可以通过配置文件中的 experimental.viewTransition 选项启用：

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    viewTransition: true
  }
})

可能的值为：false、true 或 'always'。

如果设置为 true，Nuxt 会在用户浏览器匹配 prefers-reduced-motion: reduce 时不应用过渡（推荐）。如果设置为 'always'，Nuxt 将始终应用过渡，由你来决定是否尊重用户的偏好。

默认情况下，视图过渡对所有 页面 启用，但你可以设置不同的全局默认值。

nuxt.config.ts
export default defineNuxtConfig({
  app: {
    // 全局禁用视图过渡，按页面逐个启用
    viewTransition: false
  },
})

可以通过在页面的 definePageMeta 中设置 viewTransition 键来覆盖默认的 viewTransition 值：

pages/about.vue
<script setup lang="ts">
definePageMeta({
  viewTransition: false
})
</script>
按页面覆盖视图过渡仅在启用 experimental.viewTransition 选项时有效。

如果你同时使用 Vue 过渡（如上所述的 pageTransition 和 layoutTransition）来实现与新视图过渡 API 相同的结果，你可能希望在用户浏览器支持较新的原生 Web API 时 禁用 Vue 过渡。你可以通过创建 ~/middleware/disable-vue-transitions.global.ts 并添加以下内容来实现：

export default defineNuxtRouteMiddleware(to => {
  if (import.meta.server || !document.startViewTransition) { return }

  // 禁用内置 Vue 过渡
  to.meta.pageTransition = false
  to.meta.layoutTransition = false
})

已知问题

  • 如果你在页面设置函数中进行数据获取，暂时可能需要重新考虑使用此功能。（根据设计，视图过渡会在进行时完全冻结 DOM 更新。）我们正在考虑将视图过渡限制在 <Suspense> 解析前的最后时刻，但在过渡期间，你可能需要仔细考虑是否采用此功能。