Système de route par fichier

Nuxt.js s'occupe de générer automatiquement la configuration pour vue-router en fonction de l'arborescence des fichiers Vue à l'intérieur du répertoire des pages. Il suffit de créer un fichier .vue à l'intérieur du répertoire des pages pour que le routage soit fonctionnel, nul besoin de configuration.

Parfois nous aurons besoin de créer une route dynamique ou une route imbriquée ou encore de configurer notre router de manière plus poussée. Ce chapitre a pour but de tout passer en revue afin de tirer le maximum de notre routeur.

Nuxt.js nous offre du code splitting automatique pour nos routes, sans configuration supplémentaire.

Utilisez le composant NuxtLink pour naviguer entre les pages.

<template>
  <nuxt-link to="/">Page d'accueil</nuxt-link>
</template>

Routes Basiques

Cette structure de fichier:

pages/
--| user/
-----| index.vue
-----| one.vue
--| index.vue

va automatiquement générer ceci:

router: {
  routes: [
    {
      name: 'index',
      path: '/',
      component: 'pages/index.vue'
    },
    {
      name: 'user',
      path: '/user',
      component: 'pages/user/index.vue'
    },
    {
      name: 'user-one',
      path: '/user/one',
      component: 'pages/user/one.vue'
    }
  ]
}

Routes Dynamiques

Parfois il n'est pas possible de connaître le nom de la route. Un call vers une API pour récupérer une liste d'utilisateurs ou d'articles de blog par exemple. C'est ce que l'on appelle des routes dynamiques. Pour créer une route dynamique, il faut ajouter un underscore avant le nom du fichier .vue ou devant le nom du répertoire. Nous pouvons nommer le fichier ou le répertoire de la façon dont nous voulons mais il doit être préfixé d'un underscore.

Cette structure de fichiers:

pages/
--| _slug/
-----| comments.vue
-----| index.vue
--| users/
-----| _id.vue
--| index.vue

va automatiquement générer ceci:

router: {
  routes: [
    {
      name: 'index',
      path: '/',
      component: 'pages/index.vue'
    },
    {
      name: 'users-id',
      path: '/users/:id?',
      component: 'pages/users/_id.vue'
    },
    {
      name: 'slug',
      path: '/:slug',
      component: 'pages/_slug/index.vue'
    },
    {
      name: 'slug-comments',
      path: '/:slug/comments',
      component: 'pages/_slug/comments.vue'
    }
  ]
}

Comme nous pouvons le voir, la route nommée users-id a la valeur :id? dans son chemin, ce qui en fait une valeur optionnelle. Si nous souhaitons rendre ce paramètre obligatoire, il faut créer un fichier index.vue dans le répertoire users/_id.

Depuis Nuxt >= v2.13, un crawler va détecter nos liens et générer des routes dynamiques à partir de ceux-ci. Cependant, si nous avons des pages qui ne sont pas liées (comme une page secrète), nous aurons besoin de spécifier manuellement que nous souhaitons générer cette route dynamique.

Générer des routes dynamiques pour des sites statiques.

Accéder aux paramètres de la route localement

Nous pouvons accéder aux paramètres de la route actuelle, depuis notre page locale ou notre composant en appelant this.$route.params.{nomDuParamètre}. Par exemple, si nous avons une page dynamique avec la liste de nos utilisateurs (users\_id.vue), nous pouvons accéder au paramètre id pour charger un utilisateur en particulier, pour cela nous pouvons utiliser: this.$route.params.id.

Routes Imbriquées

Nuxt.js nous permet de créer des routes imbriquées grâce à vue-router. Pour définir le composant parent d'une route imbriquée, nous avons besoin de créer un fichier Vue du même nom que le répertoire qui va contenir les vues imbriquées.

Il ne faut pas oublier d'inclure le composant NuxtChild à l'intérieur du composant parent (fichier .vue).

Cette structure de fichiers:

pages/
--| users/
-----| _id.vue
-----| index.vue
--| users.vue

va automatiquement générer ceci:

router: {
  routes: [
    {
      path: '/users',
      component: 'pages/users.vue',
      children: [
        {
          path: '',
          component: 'pages/users/index.vue',
          name: 'users'
        },
        {
          path: ':id',
          component: 'pages/users/_id.vue',
          name: 'users-id'
        }
      ]
    }
  ]
}

Routes dynamiques imbriquées

Ce n'est pas très commun mais il se peut que nous ayons envie d'avoir des enfants dynamiques dans des parents dynamiques, c'est possible avec Nuxt.js.

Cette structure de fichiers:

pages/
--| _category/
-----| _subCategory/
--------| _id.vue
--------| index.vue
-----| _subCategory.vue
-----| index.vue
--| _category.vue
--| index.vue

va automatiquement générer ceci:

router: {
  routes: [
    {
      path: '/',
      component: 'pages/index.vue',
      name: 'index'
    },
    {
      path: '/:category',
      component: 'pages/_category.vue',
      children: [
        {
          path: '',
          component: 'pages/_category/index.vue',
          name: 'category'
        },
        {
          path: ':subCategory',
          component: 'pages/_category/_subCategory.vue',
          children: [
            {
              path: '',
              component: 'pages/_category/_subCategory/index.vue',
              name: 'category-subCategory'
            },
            {
              path: ':id',
              component: 'pages/_category/_subCategory/_id.vue',
              name: 'category-subCategory-id'
            }
          ]
        }
      ]
    }
  ]
}

