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?: 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
  • Тип: string
    Своё регулярное выражение для маршрута, если имени файла недостаточно.
  
  props
  • Тип: RouteRecordRaw['props']
    Передавать params маршрута как пропсы в страничный компонент.
  
  alias
  • Тип: string | string[]
    Псевдонимы маршрута — дополнительные пути, ведущие на ту же страницу (например /users/:id и /u/:id). Параметры у alias и path должны совпадать.
  
  groups
  • Тип: string[]
    Группы маршрутов по структуре папок. Заполняется автоматически для route groups.
  
  keepalive
  • Тип: boolean | KeepAliveProps
true — сохранять состояние страницы при смене маршрута; объект — тонкая настройка KeepAlive.
  
  key
  • Тип: false | string | ((route) => string)
    Ключ для управления перерисовкой <NuxtPage>.
  
  layout
  • Тип: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey>
    Имя макета для маршрута (статическое или реактивное). false — отключить макет по умолчанию.
  
  layoutTransition
  • Тип: boolean | TransitionProps
    Имя перехода для смены макета. false — отключить переход.
  
  middleware
  • Тип: MiddlewareKey | NavigationGuard | массив
    Middleware для страницы (анонимный или по имени). Подробнее: маршрутный middleware.
  
  pageTransition
  • Тип: boolean | TransitionProps
    Имя перехода для страницы. false — отключить.
  
  viewTransition
  • Тип: boolean | 'always'
    Экспериментально, нужно включить в nuxt.config.
    Включить/выключить View Transitions для страницы. true — не применять при prefers-reduced-motion: reduce. 'always' — применять всегда.
  
  redirect
  • Тип: RouteRecordRedirectOption
    Куда редиректить при прямом совпадении маршрута. Редирект выполняется до навигационных охранников.
  
  validate
  • Тип: (route) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>
    Проверка, можно ли отобразить маршрут этой страницей. true — да, false — нет (при отсутствии других совпадений — 404). Можно вернуть объект с status/statusText для немедленной ошибки.
  
  scrollToTop
  • Тип: boolean | (to, from) => boolean
    Прокручивать ли вверх перед отображением страницы. Глобальное поведение можно переопределить в ~/router.options.ts (кастомный роутинг).
  
  [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>