---
title: "definePageMeta"
description: "为页面组件定义元数据。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/api/utils/define-page-meta"
---
# definePageMeta

> 为页面组件定义元数据。

`definePageMeta` 是一个编译器宏，你可以使用它为位于 [`app/pages/`](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages) 目录中的**页面**组件设置元数据（除非[另有设置](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#pages)）。这样，你就可以为 Nuxt 应用中的每个静态或动态路由设置自定义元数据。

```vue [app/pages/some-page.vue]
<script setup lang="ts">
definePageMeta({
  layout: 'default',
})
</script>
```

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages#page-metadata"}
::

## 类型

```ts [Signature]
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?: ViewTransitionPageOptions['enabled'] | ViewTransitionPageOptions
  key?: false | string | ((route: RouteLocationNormalizedLoaded) => string)
  keepalive?: boolean | KeepAliveProps
  layout?: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey> | { name?: LayoutKey | false, props?: Record<string, unknown> /* 或所选布局的 props */ }
  middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
  scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
  [key: string]: unknown
}
```

## 参数

### `meta`

- **类型**: `PageMeta`

  一个接受以下页面元数据的对象：

  **`name`**

  - **类型**: `string`

    你可以为此页面的路由定义名称。默认情况下，名称根据 [`app/pages/` 目录](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages)中的路径生成。

  **`path`**

  - **类型**: `string`

    如果文件名无法表达更复杂的模式，你可以定义一个[自定义正则表达式](https://nuxt.zhcndoc.com/docs/4.x/api/utils/define-page-meta#using-a-custom-regular-expression)。

  **`props`**

  - **类型**: [`RouteRecordRaw['props']`](https://router.vuejs.org/guide/essentials/passing-props)

    允许将路由的 `params` 作为 props 传入页面组件。

  **`alias`**

  - **类型**: `string | string[]`

    记录的别名。允许定义额外的路径，使其行为像记录的副本。可以使用路径简写例如 `/users/:id` 和 `/u/:id`。所有 `alias` 和 `path` 值必须共享相同的参数。

  **`groups`** :badge[v4.3]{color="info" size="xs" .align-middle}

  - **类型**: `string[]`

    页面所属的路由组，根据文件夹结构确定。对于[路由组](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages#route-groups)中的页面，会自动填充此属性。

  **`keepalive`**

  - **类型**: `boolean` | [`KeepAliveProps`](https://vue.zhcndoc.com/api/built-in-components#keepalive)

    当你希望在路由切换时保留页面状态时设置为 `true`，或者使用 [`KeepAliveProps`](https://vue.zhcndoc.com/api/built-in-components#keepalive) 进行更细粒度的控制。

  **`key`**

  - **类型**: `false` | `string` | `((route: RouteLocationNormalizedLoaded) => string)`

    当你需要更精细地控制 `<NuxtPage>` 组件何时重新渲染时，设置 `key` 值。

  **`layout`**

  - **Type**: `false` | `LayoutKey` | `Ref<LayoutKey>` | `ComputedRef<LayoutKey>` | `{ name?: LayoutKey | false; props?: Record<string, unknown> /* or the selected layout's props */ }`

    为每个路由设置静态或动态的布局名称。如果需要禁用默认布局，可将其设置为 `false`。

    你也可以传入一个带有 `name` 和 `props` 的对象，以便向你的布局组件传递已类型化的 props。当你的布局使用 `defineProps` 定义了 props 时，这些 props 会在 `definePageMeta` 中得到完整的类型支持。

  **`layoutTransition`**

  - **类型**: `boolean` | [`TransitionProps`](https://vue.zhcndoc.com/api/built-in-components#transition)

    为当前布局设置要应用的过渡。你也可以将此值设置为 `false` 以禁用布局过渡。

  **`middleware`**

  - **类型**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/navigationguard) | `Array<MiddlewareKey | NavigationGuard>`

    直接在 `definePageMeta` 中定义匿名或命名中间件。了解更多信息，请参阅[路由中间件](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/middleware)。

  **`pageTransition`**

  - **类型**: `boolean` | [`TransitionProps`](https://vue.zhcndoc.com/api/built-in-components#transition)

    为当前页面设置要应用的过渡。你也可以将此值设置为 `false` 以禁用页面过渡。

  **`viewTransition`**

  - **类型**: `boolean | 'always' | ViewTransitionPageOptions`

    **实验性功能，仅在[nuxt.config 文件中启用后](https://nuxt.zhcndoc.com/docs/4.x/getting-started/transitions#view-transitions-api-experimental)可用**<br>为当前页面启用或禁用 View Transitions。
    如果设置为 true，当用户的浏览器匹配 `prefers-reduced-motion: reduce` 时，Nuxt 不会应用过渡（推荐）。如果设置为 `always`，Nuxt 将始终应用过渡。

    你也可以传入 `ViewTransitionPageOptions` 对象来配置[视图过渡类型](https://nuxt.zhcndoc.com/docs/4.x/getting-started/transitions#view-transition-types)：

    - `enabled`：`boolean | 'always'` - 启用或禁用过渡
    - `types`：`string[] | (to, from) => string[]` - 应用于任何涉及此页面的过渡的类型
    - `toTypes`：`string[] | (to, from) => string[]` - 仅在导航**到**此页面时应用的类型
    - `fromTypes`：`string[] | (to, from) => string[]` - 仅在从此页面导航**到其他页面**时应用的类型

  **`redirect`**

  - **类型**: [`RouteRecordRedirectOption`](https://router.vuejs.org/guide/essentials/redirect-and-alias)

    如果路由被直接匹配时要重定向到的位置。重定向会在任何导航守卫之前发生，并使用新的目标位置触发一次新的导航。

  **`validate`**

  - **类型**: `(route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>`

    验证给定路由是否可以用此页面有效地渲染。如果有效返回 true，否则返回 false。如果找不到其他匹配，则表示 404。你也可以直接返回带有 `statusCode`/`statusMessage` 的对象以立即返回错误（不会检查其他匹配）。

  **`scrollToTop`**

  - **类型**: `boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean`

    告知 Nuxt 是否在渲染页面之前滚动到顶部。导航与渲染相互独立，因此即使页面不会重新渲染（例如使用固定的 [`key`](https://nuxt.zhcndoc.com/docs/4.x/api/utils/define-page-meta#key) 时），滚动行为也始终会触发。在这种情况下，设置 `scrollToTop: false` 可禁用滚动。如果你想覆盖 Nuxt 的默认滚动行为，可以在 `~/router.options.ts` 中进行设置（更多信息请参阅[自定义路由](https://nuxt.zhcndoc.com/docs/4.x/guide/recipes/custom-routing#using-routeroptions)）。

  **`[key: string]`**

  - **类型**: `any`

    除了上述属性，你还可以设置**自定义**元数据。你可以通过[扩展 `meta` 对象的类型](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/pages/#typing-custom-metadata)来确保类型安全。

## 示例

### 基本用法

下面的示例演示了：

- `key` 如何可以是一个返回值的函数；
- `keepalive` 属性如何确保在多个组件之间切换时 `<modal>` 组件不会被缓存；
- 添加 `pageType` 作为自定义属性：

```vue [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`：

```vue [app/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>
```

### 使用自定义正则表达式

当路由重叠时，自定义正则表达式是解决冲突的一个好方法，例如：

两个路由 "/test-category" 和 "/1234-post" 都同时匹配 `[postId]-[postSlug].vue` 和 `[categorySlug].vue` 页面路由。

为确保在 `[postId]-[postSlug]` 路由中我们只匹配数字（`\d+`）作为 `postId`，可以在 `[postId]-[postSlug].vue` 页面模板中添加如下内容：

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

更多示例请参阅 [Vue Router 的匹配语法](https://router.vuejs.org/guide/essentials/route-matching-syntax)。

### 定义布局

你可以定义一个与（默认情况下）位于 [`app/layouts/` 目录](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/layouts)中的布局文件名相匹配的布局。你也可以将 `layout` 设置为 `false` 来禁用布局：

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

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

### 向布局传递 Props

你可以通过使用 `layout` 的对象语法来向布局传递 props。如果你的布局使用 `defineProps` 定义了 props，那么这些 props 将会被完全类型推断。

::code-group
```vue [app/pages/dashboard.vue]
<script setup lang="ts">
definePageMeta({
  layout: {
    name: 'panel',
    props: {
      sidebar: true,
      title: 'Dashboard',
    },
  },
})
</script>
```

```vue [app/layouts/panel.vue]
<script setup lang="ts">
const props = defineProps<{
  sidebar?: boolean
  title?: string
}>()
</script>

<template>
  <div>
    <aside v-if="sidebar">
      侧边栏
    </aside>
    <main>
      <h1>{{ title }}</h1>
      <slot />
    </main>
  </div>
</template>
```
::

::tip
通过 `definePageMeta` 设置的布局 props 会基于布局的 `defineProps` 得到完整类型支持。你将在编辑器中获得自动补全和类型检查。
::

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/layouts#passing-props-to-layouts"}
::

---

- [Source](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/pages/runtime/composables.ts)


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.