Vue Router в Vue — полное руководство

TL;DR

Vue Router — официальный маршрутизатор для Vue 3, который позволяет строить SPA, сопоставлять компоненты с маршрутами, передавать параметры и query, обрабатывать 404 и добавлять переходы. В этом руководстве показано настройка, передача params и query, защита маршрутов, ленивые загрузки, анимации, чек-листы и практические шаблоны для разработки и тестирования.

Vue Router — официальный пакет маршрутизации для Vue. Он позволяет:

• Создавать Single-Page Applications (SPA).
• Сопоставлять компоненты приложения с путями браузера.
• Управлять историей навигации (стэк переходов).
• Определять динамические сегменты, query и fallback-страницы.

Пояснение терминов в одну строку:

• Маршрут (route): правило, которое сопоставляет URL с компонентом.
• Параметр (param): динамическая часть URL, обозначается через “:”.
• Query: строка запроса после “?” в URL.
• Fallback: страница 404, когда маршрут не найден.

Быстрый старт

1. Создайте проект Vue через npm:

npm create vue

При запросе о добавлении Vue Router выберите ‘Yes’.

После создания проекта откройте директорию src — в ней должен появиться каталог router:

Файл src/router/index.js обычно импортирует функции createRouter и createWebHistory из пакета vue-router и экспортирует настроенный экземпляр router.

Пример подключения router в main.js:

import './assets/main.css'

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)

app.use(router)

app.mount('#app')

Теперь можно использовать RouterLink и RouterView в компонентах:

• RouterLink генерирует ссылку на указанный маршрут.
• RouterView служит контейнером, в который Vue вставляет компонент текущего маршрута.

Конфигурация маршрутов и динамические сегменты

Простейший конфиг router/index.js:

// index.js
import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '../views/HomeView.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'home',
      component: HomeView,
    },
    {
      path: '/developer/:profileNumber',
      name: 'developer',
      component: () => import('../views/devView.vue'),
    },
  ],
})

export default router

Сегмент “:profileNumber” делает часть URL динамической, например: “/developer/123”.

В App.vue можно создавать ссылки на такие маршруты:

В компоненте devView.vue можно получить параметр двумя способами:

1. Через объект $route в шаблоне:

2. Через Composition API с useRoute:

useRoute() интегрируется с реактивностью Vue, поэтому при изменении params компонент автоматически обновится.

Query-параметры (строка запроса)

Query-параметры добавляются после символа “?” и доступны в $route.query или route.query.

Создание ссылки с query:

Home

Доступ в шаблоне:

Query полезны для фильтров, поиска и параметров состояния, которые не влияют на загрузку компонента.

Fallback-страница (404)

Определите маршрут, который поймает все остальные пути:

{
  path: '/:pathName(.*)',
  name: 'NotFound',
  component: () => import('../views/NotFoundView.vue')
}

Этот маршрут использует регулярное выражение (.*) и отрисует компонент NotFoundView в случае неизвестного URL.

Полезные практики и дополнительные возможности

Ниже — практические приёмы, которые полезно знать при работе с Vue Router.

Ленивые загрузки (lazy loading)

Используйте динамический импорт для кода, который не нужен сразу:

{
  path: '/about',
  component: () => import('../views/AboutView.vue')
}

Это уменьшает размер начальной сборки и ускоряет первую загрузку.

Именованные маршруты и programmatic navigation

Именованные маршруты удобны для programmatic navigation:

router.push({ name: 'developer', params: { profileNumber: 123 } })

// или заменить текущую запись в истории
router.replace({ name: 'home' })

Передача props в компонент маршрута

Можно передать params как props для простоты тестирования и декуплинга:

{
  path: '/developer/:profileNumber',
  name: 'developer',
  component: () => import('../views/devView.vue'),
  props: true,
}

В devView.vue тогда доступен prop profileNumber напрямую.

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

Если у вас есть layout с дочерними страницами, используйте children:

{
  path: '/dashboard',
  component: () => import('../views/DashboardLayout.vue'),
  children: [
    { path: '', component: () => import('../views/DashboardHome.vue') },
    { path: 'settings', component: () => import('../views/DashboardSettings.vue') },
  ],
}

В DashboardLayout должен быть для вставки дочерних компонент.

Навигационные guard’ы (защита маршрутов)

Guard’ы позволяют проверять доступ, загружать данные или предотвращать переходы.

Глобальный guard:

router.beforeEach((to, from, next) => {
  const requiresAuth = to.meta.requiresAuth
  if (requiresAuth && !isLoggedIn()) {
    next({ name: 'login' })
  } else {
    next()
  }
})

Локальные guard’ы можно задать внутри компонентов через beforeRouteEnter/leave.

scrollBehavior для управления прокруткой

const router = createRouter({
  history: createWebHistory(),
  routes,
  scrollBehavior(to, from, savedPosition) {
    if (savedPosition) return savedPosition
    if (to.hash) return { el: to.hash }
    return { top: 0 }
  }
})

Обработка ошибок навигации

При использовании router.push/replace навигация может быть отменена или выбросить NavigationFailure. Обрабатывайте ошибки при необходимости.

Анимации при переходе между маршрутами

