Nuxt3 中文课程《实战全栈开发简书》限时优惠

过渡效果

使用Vue或本地浏览器的视图过渡在页面和布局之间应用过渡效果。
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全局自定义这些默认的过渡效果名称。

pageTransitionlayoutTransition键都接受TransitionProps作为JSON可序列化的值,你可以通过它传递自定义CSS过渡的namemode和其他有效的过渡属性。

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>

禁用过渡效果

可以为特定的路由禁用pageTransitionlayoutTransition

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

或在nuxt.config中全局禁用:

nuxt.config.ts
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('进入之前...')
    },
    onEnter: (el, done) => {},
    onAfterEnter: (el) => {}
  }
})
</script>
了解更多关于Transition组件中可用的其他JavaScript钩子

动态过渡效果

要使用条件逻辑应用动态过渡效果,你可以利用内联middleware将不同的过渡名称分配给to.meta.pageTransition

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

页面现在在前往下一个id时应用slide-left过渡效果,在前一个id时应用slide-right过渡效果:

使用NuxtPage的过渡效果

当在app.vue中使用<NuxtPage />时,可以直接将过渡属性作为组件属性传递以激活全局过渡效果。

app.vue
<template>
  <div>
    <NuxtLayout>
      <NuxtPage :transition="{
        name: 'bounce',
        mode: 'out-in'
      }" />
    </NuxtLayout>
  </div>
</template>
请记住,此页面过渡效果无法通过在单个页面上使用definePageMeta来覆盖。

视图过渡API(实验性)

Nuxt附带了一个实验性的视图过渡API(参见MDN)。这是一种令人兴奋的新方法,用于实现本地浏览器过渡效果,它具有在不同页面的不相关元素之间进行过渡的能力,以及其他功能。

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

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

如果你还使用了类似于pageTransitionlayoutTransition(参见上文)的Vue过渡效果来实现与新的视图过渡API相同的结果,那么你可能希望在用户的浏览器支持较新的本地Web API时_禁用_Vue过渡效果。你可以通过创建~/middleware/disable-vue-transitions.global.ts文件并包含以下内容来实现:

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

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

已知问题

  • 由于上游Vue的一个bug:https://github.com/vuejs/core/issues/5513,视图过渡可能无法按预期工作,特别是在嵌套页面/布局/异步组件中。如果你使用这种模式,你可能需要延迟采用这个实验性功能或自己实现它。非常欢迎您的反馈。
  • 如果在页面设置函数中执行数据获取操作,您可能需要重新考虑暂时不使用此功能。(按设计,视图过渡在进行时完全冻结DOM更新。)我们正在考虑将视图过渡限制在<Suspense>解析之前的最后时刻,但在此期间,如果您符合上述情况,您可能需要仔细考虑是否采用此功能。