Справочник API

<router-link>

<router-link> — это компонент предназначенный для навигации пользователя в приложении с клиентской маршрутизацией. Путь назначения указывается входным параметром to. По умолчанию компонент рендерится в тег <a> с корректным значением href, но это можно изменить входным параметром tag. Кроме того, ссылка автоматически получает активный класс CSS при переходе на путь назначения.

<router-link> предпочтительнее <a href="..."> по следующим причинам:

• Он работает одинаково вне зависимости от режима работы (HTML5 history или хэш), поэтому если вы решите переключить режим, или маршрутизатор для совместимости переключится обратно в режим хэша в IE9, ничего не потребуется изменять.
• В режиме HTML5 history, router-link будет перехватывать событие click, чтобы браузер не пытался перезагрузить страницу.
• При использовании опции base в режиме работы HTML5 history, вам не потребуется добавлять её в URL входного параметра to.

v-slot API (3.1.0+)

router-link предоставляет возможность более низкоуровневой настройки с помощью слота с ограниченной областью видимости. Это более продвинутое API ориентировано в первую очередь на создателей библиотек, но может пригодиться и разработчикам, к примеру для создании пользовательских компонентов таких как NavLink или подобных.

При использовании API v-slot необходимо передавать один дочерний элемент в router-link. Если этого не сделать, router-link обернёт все дочерние элементы в span.

<router-link
  to="/about"
  v-slot="{ href, route, navigate, isActive, isExactActive }"
>
  <NavLink :active="isActive" :href="href" @click="navigate">
    {{ route.fullPath }}
  </NavLink>
</router-link>

• href: разрешённый URL. Это будет атрибутом href для элемента a
• route: разрешённый нормализованный маршрут
• navigate: функция для запуска навигации. Она автоматически предотвращает события, когда это необходимо, аналогичным способом, как это делает router-link
• isActive: true если активный класс должен применяться. Позволяет применить произвольный класс
• isExactActive: true если активный класс при точном совпадении пути должен применяться. Позволяет применить произвольный класс

Пример: Добавление активного класса к внешнему элементу

Иногда может потребоваться применять активный класс к внешнему элементу, а не к тегу <a>, в этом случае можно обернуть этот элемент в <router-link> и использовать свойства v-slot для создания ссылки:

<router-link
  to="/foo"
  v-slot="{ href, route, navigate, isActive, isExactActive }"
>
  <li
    :class="[isActive && 'router-link-active', isExactActive && 'router-link-exact-active']"
  >
    <a :href="href" @click="navigate">{{ route.fullPath }}</a>
  </li>
</router-link>

ПРИМЕЧАНИЕ

При добавлении target="_blank" на элемент a, необходимо опустить обработчик @click="navigate".

Входные параметры <router-link>

to

• тип: string | Location

• обязательный

  Определяет итоговый маршрут ссылки. При нажатии, значение входного параметра to будет передано в router.push() — поэтому это значение может быть как строкой, так и объектом описывающим маршрут.

  <!-- строка -->
  <router-link to="home">Home</router-link>
  <!-- отобразится в -->
  <a href="home">Home</a>
  
  <!-- javascript-выражение с использованием `v-bind` -->
  <router-link v-bind:to="'home'">Home</router-link>
  
  <!-- можно опустить `v-bind`, аналогично другим входным параметрам -->
  <router-link :to="'home'">Home</router-link>
  
  <!-- даст тот же результат -->
  <router-link :to="{ path: 'home' }">Home</router-link>
  
  <!-- именованный маршрут -->
  <router-link :to="{ name: 'user', params: { userId: 123 }}">User</router-link>
  
  <!-- с использованием query-строки, получим `/register?plan=private` -->
  <router-link :to="{ path: 'register', query: { plan: 'private' }}">
    Регистрация
  </router-link>
  

replace

• тип: boolean

• по умолчанию: false

  Указание входного параметра replace вызовет router.replace() вместо router.push() при нажатии на ссылку, поэтому навигация не оставит записи в истории переходов.

  <router-link :to="{ path: '/abc'}" replace></router-link>
  

append

• тип: boolean