Routes dynamiques imbriquées inconnues

Si nous ne connaissons pas la profondeur d'une URL, nous pouvons utiliser _.vue pour dynamiquement faire correspondre les chemins imbriqués. Cela va matcher tant qu'il n'y a pas de requête plus spécifique.

Cette structure de fichiers:

pages/
--| people/
-----| _id.vue
-----| index.vue
--| _.vue
--| index.vue

va automatiquement générer ceci:

/ -> index.vue
/people -> people/index.vue
/people/123 -> people/_id.vue
/about -> _.vue
/about/careers -> _.vue
/about/careers/chicago -> _.vue

Gérer les pages 404 ne fait pas partie du travail d'une page _.vue.

Personnaliser le routeur

Il y a plusieurs façons de personnaliser notre routeur avec Nuxt:

La propriété router

La propriété router nous permet de personnaliser le routeur Nuxt.js (vue-router).

nuxt.config.js
export default {
  router: {
    // personnalisons le routeur de Nuxt.js
  }
}

Base:

L'url de base de notre application. Par exemple, si nous voulons que notre Single Page App soit sous le chemin /app/, alors nous devons lui attribuer la valeur 'app/'.

extendRoutes

Nous voulons peut-être personnaliser les routes créées par Nuxt.js, pour cela nous pouvons utiliser l'option extendRoutes.

Exemple d'ajout d'une route personnalisée:

nuxt.config.js
export default {
  router: {
    extendRoutes(routes, resolve) {
      routes.push({
        name: 'custom',
        path: '*',
        component: resolve(__dirname, 'pages/404.vue')
      })
    }
  }
}

Si nous souhaitons trier nos routes, nous pouvons utiliser la fonction sortRoutes(routes) à partir de @nuxt/utils:

nuxt.config.js
import { sortRoutes } from '@nuxt/utils'
export default {
  router: {
    extendRoutes(routes, resolve) {
      // ajouter nos routes ici ...

      // trions-les
      sortRoutes(routes)
    }
  }
}

Les routes doivent respecter le schéma du vue-router.

Lorsque l'on ajoute les routes qui utilisent des routes nommées, il ne faut pas oublier d'ajouter les chunkNames des components.

nuxt.config.js
export default {
  router: {
    extendRoutes(routes, resolve) {
      routes.push({
        path: '/users/:id',
        components: {
          default: resolve(__dirname, 'pages/users'), // ou routes[index].component
          modal: resolve(__dirname, 'components/modal.vue')
        },
        chunkNames: {
          modal: 'components/modal'
        }
      })
    }
  }
}

fallback

S'occupe du routeur, si ce dernier doit se rabattre en mode hash lorsque le navigateur ne supporte pas history.pushState alors que le mode est configuré sur history.

mode

Nous pouvons changer le mode du routeur, ce n'est cependant pas recommandé en raison du Server Side Rendering (SSR).

parseQuery / stringifyQuery

Fournit des fonctions de parsing / stringification personnalisées.

routeNameSplitter

Nous pourrions vouloir changer le séparateur entre les noms des routes que Nuxt.js utilise, pour cela nous pouvons utiliser l'option routeNameSplitter dans notre fichier de configuration. Prenons par exemple le fichier page pages/posts/_id.vue. Nuxt.js va générer le nom de la route de manière programmatique, ici ce sera posts-id. Passer le routeNameSplitter à / va changer le nom en posts/id.

nuxt.config.js
export default {
  router: {
    routeNameSplitter: '/'
  }
}

scrollBehavior

L'option scrollBehavior nous laisse le choix pour définir un comportement personnalisé pour la position du défilement entre les routes. Cette méthode est appelée à chaque fois qu'une page est render.

Pour plus d'informations, veuillez consulter la documentation sur le scrollBehavior de vue-router.

Disponible depuis la version 2.9.0:

Dans Nuxt.js, nous pouvons utiliser un fichier pour écraser le scrollBehavior du routeur. Ce fichier doit être placé dans le répertoire app.

~/app/router.scrollBehavior.js.

Un exemple de comment forcer la position du défilement à se retrouver tout en haut pour chaque route:

app/router.scrollBehavior.js
export default function (to, from, savedPosition) {
  return { x: 0, y: 0 }
}

trailingSlash

Disponible depuis la version 2.10:

Si cette option est passée à true, des slashs traînants seront suffixés pour chaque route. Sinon, ils seront enlevés.

nuxt.config.js
export default {
  router: {
    trailingSlash: true
  }
}

Cette option doit être changée avec une certaine préparation et une sequence de tests conséquents. Lorsque l'on définit router.trailingSlash a quelque chose d'autre que la valeur par défaut (undefined), la route opposée cessera de fonctionner. Il doit donc y avoir des redirections 301 et nos liens internes doivent s'adapter eux aussi. Si nous passons trailingSlash à true, alors seulement example.com/abc/ vont marcher mais pas example.com/abc. Dans le cas d'un false, c'est l'inverse.

Contributeurs

Vous avez vu une erreur ou vous souhaitez contribuer à la documentation ? Éditez cette page sur GitHub !