Learn Nuxt with a Collection of 100+ Tips!
54.2K

过渡效果

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

页面过渡效果

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

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>

在页面之间导航时，会产生以下结果：

要为页面设置不同的过渡效果，请在页面的 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' }
  },
})

要开始在页面和布局之间添加过渡效果，请将以下 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>

在页面之间导航时，会产生以下结果：

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

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

全局设置

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

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

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

要覆盖全局的过渡属性，使用 definePageMeta 定义页面或布局过渡效果，覆盖了在 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('Before enter...')
    },
    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) {
    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，则当用户的浏览器匹配 prefers-reduced-motion: reduce（推荐）时，Nuxt 不会应用过渡效果。如果设置为 '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 选项时，按页面覆盖视图过渡效果才会生效。

如果您还使用了类似于上述的 pageTransition 和 layoutTransition 的 Vue 过渡效果来实现和新的 View Transitions 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
})

已知问题

  • 如果在页面设置函数中执行数据获取操作，您可能需要重新考虑当前是否使用该功能。（根据设计，当 View Transitions 正在进行时，它完全冻结 DOM 更新。）我们正在探索将 View Transition 限制在 <Suspense> 解析之前的最后一刻，但在此期间，如果描述适用于您，您可能需要仔细考虑是否采用此功能。

SEO 和 Meta

使用强大的头部配置、组合函数和组件来改善你的 Nuxt 应用的 SEO。

数据获取

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