definePageMeta

definePageMeta 是一个编译器宏，你可以使用它来设置位于 pages/ 目录中的页面组件的元数据（除非是 否则设置）。这样，你可以为 Nuxt 应用的每个静态或动态路由设置自定义元数据。

¥definePageMeta is a compiler macro that you can use to set metadata for your page components located in the pages/ directory (unless set otherwise). This way you can set custom metadata for each static or dynamic route of your Nuxt application.

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

类型

¥Type

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
}

参数

¥Parameters

meta

• 类型：PageMeta
  接受以下页面元数据的对象：
  name
  • 类型：string
    你可以为此页面的路由定义一个名称。默认情况下，名称是根据 pages/ 目录 中的路径生成的。
  
  path
  • 类型：string
    如果你的模式比文件名所能表达的更复杂，你可以定义一个 自定义正则表达式。
  
  props
  • 类型：RouteRecordRaw['props']
    允许将路由 params 作为传递给页面组件的 props 进行访问。
  
  alias
  • 类型：string | string[]
    记录的别名。允许定义额外的路径，使其行为类似于记录的副本。允许使用路径简写，例如 /users/:id 和 /u/:id。所有 alias 和 path 值必须共享相同的参数。
  
  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 的默认滚动行为，你可以在 ~/app/router.options.ts 中进行（参见 自定义路由）了解更多信息。
  
  [key: string]
  • 类型：any
    除了上述属性外，你还可以设置自定义元数据。你可能希望通过 扩充 meta 对象的类型 以类型安全的方式执行此操作。

示例

¥Examples

基本用法

¥Basic Usage

以下示例演示了：

¥The example below demonstrates:

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

<script setup lang="ts">
definePageMeta({
  key: (route) => route.fullPath,

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

  pageType: 'Checkout'
})
</script>

定义中间件

¥Defining Middleware

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

¥The example below shows how the middleware can be defined using a function directly within the definePageMeta or set as a string that matches the middleware file name located in the middleware/ directory:

<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>

使用自定义正则表达式

¥Using a Custom Regular Expression

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

¥A custom regular expression is a good way to resolve conflicts between overlapping routes, for instance:

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

¥The two routes "/test-category" and "/1234-post" match both [postId]-[postSlug].vue and [categorySlug].vue page routes.

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

¥To make sure that we are only matching digits (\d+) for postId in the [postId]-[postSlug] route, we can add the following to the [postId]-[postSlug].vue page template:

<script setup lang="ts">
definePageMeta({
  path: '/:postId(\\d+)-:postSlug' 
})
</script>

更多 Vue Router 的匹配语法 功能信息，请查看 。

¥For more examples see Vue Router's Matching Syntax.

定义布局

¥Defining Layout

你可以定义与 layouts/ 目录 中（默认情况下）布局文件名匹配的布局。你还可以通过将 layout 设置为 false 来禁用布局：

¥You can define the layout that matches the layout's file name located (by default) in the layouts/ directory. You can also disable the layout by setting the layout to false:

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

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