过渡

使用 Vue 或原生浏览器视图过渡（View Transitions）在页面和布局之间应用过渡效果。

Nuxt 利用 Vue 的 <Transition> 组件在页面和布局之间应用过渡。

由于 Nuxt 使用了 Vue 的 <Transition> 组件，你想要添加动画的页面或布局必须拥有一个单一的根元素。包含多个根元素（即片段 Fragment）的页面或布局无法应用动画，因此过渡将不会运行，并且在路由之间导航时可能会报错。Nuxt 会在开发环境中对此发出警告。请将模板包裹在一个单一的根元素中（例如 <div>）。

页面过渡

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

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    pageTransition: { name: 'page', mode: 'out-in' },
  },
})

如果你在改变页面的同时也在改变布局，此处设置的页面过渡将不会生效。取而代之的是，你应该设置一个布局过渡。

要开始在页面之间添加过渡，请将以下 CSS 添加到你的 app.vue 中

<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>

<template>
  <div>
    <h1>Home page</h1>
    <NuxtLink to="/about">About page</NuxtLink>
  </div>
</template>

<template>
  <div>
    <h1>About page</h1>
    <NuxtLink to="/">Home page</NuxtLink>
  </div>
</template>

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

要为某个页面设置不同的过渡，请在该页面的 definePageMeta 中设置 pageTransition 键

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

<template>
  <NuxtPage />
</template>

<style>
/* ... */
.rotate-enter-active,
.rotate-leave-active {
  transition: all 0.4s;
}
.rotate-enter-from,
.rotate-leave-to {
  opacity: 0;
  transform: rotate3d(1, 1, 1, 15deg);
}
</style>

切换到关于页面将添加 3D 旋转效果

布局过渡

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

nuxt.config.ts

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

要开始在页面和布局之间添加过渡，请将以下 CSS 添加到你的 app.vue 中

<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>

<template>
  <div>
    <pre>default layout</pre>
    <slot />
  </div>
</template>

<style scoped>
div {
  background-color: lightgreen;
}
</style>

<template>
  <div>
    <pre>orange layout</pre>
    <slot />
  </div>
</template>

<style scoped>
div {
  background-color: #eebb90;
  padding: 20px;
  height: 100vh;
}
</style>

<template>
  <div>
    <h1>Home page</h1>
    <NuxtLink to="/about">About page</NuxtLink>
  </div>
</template>

<script setup lang="ts">
definePageMeta({
  layout: 'orange',
})
</script>

<template>
  <div>
    <h1>About page</h1>
    <NuxtLink to="/">Home page</NuxtLink>
  </div>
</template>

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

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

pages/about.vue

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

全局设置

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

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

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    pageTransition: {
      name: 'fade',
      mode: 'out-in', // default
    },
    layoutTransition: {
      name: 'slide',
      mode: 'out-in', // default
    },
  },
})

如果你更改了 name 属性，你还必须相应地重命名 CSS 类名。

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

pages/some-page.vue

<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'bounce',
    mode: 'out-in', // default
  },
})
</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 页面创建高度动态的自定义过渡。

这种方式为诸如 GSAP 之类的 JavaScript 动画库提供了完美的用例。

pages/some-page.vue

<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'custom-flip',
    mode: 'out-in',
    onBeforeEnter: (el) => {
      console.log('Before enter...')
    },
    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>

<script setup lang="ts">
const route = useRoute()
const id = computed(() => Number(route.params.id || 1))
const prev = computed(() => '/' + (id.value - 1))
const next = computed(() => '/' + (id.value + 1))
</script>

<template>
  <div>
    <slot />
    <div v-if="$route.params.id">
      <NuxtLink :to="prev">⬅️</NuxtLink> |
      <NuxtLink :to="next">➡️</NuxtLink>
    </div>
  </div>
</template>

现在，转到下一个 ID 时页面会应用 slide-left 过渡，转到上一个 ID 时会应用 slide-right 过渡

结合 NuxtPage 使用过渡

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

app/app.vue

<template>
  <div>
    <NuxtLayout>
      <NuxtPage
        :transition="{
          name: 'bounce',
          mode: 'out-in',
        }"
      />
    </NuxtLayout>
  </div>
</template>

