Nuxt3 中文课程《实战全栈开发简书》限时优惠

definePageMeta

为你的页面组件定义元数据。

definePageMeta是一个编译器宏,你可以用它为位于pages/目录中的页面组件设置元数据(除非另有设置)。通过这种方式,你可以为Nuxt应用程序的每个静态或动态路由设置自定义元数据。

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  layout: 'default'
})
</script>
Read more in Docs > Guide > Directory Structure > Pages > #page Metadata.

类型

definePageMeta(meta: PageMeta) => void

interface PageMeta {
  validate?: (route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>
  redirect?: RouteRecordRedirectOption
  name?: string
  path?: string
  alias?: string | string[]
  pageTransition?: boolean | TransitionProps
  layoutTransition?: boolean | TransitionProps
  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
      如果你有一个比文件名更复杂的模式,你可以定义一个路径匹配器。

    alias
    • 类型string | string[]
      记录的别名。允许定义额外的路径,这些路径将像记录的副本一样工作。允许使用类似/users/:id/u/:id的路径简写。所有的aliaspath值必须共享相同的参数。

    keepalive
    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以禁用页面过渡。

    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作为自定义属性:
pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  key: (route) => route.fullPath,

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

  pageType: 'Checkout'
})
</script>

定义中间件

下面的示例展示了如何直接在definePageMeta内使用function定义中间件,或将其设置为与位于middleware/目录中的中间件文件名相匹配的string

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  // 将中间件定义为函数
  middleware: [
    function (to, from) {
      const auth = useState('auth')

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

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

  // ... 或者设置为字符串
  middleware: 'auth'

  // ... 或者设置为多个字符串
  middleware: ['auth', 'another-named-middleware']
})
</script>

定义布局

你可以定义与布局文件名相匹配的布局(默认情况下位于layouts/目录)。你也可以通过将layout设置为false来禁用布局:

pages/some-page.vue
<script setup lang="ts">
definePageMeta({
  // 设置自定义布局
  layout: 'admin'

  // ... 或者禁用默认布局
  layout: false
})
</script>