轉場效果

頁面轉場效果

您可以啟用頁面轉場效果，為您的所有頁面應用自動轉場效果。

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>

移動到 about 頁面將新增 3D 旋轉效果

版面配置轉場效果

您可以啟用版面配置轉場效果，為您的所有版面配置應用自動轉場效果。

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 應用於頁面元件

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

全域設定

您可以使用 nuxt.config 全域自訂這些預設轉場效果名稱。

pageTransition 和 layoutTransition 鍵都接受 TransitionProps 作為 JSON 可序列化值，您可以在其中傳遞自訂 CSS 轉場效果的 name、mode 和其他有效的 transition-props。

export default 
defineNuxtConfig
({
  
app
: {
    
pageTransition
: {
      
name
: 'fade',
      
mode
: 'out-in' // default
    },
    
layoutTransition
: {
      
name
: 'slide',
      
mode
: 'out-in' // default
    }
  }
})

若要覆寫全域轉場效果屬性，請使用 definePageMeta 為單一 Nuxt 頁面定義頁面或版面配置轉場效果，並覆寫在 nuxt.config 檔案中全域定義的任何頁面或版面配置轉場效果。

<script setup lang="ts">
definePageMeta
({
  
pageTransition
: {
    
name
: 'bounce',
    
mode
: 'out-in' // default
  }
})
</script>

停用轉場效果

可以為特定路由停用 pageTransition 和 layoutTransition

<script setup lang="ts">
definePageMeta
({
  
pageTransition
: false,
  
layoutTransition
: false
})
</script>

或在 nuxt.config 中全域停用

export default 
defineNuxtConfig
({
  
app
: {
    
pageTransition
: false,
    
layoutTransition
: false
  }
})

JavaScript Hooks

對於進階使用案例，您可以使用 JavaScript hooks 為您的 Nuxt 頁面建立高度動態和自訂的轉場效果。

這種方式為 JavaScript 動畫函式庫（例如 GSAP）提供了完美的使用案例。

<script setup lang="ts">
definePageMeta
({
  
pageTransition
: {
    
name
: 'custom-flip',
    
mode
: 'out-in',
    
onBeforeEnter
: (
el
) => {
      
console
.
log
('Before enter...')
    },
    
onEnter
: (
el
, 
done
) => {},
    
onAfterEnter
: (
el
) => {}
  }
})
</script>

動態轉場效果

若要使用條件邏輯應用動態轉場效果，您可以利用內聯中介層將不同的轉場效果名稱指派給 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 prop 設定轉場效果，以全域啟用轉場效果。

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

View Transitions API (實驗性功能)

Nuxt 隨附 View Transitions API 的實驗性實作（請參閱 MDN）。這是一種令人興奮的新方法，可實作原生瀏覽器轉場效果，此轉場效果（除其他外）能夠在不同頁面上不相關的元素之間進行轉場。

您可以在 https://nuxt-view-transitions.surge.sh 上查看示範，並在 StackBlitz 上查看原始碼。

Nuxt 整合正在積極開發中，但可以使用您設定檔中的 experimental.viewTransition 選項啟用

export default 
defineNuxtConfig
({
  
experimental
: {
    
viewTransition
: true
  }
})

可能的值為：false、true 或 'always'。

如果設定為 true，如果使用者的瀏覽器符合 prefers-reduced-motion: reduce（建議），Nuxt 將不會應用轉場效果。如果設定為 always，Nuxt 將始終應用轉場效果，並且由您來尊重使用者的偏好設定。

依預設，檢視轉場效果會針對所有頁面啟用，但您可以設定不同的全域預設值。

export default 
defineNuxtConfig
({
  
app
: {
    // Disable view transitions globally, and opt-in on a per page basis
    
viewTransition
: false
  },
})

可以藉由在頁面的definePageMeta 中設定 viewTransition 鍵，來覆寫頁面的預設 viewTransition 值

<script setup lang="ts">
definePageMeta
({
  
viewTransition
: false
})
</script>

如果您也使用 Vue 轉場效果（例如 pageTransition 和 layoutTransition）（請參閱上方）來達到與新的 View Transitions 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
})

已知問題

• 如果您在頁面設定函式中執行資料獲取，您可能需要重新考慮目前是否使用此功能。（依照設計，View Transitions 會在執行期間完全凍結 DOM 更新。）我們正在研究將 View Transition 限制在 <Suspense> 解析前的最後時刻，但在這段期間，如果這描述了您，您可能需要仔細考慮是否採用此功能。