過渡

使用 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 鍵都接受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 頁面建立高度動態和自定義的過渡。

這種方式為 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 的過渡

當 <NuxtPage /> 在 app.vue 中使用時，可以透過 transition 屬性配置過渡以全域性啟用過渡。

app/app.vue
<template>
  <div>
    <NuxtLayout>
      <NuxtPage
        :transition="{
          name: 'bounce',
          mode: 'out-in',
        }"
      />
    </NuxtLayout>
  </div>
</template>
請記住，此頁面過渡不能在單個頁面上使用 definePageMeta 覆蓋。

檢視過渡 API（實驗性）

Nuxt 附帶了檢視過渡 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 選項時才有效。

如果您還使用 Vue 過渡（如 pageTransition 和 layoutTransition（參見上文））來實現與新檢視過渡 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> 解析之前的最後時刻，但在此期間，如果您屬於這種情況，您可能需要仔細考慮是否採用此功能。