• по умолчанию: false

  Указание входного параметра append будет добавлять относительный путь к текущему. Например, если мы переходим от /a к относительной ссылке b, то без append будет адрес /b, а вместе с append получится /a/b.

  <router-link :to="{ path: 'relative/path'}" append></router-link>
  

tag

• тип: string

• по умолчанию: "a"

  Иногда необходимо чтобы <router-link> отображался другим тегом, например <li>. В таком случае мы можем использовать входной параметр tag, чтобы указать нужный тег, и он всё равно будет прослушивать события click для навигации.

  <router-link to="/foo" tag="li">foo</router-link>
  <!-- отобразится как -->
  <li>foo</li>
  

active-class

• тип: string

• по умолчанию: "router-link-active"

  Указание активного CSS класса, который применяется когда ссылка активна. Обратите внимание, что значение по умолчанию можно задать глобально в опции linkActiveClass конструктора маршрутизатора.

exact

• тип: boolean

• по умолчанию: false

  Стандартное поведение определения когда выставлять активный класс основывается на совпадениях по включению. Например, <router-link to="/a"> будет получать класс активности, когда текущий путь начинается с /a/ или /a.

  Обратите внимание, поэтому <router-link to="/"> будет активным для каждого маршрута! Для «режима точного соответствия» укажите в ссылке входной параметр exact:

  <!-- эта ссылка будет активной только для адреса `/` -->
  <router-link to="/" exact></router-link>
  

  Ознакомьтесь с другими примерами активных классов ссылок вживую.

event

• тип: string | Array<string>

• по умолчанию: 'click'

  Определение события (событий), которые будут вызывать навигацию по ссылке.

exact-active-class

• тип: string

• по умолчанию: "router-link-exact-active"

  Указание активного CSS класса, который применяется когда ссылка активна с точным соответствием пути. Обратите внимание, что значение по умолчанию можно задать глобально в опции linkExactActiveClass конструктора маршрутизатора.

aria-current-value

• тип: 'page' | 'step' | 'location' | 'date' | 'time'

• по умолчанию: "page"

  Настройка значения aria-current когда ссылка активна по точному (exact) совпадению. Это должно быть одно из разрешённых значений для aria-current спецификации ARIA. В большинстве случаев наиболее подходящим значением будет page.

<router-view>

Функциональный компонент <router-view> отображает компонент соответствующий данному маршруту. Компоненты внутри <router-view> также могут содержать в шаблоне собственный <router-view> (он будет использован для отображения компонентов вложенных маршрутов).

Все остальные входные параметры передаются в отображаемый компонент, однако данные маршрута удобнее получать из $route.params текущего маршрута.

Поскольку это всего лишь компонент, он работает вместе с <transition> и <keep-alive>. При одновременном использовании обоих обязательно располагайте <keep-alive> внутри:

<transition>
  <keep-alive>
    <router-view></router-view>
  </keep-alive>
</transition>

Входные параметры <router-view>

name

• тип: string

• по умолчанию: "default"

  Наличие имени у <router-view> определяет отображение компонента с соответствующим именем из опции components сопоставленного маршрута. Подробности и примеры использования этой возможности в разделе именованных представлений.

Опции конструктора Router

routes

• тип: Array<RouteConfig>

  Декларация типа для RouteConfig:

  interface RouteConfig = {
    path: string,
    component?: Component,
    name?: string, // для именованных маршрутов
    components?: { [name: string]: Component }, // для именованных представлений
    redirect?: string | Location | Function,
    props?: boolean | Object | Function,
    alias?: string | Array<string>,
    children?: Array<RouteConfig>, // для вложенных маршрутов
    beforeEnter?: (to: Route, from: Route, next: Function) => void,
    meta?: any,
  
    // Добавлено в версии 2.6.0+
    caseSensitive?: boolean, // учитывать регистр при сравнении? (по умолчанию: false)
    pathToRegexpOptions?: Object // настройки path-to-regexp для компиляции regex
  }
  

mode

• тип: string

• по умолчанию: "hash" (in browser) | "abstract" (in Node.js)

