过渡效果 Transitions

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

页面间的过渡

您可以启用页面过渡以对所有 页面 应用自动过渡。

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

如果您正在更改布局和页面，您在此处设置的页面过渡将不会运行。 相反，您应该设置一个布局间的过渡。

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

html
app.vue
html
<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 键：

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

移动到关于页面将添加 3d 旋转效果：

布局间的过渡

您可以启用布局过渡以对所有 布局 应用自动过渡。

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

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

html
app.vue
html
<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
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
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
vue
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'bounce',
    mode: 'out-in' // default
  }
})
</script>

禁用过渡

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

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

或者在 nuxt.config 中全局：

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

钩子

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

这种方式为 JavaScript 动画库提供了完美的用例，例如 GSAP 或 Tween.js。

pages/some-page.vue
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 挂钩。

动态过渡

要使用条件逻辑应用动态转换，您可以利用内联 middleware 为 to.meta.pageTransition 分配不同的转换名称。

html
pages/[id
html
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'slide-right',
    mode: 'out-in'
  },
  middleware (to, from) {
    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>

The page now applies the slide-left transition when going to the next id and slide-right for the previous:

与 NuxtPage 的过渡

在 app.vue 中使用 <NuxtPage /> 时，可以直接将 transition-props 作为组件 props 传递，以激活全局过渡。

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

记住，这个页面的过渡效果不能被在个别页面中使用definePageMeta重写。
也就是说，如果你已经在全局配置中为该页面定义了过渡效果，那么无法在单个页面中重新定义该效果。

视图过渡 API(实验性)

Nuxt 附带 View Transitions API 的实验性实现(参见 MDN)。 这是实现本机浏览器转换的令人兴奋的新方法，它(除其他外)能够在不同页面上的不相关元素之间进行转换。

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

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

如果您还使用 Vue 转换，如 pageTransition 和 layoutTransition(见上文)来实现与新的 View Transitions API 相同的结果，那么如果用户的浏览器支持更新的本机 Web API，您可能希望 禁用 Vue 转换 . 您可以通过使用以下内容创建 ~/middleware/disable-vue-transitions.global.ts 来做到这一点：

js
export default defineNuxtRouteMiddleware((to) => {
  if (!document.startViewTransition)
    return

  // 禁用内置 Vue 转换
  to.meta.pageTransition = false
  to.meta.layoutTransition = false
})

已知问题

  • 由于这个上游 Vue 错误：https://github.com/vuejs/core/issues/5513，视图转换可能无法按预期使用嵌套页面/布局/异步组件。 如果您使用此模式，则可能需要延迟采用此实验性功能或自行实施。 非常欢迎反馈。
  • 如果您在页面设置功能中执行数据获取，您可能希望暂时重新考虑使用此功能。 (根据设计，View Transitions 在 DOM 更新发生时完全冻结它们。)我们正在考虑将 View Transitions 限制在 <Suspense> 解决之前的最后时刻，但在此期间您可能需要仔细考虑是否 如果这描述了您，请采用此功能。