definePageMeta

definePageMeta — компиляторный макрос для задания метаданных страничных компонентов из app/pages/ (если путь не переопределён). Позволяет задать метаданные для каждого статического или динамического маршрута.

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

Тип

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> /* or the selected layout's props */ }
  middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
  scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
  [key: string]: unknown
}

Параметры

meta

• Тип: PageMeta
  Объект с метаданными страницы:
  name
  • Тип: string Имя маршрута страницы. По умолчанию генерируется по пути в app/pages/.
  
  path
  • Тип: stringСвоё регулярное выражение для маршрута, если имени файла недостаточно.
  
  props
  • Тип: RouteRecordRaw['props'] Передавать params маршрута как пропсы в страничный компонент.
  
  alias
  • Тип: string | string[] Псевдонимы маршрута — дополнительные пути, ведущие на ту же страницу (например /users/:id и /u/:id). Параметры у alias и path должны совпадать.
  
  groups
  • Тип: string[] Группы маршрутов по структуре папок. Заполняется автоматически для route groups.
  
  keepalive
  • Тип: boolean | KeepAlivePropstrue — сохранять состояние страницы при смене маршрута; объект — тонкая настройка KeepAlive.
  
  key
  • Тип: false | string | ((route) => string) Ключ для управления перерисовкой <NuxtPage>.
  
  layout
  • Тип: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey> | { name?: LayoutKey | false; props?: Record<string, unknown> }
    Имя макета для маршрута (статическое или реактивное). false — отключить макет по умолчанию. Можно передать объект с полями name и props, чтобы передать типизированные пропсы в компонент лейаута. При определении пропсов в лейауте через defineProps они будут полностью типизированы в definePageMeta.
  
  layoutTransition
  • Тип: boolean | TransitionProps Имя перехода для смены макета. false — отключить переход.
  
  middleware
  • Тип: MiddlewareKey | NavigationGuard | массив Middleware для страницы (анонимный или по имени). Подробнее: маршрутный middleware.
  
  pageTransition
  • Тип: boolean | TransitionProps Имя перехода для страницы. false — отключить.
  
  viewTransition
  • Тип: boolean | 'always' | ViewTransitionPageOptionsЭкспериментально, нужно включить в nuxt.config. Включить/выключить View Transitions для страницы. true — не применять при prefers-reduced-motion: reduce. 'always' — применять всегда.
    Можно передать объект ViewTransitionPageOptions для настройки типов view transition:
    • enabled: boolean | 'always' — включить/выключить переход
    • types: string[] | (to, from) => string[] — типы для любого перехода с этой страницей
    • toTypes: string[] | (to, from) => string[] — типы только при переходе на эту страницу
    • fromTypes: string[] | (to, from) => string[] — типы только при переходе с этой страницы
  
  redirect
  • Тип: RouteRecordRedirectOption Куда редиректить при прямом совпадении маршрута. Редирект выполняется до навигационных охранников.
  
  validate
  • Тип: (route) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>> Проверка, можно ли отобразить маршрут этой страницей. true — да, false — нет (при отсутствии других совпадений — 404). Можно вернуть объект с status/statusText для немедленной ошибки.
  
  scrollToTop
  • Тип: boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean
    Tell Nuxt to scroll to the top before rendering the page or not. Navigation is independent from rendering, so scroll behavior is always triggered even when the page doesn't re-render (e.g. when using a fixed key). Set scrollToTop: false to disable scrolling in such cases. If you want to overwrite the default scroll behavior of Nuxt, you can do so in ~/router.options.ts (see custom routing) for more info.
  
  [key: string]
  • Тип: any Произвольные метаданные. Типы можно расширить через augmentation.

Примеры

Базовое использование

В примере:

• key задаётся функцией;
• keepalive исключает компонент <modal> из кэша при переключении;
• добавлено кастомное свойство pageType:

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

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

  pageType: 'Checkout',
})
</script>

Определение middleware

Middleware можно задать функцией прямо в definePageMeta или строкой — именем файла из app/middleware/:

<script setup lang="ts">
definePageMeta({
  // middleware как функция
  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, задайте path:

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

Подробнее: синтаксис совпадения маршрутов Vue Router.

Выбор макета

Имя макета должно совпадать с именем файла в app/layouts/. Чтобы отключить макет по умолчанию, задайте layout: false:

<script setup lang="ts">
definePageMeta({
  layout: 'admin',

  // отключить макет по умолчанию
  layout: false,
})
</script>

Передача пропсов в лейаут

Пропсы в лейаут можно передать через объектный синтаксис опции layout. Если в лейауте пропсы объявлены через defineProps, они будут полностью типизированы.

<script setup lang="ts">
definePageMeta({
  layout: {
    name: 'panel',
    props: {
      sidebar: true,
      title: 'Dashboard',
    },
  },
})
</script>

<script setup lang="ts">
const props = defineProps<{
  sidebar?: boolean
  title?: string
}>()
</script>

<template>
  <div>
    <aside v-if="sidebar">
      Sidebar
    </aside>
    <main>
      <h1>{{ title }}</h1>
      <slot />
    </main>
  </div>
</template>