Справочник 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.

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

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

<router-link tag="li" to="/foo">
  <a>/foo</a>
</router-link>

В этом случае <a> будет фактической ссылкой (и получит правильный href), но активный класс будет применён к внешнему <li>.

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' }}">Register</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>
    

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

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:

    declare type 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.replace(location, onComplete?, 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

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

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