Skip to content

Latest commit

 

History

History
508 lines (316 loc) · 23.9 KB

README.md

File metadata and controls

508 lines (316 loc) · 23.9 KB
sidebar
auto

Справочник 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 mode, вам не потребуется добавлять её в URL входного параметра to.

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

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

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

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

Входные параметры <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' }}">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>
<!-- renders as -->
<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 | string | 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 будет вызывать для каждой навигации через <router-link> полное обновление страницы в IE9. Это может быть полезным, когда приложение рендерится на стороне сервера и должно работать в IE9, потому что режим hash не работает с серверным рендерингом (SSR).

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

router.app

  • тип: Vue instance

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

router.mode

  • тип: string

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

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

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

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