Переходы

Применение переходов между страницами и макетами с помощью Vue или нативного View Transitions API браузера.

Nuxt использует компонент Vue <Transition> для переходов между страницами и макетами.

Переходы между страницами

Переходы страниц включаются для всех страниц:

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    pageTransition: { name: 'page', mode: 'out-in' },
  },
})

Если меняется и макет, и страница, заданный здесь переход страницы не сработает. В этом случае настройте переход макета.

Добавьте следующий CSS в app.vue:

<template>
  <NuxtPage />
</template>

<style>
.page-enter-active,
.page-leave-active {
  transition: all 0.4s;
}
.page-enter-from,
.page-leave-to {
  opacity: 0;
  filter: blur(1rem);
}
</style>

<template>
  <div>
    <h1>Главная</h1>
    <NuxtLink to="/about">О нас</NuxtLink>
  </div>
</template>

<template>
  <div>
    <h1>О нас</h1>
    <NuxtLink to="/">Главная</NuxtLink>
  </div>
</template>

При навигации между страницами получится такой результат:

Для отдельной страницы другой переход задаётся ключом pageTransition в definePageMeta:

<script setup lang="ts">
definePageMeta
({
  pageTransition
: {
    name
: 'rotate',
  },
})
</script>

<template>
  <NuxtPage />
</template>

<style>
/* ... */
.rotate-enter-active,
.rotate-leave-active {
  transition: all 0.4s;
}
.rotate-enter-from,
.rotate-leave-to {
  opacity: 0;
  transform: rotate3d(1, 1, 1, 15deg);
}
</style>

На странице About будет эффект 3D-поворота:

Переходы макетов

Переходы макетов включаются для всех макетов:

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    layoutTransition: { name: 'layout', mode: 'out-in' },
  },
})

Добавьте следующий CSS в app.vue:

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

<style>
.layout-enter-active,
.layout-leave-active {
  transition: all 0.4s;
}
.layout-enter-from,
.layout-leave-to {
  filter: grayscale(1);
}
</style>

<template>
  <div>
    <pre>default layout</pre>
    <slot />
  </div>
</template>

<style scoped>
div {
  background-color: lightgreen;
}
</style>

<template>
  <div>
    <pre>orange layout</pre>
    <slot />
  </div>
</template>

<style scoped>
div {
  background-color: #eebb90;
  padding: 20px;
  height: 100vh;
}
</style>

<template>
  <div>
    <h1>Главная</h1>
    <NuxtLink to="/about">О нас</NuxtLink>
  </div>
</template>

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

<template>
  <div>
    <h1>О нас</h1>
    <NuxtLink to="/">Главная</NuxtLink>
  </div>
</template>

Результат при навигации:

Как и для pageTransition, свой переход макета задаётся в definePageMeta через layoutTransition:

pages/about.vue

<script setup lang="ts">
definePageMeta
({
  layout
: 'orange',
  layoutTransition
: {
    name
: 'slide-in',
  },
})
</script>

Глобальные настройки

Имена переходов по умолчанию настраиваются в nuxt.config.

Ключи pageTransition и layoutTransition принимают значения в формате TransitionProps (JSON-serializable): name, mode и другие опции перехода.

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    pageTransition: {
      name: 'fade',
      mode: 'out-in', // по умолчанию
    },
    layoutTransition: {
      name: 'slide',
      mode: 'out-in', // по умолчанию
    },
  },
})

При смене свойства name переименуйте соответствующие CSS-классы.

Чтобы переопределить глобальный переход для одной страницы, используйте definePageMeta — это перезапишет настройки из nuxt.config.

pages/some-page.vue

<script setup lang="ts">
definePageMeta
({
  pageTransition
: {
    name
: 'bounce',
    mode
: 'out-in', // по умолчанию
  },
})
</script>

Отключение переходов

Для конкретного маршрута можно отключить pageTransition и layoutTransition:

pages/some-page.vue

<script setup lang="ts">
definePageMeta
({
  pageTransition
: false,
  layoutTransition
: false,
})
</script>

Или глобально в nuxt.config:

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    pageTransition: false,
    layoutTransition: false,
  },
})

JavaScript-хуки

Для сложных сценариев можно использовать JavaScript-хуки и библиотеки анимации, например GSAP.

pages/some-page.vue

<script setup lang="ts">
definePageMeta
({
  pageTransition
: {
    name
: 'custom-flip',
    mode
: 'out-in',
    onBeforeEnter
: (el
) => {
      console
.log
('Before enter...')
    },
    onEnter
: (el
, done
) => {},
    onAfterEnter
: (el
) => {},
  },
})
</script>

Подробнее о JavaScript-хуках компонента Transition.

Динамические переходы

Чтобы задать переход по условию, используйте inline middleware и меняйте to.meta.pageTransition:

<script setup lang="ts">
definePageMeta
({
  pageTransition
: {
    name
: 'slide-right',
    mode
: 'out-in',
  },
  middleware
 (to
, from
) {
    if (to
.meta.pageTransition && typeof to
.meta.pageTransition !== 'boolean') {
      to
.meta.pageTransition.name = +to
.params.id! > +from
.params.id! ? 'slide-left' : 'slide-right'
    }
  },
})
</script>

<template>
  <h1
>#{{ $route
.params
.id
 }}</h1
>
</template>

