Vue Router

# API

<router-link> est le composant pour activer la navigation utilisateur dans une application où le routeur est activé. La localisation cible est spécifiée grâce à la prop to. Il est rendu en tant que balise <a> avec le href correct par défaut, mais peut être configuré grâce à la prop tag. De plus, le lien se verra attribuer une classe CSS active lorsque la route cible est active.

<router-link> est préféré par rapport au <a href="..."> en dur dans le code pour les raisons suivantes :

  • Cela fonctionne de la même manière qu'on soit dans le mode historique HTML5 ou le mode hash, donc si vous avez décidé de changer de mode, ou alors que le routeur se replie sur le mode hash pour IE9, rien n'a besoin d'être changé.

  • Dans le mode historique HTML5, router-link interceptera l'évènement du clic, comme ça le navigateur n'essaiera pas de rafraichir la page.

  • En utilisant l'option base dans le mode historique HTML5, vous n'avez pas besoin de l'inclure dans la prop to

# v-slot API (3.1.0+)

router-link est fortement personnalisable via une slot avec portée (opens new window). C'est une API qui cible principalement les créateurs de bibliothèque, mais elle peut aussi servir pour les développeurs, le plus souvent dans des composants personnalisés tel qu'un NavLink et autre.

Lors de l'utilisation v-slot API, il faut obligatoirement passer un composant enfant unique au router-link. Si vous ne le faites pas, router-link va entourer ses enfants avec une balise span.

<router-link
  to="/about"
  custom
  v-slot="{ href, route, navigate, isActive, isExactActive }"
>
  <NavLink :active="isActive" :href="href" @click="navigate"
    >{{ route.fullPath }}</NavLink
  >
</router-link>
  • href: URL résolue. Ce serait l'attribut href d'une balise a
  • route: localisation normalisée et résolue
  • navigate: fonction pour lancer la navigation. En cas de nécessité il va automatiquement empêcher les événements, de la même façon que router-link
  • isActive: true si active class devrait être appliqué. Permet d'appliquer une classe arbitraire
  • isExactActive: true si exact active class devrait être appliqué. Permet d'appliquer une classe arbitraire

# Appliquer la classe active à l'élément extérieur

Parfois, on voudrait que la classe active soit appliquée à un élément extérieur au lieu de l'élément <a> lui-même, dans ce cas, vous pouvez faire le rendu de cet élément extérieur en utilisant <router-link> et en entourant le tag <a> :

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

Dans ce cas, <a> sera le lien actuel (et récupèrera le bon href), mais la classe active sera appliquée à l'élément extérieur <li>.

# to

  • type : string | Location

  • requis

    Désigne la route cible du lien. Lorsqu'il est cliqué, la valeur de la prop to va être passée de manière interne à router.push, donc la valeur peut soit être une chaine de caractères, ou alors un objet décrivant une localisation.

    <!--  chaine littérale  -->
<router-link to="home">Accueil</router-link>
<!-- rend -->
<a href="home">Accueil</a>

<!-- expression JavaScript en utilisant `v-bind` -->
<router-link v-bind:to="'home'">Accueil</router-link>

<!-- Omettre `v-bind` est OK, tout comme une autre prop -->
<router-link :to="'home'">Accueil</router-link>

<!-- pareil qu'au-dessus -->
<router-link :to="{ path: 'home' }">Accueil</router-link>

<!-- route nommée -->
<router-link :to="{ name: 'user', params: { userId: 123 }}"
  >Utilisateur</router-link
>

<!-- avec une requête, résulte en `/register?plan=private` -->
<router-link :to="{ path: 'register', query: { plan: 'private' }}"
  >S'enregistrer</router-link
>

# replace

  • type : boolean

  • défaut : false

    Configurer la prop replace appellera router.replace() au lieu de router.push() lors du clic, comme ça, la navigation ne laissera pas un enregistrement dans l'historique.

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

# append

  • type : boolean

  • défaut : false

    Configurer la propriété append suffixe toujours le chemin relatif au chemin courant. Par exemple, assumons que nous naviguons de /a à un lien relatif b, sans append on finira sur /b, mais avec append on finira sur /a/b.

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

# tag

  • type : string

  • défaut : "a"

    Parfois, on veut que <router-link> soit rendu avec une balise différente, ex : <li>. On peut alors utiliser la prop tag pour modifier la balise qui sera rendue, et elle écoutera toujours les évènements de clic pour la navigation.

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

# active-class

  • type : string

  • défaut : "router-link-active"

    Configure la classe CSS active qui sera appliquée lorsque le lien sera actif. Notez que la valeur par défaut peut aussi être configurée de manière globale via l'option linkActiveClass du constructeur du routeur.

# exact

  • type : boolean
  • défaut : false

Le comportement par défaut de la correspondance de classe active est une correspondance inclusive. Par exemple, <router-link to="/a"> verra cette classe appliquée tant que le chemin courant commencera par /a/ ou /a.

