definePageMeta

原始檔
為頁面元件定義元資料。

definePageMeta 是一個編譯器宏，您可以使用它來為位於 app/pages/ 目錄中的頁面元件設定元資料（除非另行設定）。透過這種方式，您可以為 Nuxt 應用程式的每個靜態或動態路由設定自定義元資料。

app/pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  layout: 'default',
})
</script>
在文件 > 4 X > 指南 > 目錄結構 > App > Pages#page Metadata中閱讀更多內容。

型別

簽名
export function 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
      您可以為此頁面的路由定義一個名稱。預設情況下，名稱是根據 app/pages/ 目錄中的路徑生成的。

    path
    props
    alias
    • 型別：string | string[]
      記錄的別名。允許定義額外的路徑，這些路徑將表現得像記錄的副本。允許使用路徑簡寫，如 /users/:id 和 /u/:id。所有 alias 和 path 值必須共享相同的 params。

    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 的預設滾動行為，可以在 ~/router.options.ts 中進行（有關更多資訊，請參閱自定義路由）。

    [key: string]
    • 型別：any
      除了上述屬性，您還可以設定自定義元資料。您可能希望透過增強 meta 物件的型別來以型別安全的方式進行。

示例

基本用法

以下示例演示了

  • key 如何成為一個返回值的函式；
  • keepalive 屬性如何確保在多個元件之間切換時 <modal> 元件不被快取；
  • 新增 pageType 作為自定義屬性
app/pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,

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

  pageType: 'Checkout',
})
</script>

定義中介軟體

以下示例展示瞭如何在 definePageMeta 中直接使用 function 定義中介軟體，或將其設定為與 app/middleware/ 目錄中的中介軟體檔名匹配的 string

app/pages/some-page.vue
<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 頁面模板中新增以下內容

app/pages/[postId]-[postSlug].vue
<script setup lang="ts">
definePageMeta({
  path: '/:postId(\\d+)-:postSlug',
})
</script>

更多示例請參閱Vue Router 的匹配語法.

定義佈局

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

app/pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  // set custom layout
  layout: 'admin',

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