Spec-Zone.ru › Vue Router 3

Справочник API

<router-link>

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

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

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

API v-slot (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() внутренне, поэтому значение может быть строкой или объектом описания местоположения.

    <!-- literal string -->
<router-link to="home">Home</router-link>
<!-- renders to -->
<a href="home">Home</a>

<!-- javascript expression using `v-bind` -->
<router-link v-bind:to="'home'">Home</router-link>

<!-- Omitting `v-bind` is fine, just as binding any other prop -->
<router-link :to="'home'">Home</router-link>

<!-- same as above -->
<router-link :to="{ path: 'home' }">Home</router-link>

<!-- named route -->
<router-link :to="{ name: 'user', params: { userId: 123 }}">User</router-link>

<!-- with query, resulting in `/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 для указания отображаемого тега, и он по-прежнему будет отслеживать события кликов для навигации.

    <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:

    <!-- this link will only be active at `/` -->
<router-link to="/" exact></router-link>

    Узнайте больше об примерах, объясняющих активный класс ссылки здесь.

exact-path

Новое в 3.5.0

  • тип: boolean

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

    Позволяет сопоставлять только часть URL path, фактически игнорируя части query и hash.

    <!-- this link will also be active at `/search?page=2` or `/search#filters` -->
<router-link to="/search" exact-path> </router-link>

exact-path-active-class

  • тип: string

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

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

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 при активации ссылки с точным совпадением. Оно должно быть одним из разрешённых значений для aria-current в спецификации ARIA. В большинстве случаев, значение по умолчанию page является наилучшим вариантом.

<router-view>

Компонент <router-view> — это функциональный компонент, который отображает соответствующий компонент для данного пути. Компоненты, отображаемые в <router-view>, также могут содержать свои собственные <router-view>, которые будут отображать компоненты для вложенных путей.

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

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

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

Свойства <router-view>

name

  • тип: string

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

    Когда у <router-view> есть имя, он отобразит компонент с соответствующим именем в записи маршрута, в опции components . Смотрите Именованные представления для примера.

Опции конструирования маршрутизатора

routes

  • тип: Array<RouteConfig>

    Описание типа для RouteConfig:

    interface RouteConfig = {
  path: string,
  component?: Component,
  name?: string, // for named routes
  components?: { [name: string]: Component }, // for named views
  redirect?: string | Location | Function,
  props?: boolean | Object | Function,
  alias?: string | Array<string>,
  children?: Array<RouteConfig>, // for nested routes
  beforeEnter?: (to: Route, from: Route, next: Function) => void,
  meta?: any,

  // 2.6.0+
  caseSensitive?: boolean, // use case sensitive match? (default: false)
  pathToRegexpOptions?: Object // path-to-regexp options for compiling regex
}

mode

  • тип: string

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

  • доступные значения: "hash" | "history" | "abstract"

    Настройка режима маршрутизатора.

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

    • history: требует API истории HTML5 и конфигурации сервера. Смотрите Режим истории HTML5.

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

base

  • тип: string

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

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

linkActiveClass

  • тип: string

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

    Глобальная настройка активного класса по умолчанию. Также смотрите router-link.

linkExactActiveClass

  • тип: string

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

    Глобальная настройка активного класса по умолчанию для точных совпадений. Также смотрите router-link.

scrollBehavior

  • тип: Function

    Подпись:

    type PositionDescriptor =
  { x: number, y: number } |
  { selector: string } |
  void

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

    Для получения дополнительной информации смотрите Поведение прокрутки.

parseQuery / stringifyQuery

  • тип: Function

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

fallback

  • тип: boolean

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

    Управляет тем, перейдёт ли маршрутизатор в режим hash при отсутствии в браузере поддержки history.pushState, но режим установлен на history.

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

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

router.app

  • тип: Vue instance

    Корневой экземпляр Vue, в который был инжектирован router.

router.mode

  • тип: string

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

router.currentRoute

  • тип: Route

    Текущий маршрут, представленный как Объект маршрута.

router.START_LOCATION

  • тип: Route

    Исходное расположение маршрута, представленное как Объект маршрута, с которого начинается маршрутизатор. Может использоваться в сторожах навигации для различения начальной навигации.

    import Router from 'vue-router'

const router = new Router({
  // ...
})

router.beforeEach((to, from) => {
  if (from === START_LOCATION) {
    // initial navigation
  }
})

Методы экземпляра маршрутизатора

router.beforeEach

router.beforeResolve

router.afterEach

Подписи:

router.beforeEach((to, from, next) => {
  /* must call `next` */
})

router.beforeResolve((to, from, next) => {
  /* must call `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 и передачи его корневому экземпляру Vue, как показано в начале работы.

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

УСТЕРЕНО: используйте route.addRoute() вместо этого.

Подпись:

router.addRoutes(routes: Array<RouteConfig>)

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

router.addRoute

Новое в 3.5.0

Добавить новый маршрут в маршрутизатор. Если у маршрута есть name и уже существует аналогичный, он перезаписывается.

Подпись:

addRoute(route: RouteConfig): () => void

router.addRoute

Новое в 3.5.0

Добавить новую запись маршрута как дочернюю к существующему маршруту. Если у маршрута есть name и уже существует аналогичный, он перезаписывается.

Подпись:

addRoute(parentName: string, route: RouteConfig): () => void

router.getRoutes

Новое в 3.5.0

Получить список всех активных записей маршрутов. **Обратите внимание, что только документированные свойства считаются общедоступным API**, избегайте использования других свойств, например regex, так как они отсутствуют в Vue Router 4.

Подпись:

getRoutes(): RouteRecord[]

router.onReady

Подпись:

router.onReady(callback, [errorCallback])

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

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

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

router.onError

Подпись:

router.onError(callback)

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

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

  • Ошибка обрабатывается асинхронно, вызывая next(err) внутри функции сторожа маршрута;

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

Объект маршрута

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

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

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

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

  • Внутри $route обратных вызовов наблюдателей

  • В качестве возвращаемого значения вызова router.match(location)

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

    router.beforeEach((to, from, next) => {
  // `to` and `from` are both route objects
})

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

    const router = new VueRouter({
  scrollBehavior(to, from, savedPosition) {
    // `to` and `from` are both route objects
  }
})

Свойства объекта маршрута

  • $route.path

    • тип: string

      Строка, равная пути текущего маршрута, всегда разрешается как абсолютный путь. Например, "/foo/bar".

  • $route.params

    • тип: Object

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

  • $route.query

    • тип: Object

      Объект, содержащий пары ключ/значение строки запроса. Например, для пути /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: [
    // the following object is a route record
    {
      path: '/foo',
      component: Foo,
      children: [
        // this is also a route record
        { path: 'bar', component: Bar }
      ]
    }
  ]
})

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

  • $route.name

    Имя текущего маршрута, если оно есть. (См. Именованные маршруты)

  • $route.redirectedFrom

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

Встраивания компонентов

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

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

  • this.$router

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

  • this.$route

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

Активные опции компонента

  • beforeRouteEnter

  • beforeRouteUpdate

  • beforeRouteLeave

    См. В сторожах компонентов.

© 2013–present Evan You
Licensed under the MIT License.
https://router.vuejs.org/api/

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API