• возможные значения: "hash" | "history" | "abstract"

  Определяет режим работы маршрутизатора.

  • hash: используется хэш URL для маршрутизации. Работает во всех совместимых с Vue браузерами, даже тех, что не поддерживают HTML5 History API.

  • history: требует поддержки HTML5 History API и конфигурации сервера. Подробнее в разделе Режим HTML5 History.

  • abstract: работает во всех JavaScript-окружениях, например при серверном рендеринге с помощью Node.js. Маршрутизатор автоматически переключается в этот режим, если не обнаружит API браузера.

base

• тип: string

• по умолчанию: "/"

  Базовый URL приложения. Например, если SPA расположено по пути /app/, тогда base должно иметь значение "/app/".

linkActiveClass

• тип: string

• по умолчанию: "router-link-active"

  Глобальная настройка активного класса по умолчанию для <router-link>. Подробнее в опции router-link.

linkExactActiveClass

• тип: string

• по умолчанию: "router-link-exact-active"

  Глобальная настройка активного класса по умолчанию при точном совпадении маршрута для <router-link>. Подробнее в опции router-link.

scrollBehavior

• тип: Function

  Сигнатура:

  type PositionDescriptor =
    { x: number, y: number } |
    { selector: string } |
    ?{}
  
  type scrollBehaviorHandler = (
    to: Route,
    from: Route,
    savedPosition?: { x: number, y: number }
  ) => PositionDescriptor | Promise<PositionDescriptor>
  

  Подробнее в разделе настройки поведения прокрутки страницы.

parseQuery / stringifyQuery

• тип: Function

  Указание пользовательских функций для парсинга строки запроса / приведения к строке запроса (stringify). Переопределяют реализации по умолчанию.

fallback

• тип: boolean

• по умолчанию: true

  Определяет, должен ли маршрутизатор возвращаться в режим hash, когда браузер не поддерживает history.pushState.

  Установка этой опции в false будет приводить к полному обновлению страницы в IE9 для каждой навигации через <router-link>. Это полезно, когда приложение рендерится на стороне сервера (SSR) и должно работать в IE9, потому что режим hash не работает с серверным рендерингом.

Свойства экземпляра Router

router.app

• тип: Vue instance

  Корневой экземпляр Vue, в который внедряется router.

router.mode

• тип: string

  Режим работы, используемый маршрутизатором.

router.currentRoute

• тип: Route

  Текущий маршрут в виде объекта Route.

Методы экземпляра Router

router.beforeEach

router.beforeResolve

router.afterEach

Сигнатуры:

router.beforeEach((to, from, next) => {
  /* необходимо вызывать `next` */
})

router.beforeResolve((to, from, next) => {
  /* необходимо вызывать `next` */
})

router.afterEach((to, from) => {})

Добавляют глобальные навигационные хуки. Подробнее в разделе Навигационные хуки.

Все три метода возвращают функцию для удаления зарегистрированного хука.

router.push

router.replace

router.go

router.back

router.forward

Сигнатуры:

router.push(location, onComplete?, onAbort?)
router.push(location).then(onComplete).catch(onAbort)
router.replace(location, onComplete?, onAbort?)
router.replace(location).then(onComplete).catch(onAbort)
router.go(n)
router.back()
router.forward()

Программная навигация на новый URL. Подробнее в разделе программная навигация.

router.getMatchedComponents

Сигнатура:

const matchedComponents: Array<Component> = router.getMatchedComponents(location?)

Возвращает массив компонентов (определение/конструктор, не экземпляры) сопоставленные для указанного адреса или текущего маршрута. В основном это используется для рендеринга на стороне сервера, чтобы выполнить предварительную загрузку данных.

router.resolve

Сигнатура:

const resolved: {
  location: Location;
  route: Route;
  href: string;
} = router.resolve(location, current?, append?)

Обратное разрешение URL, чтобы получить местоположение в формате, аналогичном используемому в <router-link/>.

• current текущий маршрут по умолчанию (в большинстве случаев не требуется это менять)
• append позволяет вам добавить путь к маршруту current (как и в router-link)

router.addRoutes

Сигнатура:

router.addRoutes(routes: Array<RouteConfig>)

Динамически добавляет дополнительные маршруты в маршрутизатор. Аргумент должен быть массивом маршрутов в таком же формате, как и в опции routes конструктора.

router.onReady