<style>
.slide-left-enter-active,
.slide-left-leave-active,
.slide-right-enter-active,
.slide-right-leave-active {
  transition: all 0.2s;
}
.slide-left-enter-from {
  opacity: 0;
  transform: translate(50px, 0);
}
.slide-left-leave-to {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-enter-from {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-leave-to {
  opacity: 0;
  transform: translate(50px, 0);
}
</style>

<script setup lang="ts">
const route = useRoute()
const id = computed(() => Number(route.params.id || 1))
const prev = computed(() => '/' + (id.value - 1))
const next = computed(() => '/' + (id.value + 1))
</script>

<template>
  <div>
    <slot />
    <div v-if="$route.params.id">
      <NuxtLink :to="prev">⬅️</NuxtLink> |
      <NuxtLink :to="next">➡️</NuxtLink>
    </div>
  </div>
</template>

При переходе к следующему id будет slide-left, к предыдущему — slide-right:

Переход с NuxtPage

Когда <NuxtPage /> используется в app.vue, переход можно задать пропом transition:

app/app.vue

<template>
  <div>
    <NuxtLayout>
      <NuxtPage
        :transition="{
          name: 'bounce',
          mode: 'out-in',
        }"
      />
    </NuxtLayout>
  </div>
</template>

Такой переход страницы нельзя переопределить через definePageMeta на отдельных страницах.

View Transitions API (экспериментально)

В Nuxt есть экспериментальная поддержка View Transitions API (MDN) — нативных переходов браузера, в том числе между разными элементами на разных страницах.

Демо: StackBlitz.

Включение в конфиге:

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    viewTransition: true,
  },
})

Допустимые значения: false, true или 'always'.

При true Nuxt не применяет переходы, если у пользователя включён prefers-reduced-motion: reduce (рекомендуется). При 'always' переходы всегда применяются — учитывать предпочтение пользователя нужно самостоятельно.

По умолчанию view transitions включены для всех страниц. Глобальное значение по умолчанию можно изменить:

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    // Отключить глобально, включать по страницам
    viewTransition: false,
  },
})

Для страницы значение переопределяется ключом viewTransition в definePageMeta:

pages/about.vue

<script setup lang="ts">
definePageMeta
({
  viewTransition
: false,
})
</script>

Переопределение view transitions по страницам действует только при включённой опции experimental.viewTransition.

Типы View Transition

Типы view transition позволяют применять разные CSS-анимации в зависимости от типа навигации. Это удобно для асимметричных переходов (например, разная анимация при переходе вперёд и назад).

Типы задаются в объекте ViewTransition и доступны в CSS через псевдокласс :active-view-transition-type().

Глобальные типы по умолчанию задаются в nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    viewTransition: {
      enabled: true,
      types: ['slide'],
    },
  },
})

Либо настраивайте типы по страницам через definePageMeta. Поддерживаются и статические массивы, и функции для динамики:

pages/detail.vue

<script setup lang="ts">
definePageMeta
({
  viewTransition
: {
    enabled
: true,
    // Типы для любого перехода с этой страницей
    types
: ['slide'],
    // Типы только при переходе НА эту страницу
    toTypes
: ['slide-in'],
    // Типы только при переходе С этой страницы
    fromTypes
: ['slide-out'],
  },
})
</script>

В definePageMeta для types, toTypes и fromTypes можно использовать функции, чтобы задавать типы по маршруту:

pages/[id].vue

<script setup lang="ts">
definePageMeta
({
  viewTransition
: {
    enabled
: true,
    toTypes
: (to
, from
) => {
      // Влево при переходе к большему ID, иначе вправо
      return Number
(to
.params.id) > Number
(from
.params.id)
        ? ['slide-left']
        : ['slide-right']
    },
  },
})
</script>

Затем задайте эти типы в CSS:

/* Обычный кроссфейд */
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.3s;
}

/* Анимация сдвига влево */
html:active-view-transition-type(slide-left) {
  &::view-transition-old(root) {
    animation: slide-out-left 0.3s ease-in-out;
  }
  &::view-transition-new(root) {
    animation: slide-in-right 0.3s ease-in-out;
  }
}

/* Анимация сдвига вправо */
html:active-view-transition-type(slide-right) {
  &::view-transition-old(root) {
    animation: slide-out-right 0.3s ease-in-out;
  }
  &::view-transition-new(root) {
    animation: slide-in-left 0.3s ease-in-out;
  }
}

Значения-функции для types, toTypes и fromTypes работают только в definePageMeta, в nuxt.config.ts поддерживается только статический string[].

Хук page:view-transition:start даёт доступ к объекту ViewTransition и его свойству types (ViewTransitionTypeSet), которое можно читать и менять во время выполнения:

plugins/view-transition.client.ts

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('page:view-transition:start', (transition) => {
    // Чтение или изменение типов во время выполнения
    console.log([...transition.types])
  })
})

Если вы используете Vue-переходы (pageTransition, layoutTransition) и хотите отключить их при поддержке View Transitions API в браузере, создайте ~/middleware/disable-vue-transitions.global.ts:

export default defineNuxtRouteMiddleware((to) => {
  if (import.meta.server || !document.startViewTransition) {
    return
  }

  to.meta.pageTransition = false
  to.meta.layoutTransition = false
})

Известные ограничения

При загрузке данных в setup-функциях страницы использование этой возможности может быть нежелательно: View Transitions полностью замораживают обновления DOM на время перехода. Рассматривается ограничение перехода моментом перед разрешением <Suspense>. Пока что оцените, подходит ли вам эта возможность.

Был ли материал полезен?

Сообщить об ошибке или Редактировать на GitHub

SEO и мета-теги

Улучшение SEO приложения Nuxt: конфигурация head, композаблы и компоненты.

Получение данных

Nuxt предоставляет композаблы для получения данных в приложении.