definePageMeta

definePageMeta 是一個編譯器巨集，您可以使用它來為位於 pages/ 目錄中的**頁面**元件設定元數據（除非 另有設定）。這樣您就可以為 Nuxt 應用程式的每個靜態或動態路由設定自訂元數據。

<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
  一個接受以下頁面元數據的物件
  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 檔案中啟用 時才可用
    為目前頁面啟用/停用 View Transitions。如果設定為 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
    除了上述屬性之外，您還可以設定自訂中繼資料。您可能希望透過擴充 meta 物件的類型 來以類型安全的方式執行此操作。

範例

基本用法

以下範例示範

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

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

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

  pageType: 'Checkout'
})
</script>

定義中介層

以下範例顯示如何直接在 definePageMeta 中使用 function 定義中介層，或將其設定為與位於 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>