Une conséquence de cela est que <router-link to="/"> sera actif pour toutes les routes ! Pour forcer le lien dans un « mode correspondance exacte », utilisez la prop exact.

<!-- ce lien sera uniquement actif à `/` -->
<router-link to="/" exact></router-link>

Allez voir les exemples expliquant la classe active pour les liens ici (opens new window).

# event

  • type : string | Array<string>

  • défaut : 'click'

    Spécifie les évènement(s) que peu(ven)t lancer la navigation de lien.

# exact-active-class

  • type : string

  • défaut : "router-link-exact-active"

    Configure la classe CSS active qui sera appliquée lorsqu'un lien sera actif avec une correspondance exacte. Notez que la valeur par défaut peut aussi être configurée de manière globale via l'option linkExactActiveClass du constructeur du routeur.

# <router-view>

Le composant <router-view> est un composant fonctionnel qui fait le rendu du composant correspondant au chemin donné. Les composants rendus dans <router-view> peuvent aussi contenir leur propre <router-view>, qui fera le rendu des composants pour les chemins imbriqués.

# <router-view> Props

# name

  • type : string

  • défaut : "default"

    Lorsqu'un <router-view> a un nom, il fera le rendu du composant correspondant à ce nom dans les itinéraires de route correspondant à l'option components. Voir les Routes nommées pour un exemple.

# Options de construction du routeur

