Критические изменения API

Vue Router является официальной библиотекой маршрутизации для Vue.js и активно развивается вместе с экосистемой. В последних версиях произошли значительные изменения, влияющие на структуру кода и способы организации маршрутов. Эти изменения требуют внимательного подхода при миграции с предыдущих версий.

Новый способ создания экземпляра маршрутизатора

В версиях до Vue Router 4 использовался синтаксис:

import Vue from 'vue'
import Router from 'vue-router'
import Home from './views/Home.vue'

Vue.use(Router)

export default new Router({
  routes: [
    { path: '/', component: Home }
  ]
})

Начиная с Vue Router 4 синтаксис изменился. Вместо глобальной регистрации через Vue.use применяется функция createRouter:

import { createRouter, createWebHistory } from 'vue-router'
import Home from './views/Home.vue'

const routes = [
  { path: '/', component: Home }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router

Ключевые моменты:

  • Использование createWebHistory() или createWebHashHistory() вместо свойства mode.
  • Не требуется глобальная регистрация через Vue.use.
  • Экземпляр маршрутизатора создается и передается в приложение Vue через опцию router при создании приложения.
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

createApp(App).use(router).mount('#app')

Изменения в динамических маршрутах и параметрах

Ранее параметры маршрута были доступны через this.$route.params, а навигация выполнялась через this.$router.push. В новой версии API навигация стала более гибкой и поддерживает объектные формы с типизацией:

router.push({ name: 'user', params: { id: 123 } })
  • Параметры маршрута теперь автоматически преобразуются при наличии props: true в конфигурации маршрута.
  • Возможность передавать объект query для GET-подобных параметров:
router.push({ path: '/search', query: { q: 'vue' } })
  • Методы replace, go, back и forward остались, но теперь возвращают промисы, что позволяет использовать async/await:
await router.push('/about')

Lazy Loading компонентов и маршрутов

Lazy Loading компонентов стал стандартной практикой, особенно для крупных проектов:

const About = () => import('./views/About.vue')

const routes = [
  { path: '/about', component: About }
]

Важные изменения:

  • Синтаксис динамического импорта не изменился, но теперь поддерживается асинхронная обработка ошибок при навигации.
  • Vue Router 4 автоматически предотвращает дублирующие переходы в те же маршруты и выбрасывает ошибки навигации типа NavigationDuplicated.

Навигационные охранники (beforeEach, beforeEnter, beforeRouteLeave) получили обновления в API:

  • Все хуки теперь поддерживают асинхронные функции и возврат промисов.
  • Возврат false отменяет навигацию, а возврат строки или объекта инициирует редирект:
router.beforeEach(async (to, from) => {
  if (!isAuthenticated() && to.meta.requiresAuth) {
    return { name: 'login' }
  }
})
  • Локальные guards beforeRouteEnter и beforeRouteUpdate в компонентах теперь позволяют использовать next с объектом маршрута, поддерживая асинхронность.

Методы и свойства экземпляра маршрутизатора

Набор методов изменился:

Метод Новое поведение
push Возвращает промис, поддерживает async/await
replace Возвращает промис, аналогично push
go, back, forward Возвращают void или промис
resolve Генерирует объект маршрута без навигации
getRoutes Возвращает массив зарегистрированных маршрутов

Свойства маршрута также обновлены:

  • this.$route остался, но рекомендуется использовать Composition API через useRoute() и useRouter():
import { useRoute, useRouter } from 'vue-router'

export default {
  setup() {
    const route = useRoute()
    const router = useRouter()

    const goHome = () => router.push('/')
    return { route, goHome }
  }
}

Влияние на миграцию проектов

  • Старые проекты на Vue Router 3 требуют полной переработки регистрации маршрутизатора.
  • Navigation Guards и асинхронные переходы необходимо переписать с учетом промисов.
  • Lazy Loading и работа с параметрами маршрутов требуют корректного использования Composition API.

Эти изменения делают работу с маршрутизацией более предсказуемой, типизированной и совместимой с современными подходами Vue 3.

Оглавление