definePageMeta

definePageMeta 是一個編譯器巨集，您可以使用它為位於 pages/ 目錄中的頁面組件設定 metadata（除非 另有設定）。透過這種方式，您可以為 Nuxt 應用程式的每個靜態或動態路由設定自訂 metadata。

<script setup lang="ts">
definePageMeta({
  layout: 'default'
})
</script>

類型

definePageMeta(meta: PageMeta) => void

interface PageMeta {
  validate?: (route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>
  redirect?: RouteRecordRedirectOption
  name?: string
  path?: string
  props?: RouteRecordRaw['props']
  alias?: string | string[]
  pageTransition?: boolean | TransitionProps
  layoutTransition?: boolean | TransitionProps
  viewTransition?: boolean | 'always'
  key?: false | string | ((route: RouteLocationNormalizedLoaded) => string)
  keepalive?: boolean | KeepAliveProps
  layout?: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey>
  middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
  scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
  [key: string]: unknown
}

參數

meta

• 類型: PageMeta
  一個接受以下頁面 metadata 的物件
  name
  • 類型: string
    您可以為此頁面的路由定義名稱。預設情況下，名稱是根據 pages/ 目錄中的路徑產生的。
  
  path
  • 類型: string
    如果您有比檔案名稱更複雜的模式，您可以定義自訂正規表示式。
  
  props
  • 類型: RouteRecordRaw['props']
    允許將路由 params 作為 props 傳遞到頁面組件。
  
  alias
  • 類型: string | string[]
    記錄的別名。允許定義額外的路徑，這些路徑的行為將類似於記錄的副本。允許使用路徑簡寫，例如 /users/:id 和 /u/:id。所有 alias 和 path 值都必須共用相同的參數。
  
  keepalive
  • 類型: boolean | KeepAliveProps
    當您想要在路由變更之間保留頁面狀態時，或使用 KeepAliveProps 進行細緻的控制時，設定為 true。
  
  key
  • 類型: false | string | ((route: RouteLocationNormalizedLoaded) => string)
    當您需要更多控制 <NuxtPage> 組件何時重新渲染時，設定 key 值。
  
  layout
  • 類型: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey>
    為每個路由設定佈局的靜態或動態名稱。如果需要停用預設佈局，則可以將其設定為 false。
  
  layoutTransition
  • 類型: boolean | TransitionProps
    設定要應用於目前佈局的轉場名稱。您也可以將此值設定為 false 以停用佈局轉場。
  
  middleware
  • 類型: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
    直接在 definePageMeta 中定義匿名或具名中介層。瞭解更多關於路由中介層的資訊。
  
  pageTransition
  • 類型: boolean | TransitionProps
    設定要應用於目前頁面的轉場名稱。您也可以將此值設定為 false 以停用頁面轉場。
  
  viewTransition
  • 類型: boolean | 'always'
    實驗性功能，僅在 在您的 nuxt.config 檔案中啟用時才可用
    啟用/停用目前頁面的檢視轉場。如果設定為 true，如果使用者的瀏覽器符合 prefers-reduced-motion: reduce（建議），Nuxt 將不會應用轉場。如果設定為 always，Nuxt 將始終應用轉場。
  
  redirect
  • 類型: RouteRecordRedirectOption
    如果路由直接匹配，則重新導向到何處。重新導向發生在任何導航守衛之前，並使用新的目標位置觸發新的導航。
  
  validate
  • 類型: (route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>
    驗證給定的路由是否可以有效地使用此頁面進行渲染。如果有效，則傳回 true，如果無效，則傳回 false。如果找不到其他匹配項，則這表示 404。您也可以直接傳回具有 statusCode/statusMessage 的物件，以立即回應錯誤（不會檢查其他匹配項）。
  
  scrollToTop
  • 類型: boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean
    告訴 Nuxt 在渲染頁面之前是否捲動到頂部。如果您想覆寫 Nuxt 的預設捲動行為，您可以在 ~/app/router.options.ts 中執行此操作（請參閱自訂路由）以獲取更多資訊。
  
  [key: string]
  • 類型: any
    除了上述屬性之外，您還可以設定自訂 metadata。您可能希望透過擴增 meta 物件的類型以類型安全的方式執行此操作。

範例

基本用法

以下範例示範

• key 如何成為傳回值的函式；
• keepalive 屬性如何確保在多個組件之間切換時，<modal> 組件不會被快取；
• 新增 pageType 作為自訂屬性

<script setup lang="ts">
definePageMeta({
  key: (route) => route.fullPath,

  keepalive: {
    exclude: ['modal']
  },

  pageType: 'Checkout'
})
</script>

定義中介層

以下範例示範如何使用 function 直接在 definePageMeta 中定義中介層，或設定為與位於 middleware/ 目錄中的中介層檔案名稱相符的 string

<script setup lang="ts">
definePageMeta({
  // define middleware as a function
  middleware: [
    function (to, from) {
      const auth = useState('auth')

      if (!auth.value.authenticated) {
          return navigateTo('/login')
      }

      if (to.path !== '/checkout') {
        return navigateTo('/checkout')
      }
    }
  ],

  // ... or a string
  middleware: 'auth'

  // ... or multiple strings
  middleware: ['auth', 'another-named-middleware']
})
</script>

使用自訂正規表示式

自訂正規表示式是解決重疊路由之間衝突的好方法，例如

路由 "/test-category" 和 "/1234-post" 都與 [postId]-[postSlug].vue 和 [categorySlug].vue 頁面路由匹配。

為了確保我們僅為 [postId]-[postSlug] 路由中的 postId 匹配數字 (\d+)，我們可以將以下內容新增到 [postId]-[postSlug].vue 頁面範本

<script setup lang="ts">
definePageMeta({
  path: '/:postId(\\d+)-:postSlug' 
})
</script>

有關更多範例，請參閱 Vue Router 的匹配語法。

定義佈局

您可以定義與佈局檔案名稱匹配的佈局，該檔案名稱（預設情況下）位於 layouts/ 目錄中。您也可以透過將 layout 設定為 false 來停用佈局

<script setup lang="ts">
definePageMeta({
  // set custom layout
  layout: 'admin'

  // ... or disable a default layout
  layout: false
})
</script>