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>