Сигнатура:

router.onReady(callback, [errorCallback])

Регистрирует коллбэк, который будет вызван когда маршрутизатор завершит начальную навигацию, когда будут завершены все асинхронные хуки и готовы асинхронные компоненты, связанные с начальным маршрутом.

Пригодится при рендеринге на стороне сервера, чтобы обеспечить консистентный результат как на сервере, так и на клиенте.

Второй аргумент errorCallback поддерживается только в версиях 2.4+. Он вызывается когда начальное разрешение маршрута заканчивается ошибкой (например, не удалось разрешить асинхронный компонент).

router.onError

Сигнатура:

router.onError(callback)

Регистрирует коллбэк, который будет вызван при обнаружении ошибок во время навигации по маршруту. Обратите внимание, что он вызывается в одном из следующих сценариев:

• Ошибка произошла синхронно внутри функции маршрута;

• Ошибка фиксируется и асинхронно обрабатывается с помощью next(err) внутри функции навигационного хука;

• Произошла ошибка при попытке разрешить асинхронный компонент, необходимый для отображения маршрута.

Объект Route

Объект Route представляет собой состояние текущего активного маршрута. Он содержит информацию о текущем URL и записи маршрутов, сопоставленные с ним.

Объект маршрута иммутабелен. Каждая успешная навигация создаёт новый объект маршрута.

Объект маршрута встречается в нескольких местах:

• Внутри компонентов как this.$route

• Внутри коллбэка при отслеживании изменений $route

• Как возвращаемое значение при вызове router.match(location)

• В качестве двух первых параметров навигационных хуков:

  router.beforeEach((to, from, next) => {
    // как `to` так и `from` являются объектами маршрута
  })
  

• В качестве двух первых параметров функции scrollBehavior:

  const router = new VueRouter({
    scrollBehavior(to, from, savedPosition) {
      // как `to` так и `from` являются объектами маршрута
    }
  })
  

Свойства объекта Route

• $route.path

  • тип: string

    Строка пути текущего маршрута, всегда в абсолютном формате, например "/foo/bar".

• $route.params

  • тип: Object

    Объект, который содержит пары ключ/значение динамических сегментов маршрута (включая *-сегменты). Если параметров нет, то значением будет пустой объект.

• $route.query

  • тип: Object

    Объект, который содержит пары ключ/значение строки запроса (query string). Например, для пути /foo?user=1 получим $route.query.user == 1. Если строки запроса нет, то значением будет пустой объект.

• $route.hash

  • тип: string

    Хэш текущего маршрута (вместе с символом #) при его наличии. Если хэша нет, то значением будет пустая строка.

• $route.fullPath

  • тип: string

    Полная запись URL-адреса, включая строку запроса и хэш.

• $route.matched

  • тип: Array<RouteRecord>

  Массив с записями маршрутов для всех вложенных сегментов текущего маршрута. Записи маршрутов — это копии объектов из опции routes (и вложенных массивов children):

  const router = new VueRouter({
    routes: [
      // объект ниже — это запись маршрута
      {
        path: '/foo',
        component: Foo,
        children: [
          // это — тоже запись маршрута
          { path: 'bar', component: Bar }
        ]
      }
    ]
  })
  

Для URL /foo/bar, значение $route.matched будет массивом, содержащим копии объектов (клоны), в порядке сортировки от родителя к потомку.

• $route.name

  Имя текущего маршрута, если было указано. (Подробнее в разделе именованные маршруты)

• $route.redirectedFrom

  Имя маршрута с которого произошло перенаправление, если было указано. (Подробнее в разделе перенаправления и псевдонимы)

Интеграция в компоненты

Внедряемые в компоненты свойства

Эти свойства внедряются в каждый дочерний компонент, передавая экземпляр маршрутизатора в корневой экземпляр в качестве опции router.

• this.$router

  Экземпляр маршрутизатора.

• this.$route

  Текущий активный маршрут. Это свойство только для чтения и все его свойства иммутабельны, но можно отслеживать их изменения.

Добавляемые опции в компонент

• beforeRouteEnter

• beforeRouteUpdate

• beforeRouteLeave

  Подробнее в разделе Навигационные хуки компонентов.