过渡效果 · Nuxt 入门

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

布局过渡效果

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

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 键都接受 TransitionProps 作为 JSON 可序列化的值，您可以在其中传递 name，mode 以及自定义 CSS 过渡的其他有效过渡属性。

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 页面创建高度动态和自定义的过渡效果。

这种方式非常适合使用 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 钩子的更多信息。

动态过渡

要使用条件逻辑应用动态过渡，您可以利用内联中间件将不同的过渡名称分配给 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
: {
    // 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 选项时，按页面覆盖视图过渡才会生效。

如果您还使用诸如 pageTransition 和 layoutTransition 之类的 Vue 过渡效果（请参阅上文）来实现与新的视图过渡 API 相同的结果，那么如果用户的浏览器支持较新的原生 Web 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
})

已知问题

如果您在页面设置函数中执行数据获取，那么您可能需要暂时重新考虑使用此功能。（根据设计，视图过渡会在发生时完全冻结 DOM 更新。）我们正在考虑将视图过渡限制在 <Suspense> 解析之前的最后时刻，但在过渡期间，如果这种情况描述了您的情况，则可能需要仔细考虑是否采用此功能。

SEO 和 Meta

使用强大的 head 配置、组合和组件来改善您的 Nuxt 应用程序的 SEO。

数据获取

Nuxt 提供了组合，以处理应用程序中的数据获取。