definePageMeta
为你的页面组件定义元数据。
definePageMeta
是一个编译器宏,你可以用它为位于 pages/
目录下的页面组件设置元数据(除非另有设置)。这样你可以为 Nuxt 应用的每个静态或动态路由设置自定义元数据。
pages/some-page.vue
<script setup lang="ts">
definePageMeta({
layout: 'default'
})
</script>
类型
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
你可以为该页面的路由定义一个名称。默认情况下,名称是根据pages/
目录中的路径生成的。
path
- 类型:
string
如果你的匹配模式比文件名可以表达的更复杂,可以定义一个自定义正则表达式。
props
- 类型:
RouteRecordRaw['props']
允许作为 prop 将路由的params
传递给页面组件。
alias
- 类型:
string | string[]
路由别名。允许定义额外路径,使其行为与该路由的副本一致。支持路径简写,如/users/:id
和/u/:id
。所有的alias
和path
必须共享相同的参数。
keepalive
- 类型:
boolean
|KeepAliveProps
当你希望在路由切换时保留页面状态时设置为true
,或者使用KeepAliveProps
进行细粒度控制。
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
对象类型 以类型安全的方式实现。
- 类型:
示例
基础用法
下面示例演示:
- 如何将
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/
目录中文件名的字符串:
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]
路由中的 postId
只匹配数字(\d+
),我们可以在 [postId]-[postSlug].vue
页面模板添加如下内容:
pages/[postId]-[postSlug].vue
<script setup lang="ts">
definePageMeta({
path: '/:postId(\\d+)-:postSlug'
})
</script>
更多示例请参见 Vue Router 的匹配语法。
定义布局
你可以定义匹配布局文件名的布局(默认位于layouts/
目录)。你也可以通过将 layout
设置为 false
来禁用布局:
pages/some-page.vue
<script setup lang="ts">
definePageMeta({
// 设置自定义布局
layout: 'admin'
// ... 或禁用默认布局
layout: false
})
</script>