# routes

  • type: Array<RouteConfig>

    Déclaration de type pour RouteConfig :

    declare type RouteConfig = {
  path: string,
  component?: Component,
  name?: string, // pour les routes nommées
  components?: { [name: string]: Component }, // pour les vues nommées
  redirect?: string | Location | Function,
  props?: boolean | string | Function,
  alias?: string | Array<string>,
  children?: Array<RouteConfig>, // pour les routes imbriquées
  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

  • type : string

  • défaut : "hash" (dans le navigateur) | "abstract" (en Node.js)

  • valeurs disponibles : "hash" | "history" | "abstract"

    Configure le mode du routeur.

    • hash : utilise le hash de l'URL pour le routage. Fonctionne dans tous les navigateurs supportés par Vue, ainsi que ceux qui ne supportent pas l'API History d'HTML5.

    • history : nécessite l'API History d'HTML 5 et la configuration du serveur. Voir Mode historique de HTML5.

    • abstract : fonctionne dans tous les environnements JavaScript, ex. côté serveur avec Node.js. Le routeur sera automatiquement forcé d'utiliser ce mode si aucune API navigateur n'est présente.

# base

  • type : string

  • défaut : "/"

    L'URL de base de l'application. Par exemple, si l'application monopage entière est distribuée sous /app/, alors base doit utiliser la valeur "/app/".

# linkActiveClass

  • type : string

  • défaut : "router-link-active"

    Configure de manière globale la classe active par défaut de <router-link>. Voir aussi router-link.

# linkExactActiveClass

  • type : string

  • default : "router-link-exact-active"

    Configure de manière globale la classe active par défaut de <router-link> lors d'une correspondance exacte. Voir aussi router-link.

# scrollBehavior

  • type : Function

    Signature :

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

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

    Pour plus de détails, voir Comportement du Scroll.

# parseQuery / stringifyQuery

  • type : Function

    Permettent de spécifier des fonctions personnalisées pour formater en objet ou en chaîne de caractères la requête. Surcharge les fonctions par défaut.

# fallback

  • type : boolean

    Contrôle comment le routeur devrait passer en mode hash quand le navigateur ne supporte pas history.pushState. Par défaut à true.

    Passer cette valeur à false va essentiellement faire que la navigation via router-link va réclamer un rechargement de page dans IE9. Ceci est utile quand l'application est rendue côté serveur et à besoin de fonctionner dans IE9, car le mode hash ne fonctionne pas avec du SSR.

# L'instance du routeur

# router.app

  • type: instance de Vue

L'instance racine de Vue dans laquelle l'instance de routeur a été injectée.

# router.mode

  • type: string

    Le mode que le routeur utilise.

# router.currentRoute

  • type: Route

    La route actuelle représentée en tant qu'un objet route.

# Méthodes

# router.beforeEach

# router.beforeResolve

# router.afterEach

Ajout des interceptions globales de navigation. Voir les Intercepteurs de navigation.

Dans la version 2.5.0+, ces trois méthodes retournent une fonction qui enlève les fonctions d'interception et hooks enregistrés.

# router.push

# router.replace

# router.go

# router.back

# router.forward

Navigue à une nouvelle URL de façon programmée. Voir Navigation de façon programmée.

# router.getMatchedComponents

Retourne un tableau de composants (définition/constructeur et non les instances) correspondant à la location passée en paramètre, ou alors de la route actuelle. Cette fonction est principalement utilisée pendant le rendu côté serveur afin d'effectuer une prérécupération des données.

# router.resolve

Inverse la résolution d'URL. La location doit avoir la même forme qu'utilisée dans <router-link>, retourne un objet avec les propriétés suivantes :

{
  location: Location
  route: Route
  href: string
}
  • current is the current Route by default (most of the time you don't need to change this)
  • append allows you to append the path to the current route (as with router-link)

# router.addRoutes

Permet d'ajouter dynamiquement des routes au routeur. L'argument doit être un tableau utilisant le même format de configuration que l'option routes du constructeur.

# router.onReady

Cette méthode met en file d'attente une fonction de rappel qui sera appelée lorsque le routeur aura complété la navigation initiale, ce qui signifie qu'il a résolu tous les hooks d'entrées asynchrones et composants asynchrones qui sont associés à la route initiale.

C'est utile pendant un rendu côté serveur pour assurer une sortie consistance sur le serveur et le client.

Le deuxième argument errorCallback est uniquement supporté à partir de la version 2.4. Il sera appelé lorsque la résolution de la route initiale résultera en une erreur (ex. : la résolution d'un composant asynchrone qui a échoué).

# router.onError

Enregistre une fonction de rappel qui sera appelée lorsqu'une erreur sera capturée pendant la navigation vers une route. Notez que pour qu'une erreur soit appelée, cela doit correspondre à l'un des scénarios suivants :

  • L'erreur est lancée de manière synchrone à l'intérieur d'une fonction d'interception de route ;

  • L'erreur est capturée et traitée de manière asynchrone en appelant next(err) à l'intérieur d'une fonction d'interception de route ;

  • Une erreur est survenue pendant la résolution d'un composant asynchrone qui est requis pour faire le rendu d'une route.

# L'objet Route

Un objet Route représente l'état actuel de la route active. Il contient des informations analysées à propos de l'URL courant et les itinéraires de route appariés par l'URL.

L'objet Route est immutable. Chaque navigation qui se déroule avec succès résultera en un nouvel objet Route.

L'objet Route peut être trouvé à plusieurs endroits :

  • À l'intérieur des composants en tant que this.$route

  • À l'intérieur des fonctions de rappel des observateurs de $route

  • Comme valeur de retour après l'appel de router.match(location)

  • À l'intérieur des fonctions d'interception de la navigation, dans les deux premiers paramètres de la fonction :

    router.beforeEach((to, from, next) => {
  // `to` et `from` sont tous les deux des objets Route
})

  • À l'intérieur de la fonction scrollBehavior dans les deux premiers arguments :

    const router = new VueRouter({
  scrollBehavior(to, from, savedPosition) {
    // `to` et `from` sont tous les deux des objets Route
  }
})

# Propriétés de l'objet Route

  • $route.path

    • type : string

      Une chaine de caractères représentant le chemin de la route en cours, toujours résolue en tant que chemin absolu, ex : "/foo/bar".

  • $route.params

    • type : Object

      Un objet qui contient des pairs clé/valeur de segments dynamiques et segments star. S'il n'y a pas de paramètres, alors la valeur sera un objet vide.

  • $route.query

    • type : Object

      Un objet qui contient des pairs clé/valeur de la requête au format d'une chaine de caractères. Par exemple, pour un chemin /foo?user=1, on aura $route.query.user == 1. S'il n'y a pas de requête, alors la valeur sera un objet vide.

  • $route.hash

    • type : string

      Le hash de la route courante (avec le #), s'il y en a un. S'il n'y a pas de hash, alors la valeur sera une chaine de caractères vide.

  • $route.fullPath

    • type : string

      L'URL entièrement résolu, incluant la requête et le hash.

  • $route.matched

    • type : Array<RouteRecord>

      Un Array contenant les les itinéraires de la route pour chaque segment de chemin imbriqué de la route courante. Les itinéraires de la route sont des copies des objets dans le tableau de configuration routes (et dans les tableaux children).

    const router = new VueRouter({
  routes: [
    // l'objet qui suit est un itinéraire de route
    {
      path: '/foo',
      component: Foo,
      children: [
        // c'est aussi un itinéraire
        { path: 'bar', component: Bar }
      ]
    }
  ]
})

    Lorsque l'URL sera /foo/bar, $route.matched sera un Array contenant les deux objets (clonés), dans l'ordre parent à l'enfant.

  • $route.name

    Le nom de la route courante, si elle en a un. (Voir Routes nommées).

  • $route.redirectedFrom

    Le nom de la route d'où la page a été redirigée, si elle en a un. (Voir Redirection et alias).

# Injections de composant

# Propriétés injectées

Ces propriétés sont injectées dans chacun des composants enfants, en passant l'instance du routeur à l'application racine de Vue en tant qu'option router.

  • $router

    L'instance du routeur.

  • $route

La Route actuellement active. C'est une propriété en lecture seule et ses propriétés sont immutables, mais elles restent malgré tout observables.

# Options activées