definePageMeta

definePageMeta 是一个编译宏，可用于设置位于 app/pages/ 目录中的**页面**组件的元数据（除非在 其他地方设置）。这样你就可以为 Nuxt 应用的每个静态或动态路由设置自定义元数据。

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

类型

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[]
  groups?: 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
  • 类型: string
    如果你有一个比文件名所能表达的更复杂的模式，你可以定义一个自定义正则表达式。
  
  props
  • 类型: RouteRecordRaw['props']
    允许将路由 params 作为 props 传递给页面组件。
  
  alias
  • 类型: string | string[]
    记录的别名。允许定义额外的路径，这些路径的行为就像记录的副本。允许拥有路径简写，如 /users/:id 和 /u/:id。所有 alias 和 path 值必须共享相同的 params。
  
  groups
  • 类型: string[]
    页面所属的路由组，基于文件夹结构。对于 路由组中的页面，会自动填充。
  
  keepalive
  • 类型: boolean |KeepAliveProps
    设置为 true 时，你希望在路由更改时保留页面状态或使用KeepAliveProps以进行细粒度控制。
  
  key
  • 类型: false | string | ((route: RouteLocationNormalized) => string)
    设置 key 值，以便在重新渲染 <NuxtPage> 组件时进行更精细的控制。
  
  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。你也可以直接返回一个带有 status/statusText 的对象，立即以错误响应（将不检查其他匹配项）。
  
  scrollToTop
  • 类型: boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean
    告诉 Nuxt 在渲染页面之前是否滚动到顶部。如果你想覆盖 Nuxt 的默认滚动行为，可以在 ~/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 或将其设置为与位于 app/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 的匹配语法.

定义布局

你可以定义与（默认位于 app/layouts/ 目录中）布局文件名称匹配的布局。你也可以通过将 layout 设置为 false 来禁用布局

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

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