请记住，此页面过渡无法通过各个页面上的 definePageMeta 进行覆盖。

视图过渡 API（实验性）

Nuxt 附带了 视图过渡 API (View Transitions API) 的实验性实现（参见 MDN）。这是一种令人兴奋的实现原生浏览器过渡的新方法，它（除其他功能外）能够在不同页面上不相关的元素之间进行过渡。

你可以在 StackBlitz 上查看演示。

可以在配置文件中通过 experimental.viewTransition 选项启用 Nuxt 集成

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    viewTransition: true,
  },
})

可选值为：false、true 或 'always'。

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

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

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    // Disable view transitions globally, and opt-in on a per page basis
    viewTransition: false,
  },
})

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

pages/about.vue

<script setup lang="ts">
definePageMeta({
  viewTransition: false,
})
</script>

只有在你启用了 experimental.viewTransition 选项的前提下，按页面覆盖视图过渡才会有效果。

视图过渡类型 v4.4

视图过渡类型允许你根据导航类型应用不同的 CSS 动画。这对于创建非对称过渡非常有用（例如，前进导航与后退导航时采用不同的动画）。

类型设置在 ViewTransition 上，并且可以在 CSS 中使用 :active-view-transition-type() 伪类选择器进行定位。

你可以在 nuxt.config.ts 中全局设置默认类型

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    viewTransition: {
      enabled: true,
      types: ['slide'],
    },
  },
})

或者使用 definePageMeta 按页面配置类型。单页类型同时支持用于动态行为的静态数组和函数

pages/detail.vue

<script setup lang="ts">
definePageMeta({
  viewTransition: {
    enabled: true,
    // Types applied to any transition involving this page
    types: ['slide'],
    // Types applied only when navigating TO this page
    toTypes: ['slide-in'],
    // Types applied only when navigating FROM this page
    fromTypes: ['slide-out'],
  },
})
</script>

你还可以在 definePageMeta 中为 types、toTypes 和 fromTypes 使用函数，从而根据路由动态确定类型

pages/[id].vue

<script setup lang="ts">
definePageMeta({
  viewTransition: {
    enabled: true,
    toTypes: (to, from) => {
      // Slide left when going to a higher ID, right otherwise
      return Number(to.params.id) > Number(from.params.id)
        ? ['slide-left']
        : ['slide-right']
    },
  },
})
</script>

然后在你的 CSS 中针对这些类型进行设置

/* Default crossfade */
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.3s;
}

/* Slide left animation */
html:active-view-transition-type(slide-left) {
  &::view-transition-old(root) {
    animation: slide-out-left 0.3s ease-in-out;
  }
  &::view-transition-new(root) {
    animation: slide-in-right 0.3s ease-in-out;
  }
}

/* Slide right animation */
html:active-view-transition-type(slide-right) {
  &::view-transition-old(root) {
    animation: slide-out-right 0.3s ease-in-out;
  }
  &::view-transition-new(root) {
    animation: slide-in-left 0.3s ease-in-out;
  }
}

types、toTypes 和 fromTypes 的函数值仅在 definePageMeta 中有效，在 nuxt.config.ts 中无效（后者仅支持静态 string[]）。

page:view-transition:start 钩子提供了对 ViewTransition 对象的访问权限，该对象包含一个可以在运行时读取或修改的 types 属性（ViewTransitionTypeSet）

plugins/view-transition.client.ts

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('page:view-transition:start', (transition) => {
    // Read or modify types at runtime
    console.log([...transition.types])
  })
})

如果你还使用了诸如 pageTransition 和 layoutTransition 之类的 Vue 过渡（见上文）来达到与新的视图过渡 API 相同的结果，那么如果用户的浏览器支持更新的本地网页 API，你可能希望禁用 Vue 过渡。你可以通过创建包含以下内容的 ~/middleware/disable-vue-transitions.global.ts 来实现这一点

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

  // Disable built-in Vue transitions
  to.meta.pageTransition = false
  to.meta.layoutTransition = false
})

已知问题

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

这有帮助吗？

报告问题或在 GitHub 上编辑此页

SEO 和 Meta

通过强大的 head 配置、组合式函数和组件，提升你的 Nuxt 应用的 SEO。

数据获取

Nuxt 提供了用于处理应用程序内数据获取的组合式函数。