Страницы и макеты

app.vue

В Nuxt 3 единая точка входа приложения — ~/app.vue.

Сюда удобно выносить код, выполняемый один раз при старте, и компоненты, общие для всех страниц. Например, при одном лейауте его можно перенести в app.vue.

Миграция

Создайте app.vue и перенесите туда логику, которая должна выполняться один раз на верхнем уровне приложения. Пример: документация app.

Макеты (Layouts)

При использовании макетов для нескольких страниц изменения минимальны.

В Nuxt 2 в макете для отображения текущей страницы использовался <Nuxt>. В Nuxt 3 макеты используют слоты — замените его на <slot />. Это также даёт возможность использовать именованные и скоупированные слоты. Подробнее о макетах.

Макет страницы задаётся через макрос definePageMeta в kebab-case: app/layouts/customLayout.vue на странице указывается как custom-layout.

Миграция

1. Замените <Nuxt /> на <slot />
   app/layouts/custom.vue

     <template>
       <div id="app-layout">
         <main>
   -       <Nuxt />
   +       <slot />
         </main>
       </div>
     </template>
   

2. Используйте definePageMeta для выбора макета страницы.
   app/pages/index.vue

   + <script setup>
   + definePageMeta({
   +   layout: 'custom'
   + })
   - <script>
   - export default {
   -   layout: 'custom'
   - }
     </script>
   

3. Перенесите ~/layouts/_error.vue в ~/error.vue. См. обработку ошибок. Чтобы страница ошибки использовала макет, оберните содержимое в <NuxtLayout> внутри error.vue:
   error.vue

   <template>
     <div>
       <NuxtLayout name="default">
         <!-- -->
       </NuxtLayout>
     </div>
   </template>
   

Страницы

Интеграция vue-router в Nuxt 3 подключается при наличии каталога app/pages/. При одной странице можно перенести её в app.vue для более лёгкой сборки.

Динамические маршруты

Формат динамических маршрутов в Nuxt 3 отличается от Nuxt 2 — возможно, потребуется переименовать файлы в app/pages/.

1. Вместо _id для параметра маршрута используется [id].
2. Вместо _.vue для catch-all маршрута используется [...slug].vue.

Вложенные маршруты

В Nuxt 2 вложенные маршруты (родитель и дочерние компоненты) задавались через <Nuxt> и <NuxtChild>. В Nuxt 3 их заменяет один компонент <NuxtPage>.

Ключ страницы и пропсы keep-alive

Если вы передавали кастомный ключ страницы или пропсы keep-alive в <Nuxt>, теперь это задаётся через definePageMeta.

Переходы страниц и макетов

Переходы для страницы или макета задаются через definePageMeta. В Vue 3 переименованы CSS-классы -enter и -leave. Проп style у <Nuxt> для <slot> больше не влияет на переход — перенесите стили в класс -active.

Миграция

1. Переименуйте страницы с динамическими параметрами под новый формат.
2. Замените <Nuxt> и <NuxtChild> на <NuxtPage>.
3. При использовании Composition API замените this.$route и this.$router на композаблы useRoute и useRouter.

Пример: динамические маршруты

- URL: /users
- Page: /pages/users/index.vue

- URL: /users/some-user-name
- Page: /pages/users/_user.vue
- Usage: params.user

- URL: /users/some-user-name/edit
- Page: /pages/users/_user/edit.vue
- Usage: params.user

- URL: /users/anything-else
- Page: /pages/users/_.vue
- Usage: params.pathMatch

- URL: /users
- Page: /pages/users/index.vue

- URL: /users/some-user-name
- Page: /pages/users/[user].vue
- Usage: params.user

- URL: /users/some-user-name/edit
- Page: /pages/users/[user]/edit.vue
- Usage: params.user

- URL: /users/anything-else
- Page: /pages/users/[...slug].vue
- Usage: params.slug

Пример: вложенные маршруты и definePageMeta

<template>
  <div>
    <NuxtChild
      keep-alive
      :keep-alive-props="{ exclude: ['modal'] }"
      :nuxt-child-key="$route.slug"
    />
  </div>
</template>

<script>
export default {
  transition: 'page', // or { name: 'page' }
}
</script>

<template>
  <div>
    <NuxtPage />
  </div>
</template>

<script setup lang="ts">
// Макрос работает и в <script>, и в <script setup>
definePageMeta({
  // можно передать строку или computed
  key: route => route.slug,
  transition: {
    name: 'page',
  },
  keepalive: {
    exclude: ['modal'],
  },
})
</script>

Компонент <NuxtLink>

Синтаксис и поведение глобального NuxtLink в основном те же. Сокращение <NLink> замените на <NuxtLink>.

<NuxtLink> теперь подходит для всех ссылок, в том числе внешних. Подробнее о компоненте и расширении под свою ссылку — в документации.

Программная навигация

При переходе с Nuxt 2 на Nuxt 3 обновите вызовы навигации. В Nuxt 2 использовался this.$router. В Nuxt 3 — утилита navigateTo(), в которую передаётся маршрут и параметры для Vue Router.

<script>
export default {
  methods: {
    navigate () {
      this.$router.push({
        path: '/search',
        query: {
          name: 'first name',
          type: '1',
        },
      })
    },
  },
}
</script>

<script setup lang="ts">
function navigate () {
  return navigateTo({
    path: '/search',
    query: {
      name: 'first name',
      type: '1',
    },
  })
}
</script>