Vue поддерживает переходы через компонент transition. Для анимации роутов оберните RouterView в transition:

Можно комбинировать с ключами, чтобы анимировать разные маршруты по-разному.

Когда маршрутизация может не подойти (контрпримеры)

• Очень простые многостраничные сайты без нужды в динамике: SSR или классический многостраничный подход проще.
• Если важна SEO на первой загрузке и вы не используете серверный рендеринг — нужно дополнительно настраивать мета-теги и предварительную индексацию.
• Если у проекта строгие требования к URL-структуре для сторонних систем — убедитесь, что режим истории настроен корректно (history vs hash).

Ментальные модели и эвристики

• Подумайте о маршрутах как о «входных точках» в экран приложения — каждый маршрут должен иметь чёткую ответственность.
• Params — для идентификаторов и подстановки в путь; query — для фильтров и состояния интерфейса.
• Используйте ленивую загрузку для редко используемых страниц.
• Храните авторизацию и загрузку данных в guard’ах или в отдельных слоях, а не в шаблонах.

Чек-листы и шаблоны

Чек-лист при добавлении нового маршрута (developer):

• Добавлен объект маршрута в router/index.js.
• Компонент подключён через ленивый импорт при необходимости.
• Если маршрут защищён, добавлено meta.requiresAuth.
• Написан unit/e2e тест для навигации.
• Обновлена навигация (RouterLink или programmatic).
• При необходимости добавлен props или useRoute.
• Проверен fallback (404) путь.

Чек-лист QA:

• Маршрут доступен по ожидаемому URL.
• Params и query корректно передаются и отображаются.
• При отсутствии прав навигация перенаправляет на login.
• Переходы анимируются корректно.

Шаблон SOP: добавить новый публичный маршрут

1. Создать компонент в views/.
2. Добавить маршрут в src/router/index.js с именем и ленивым импортом.
3. При необходимости добавить meta и props: true.
4. Обновить навигацию (RouterLink или router.push).
5. Написать базовые тесты (unit + e2e).
6. Провести ревью и деплой.

Критерии приёмки

• Маршрут корректно рендерит целевой компонент по URL.
• Переданные params доступны в компоненте как props или через useRoute.
• Query параметры читаются и влияют на поведение компонента, если требуется.
• При навигации сохраняется ожидаемая позиция скролла.
• Если маршрут требует авторизации, неавторизованный пользователь перенаправляется.

Тестовые сценарии (простые)

1. Навигация к ‘/developer/123’ отображает профиль с id 123.
2. Переход по RouterLink с query ‘?name=vue’ показывает значение name в компоненте.
3. Попытка доступа к приватному пути без токена перенаправляет на /login.
4. Неправильный путь отображает NotFoundView.

Совместимость и миграционные примечания

• Это руководство ориентировано на Vue 3 и vue-router 4. Для Vue 2 используется vue-router 3, API отличается (нет createRouter/createWebHistory).
• При миграции с Vue 2 обратите внимание на Composition API и differences в guard’ах и хелперах.

Примеры кода: дополнительные сниппеты

Программная навигация с обработкой ошибок:

try {
  await router.push({ name: 'developer', params: { profileNumber: 456 } })
} catch (err) {
  // Обработка навигационной ошибки
  console.error('Navigation error:', err)
}

Guard с асинхронной загрузкой данных перед входом на маршрут:

router.beforeEach(async (to, from, next) => {
  if (to.meta.fetchData) {
    try {
      await fetchSomeData(to.params.id)
      next()
    } catch (e) {
      next({ name: 'error' })
    }
  } else {
    next()
  }
})

Диаграмма принятия решения при выборе настроек маршрутизации

flowchart TD
  A[Нужна ли поддержка SEO на первой загрузке?] -->|Да| B[Рассмотрите SSR/SSG]
  A -->|Нет| C[SPA с vue-router]
  C --> D{Нужно ли поддерживать старые браузеры / якоря URL}
  D -->|Да| E[Используйте createWebHashHistory]
  D -->|Нет| F[Используйте createWebHistory]
  B --> G[Настроить meta-теги и prerendering]

Короткий глоссарий

• RouterLink: компонент для ссылок внутри приложения.
• RouterView: контейнер для текущего маршрута.
• Params: динамические сегменты в пути.
• Query: ключ=значение в строке запроса.
• Guard: функция, которая запускается при навигации и может разрешить или отменить её.

Заключение

Vue Router — мощный инструмент для маршрутизации в Vue-приложениях. Он покрывает большинство сценариев: от простых статических страниц до сложных SPA с авторизацией, ленивой загрузкой и кастомными переходами. Используйте guard’ы для управления доступом и загрузкой данных, ленивые импорты для оптимизации и props для упрощения тестирования компонентов.

Важно: выбирайте стратегию маршрутизации в контексте требований к SEO и пользовательскому опыту. Для production-сайтов, где критична индексируемость, рассмотрите серверный рендеринг или гибридные подходы.

Полезные шаги дальше:

• Добавьте unit и e2e тесты на навигацию.
• Настройте мониторинг навигационных ошибок.
• Реализуйте доступность (a11y) для ссылок и фокусного управления при переходах.