Справочник API

This project is sponsored by bit

<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".

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 конструктора маршрутизатора.

<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

router.currentRoute

Методы экземпляра 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 будет массивом, содержащим копии объектов (клоны), в порядке сортировки от родителя к потомку.

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

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

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

  • this.$router

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

  • this.$route

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

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