L'API History et le principe des applications monopage

1. Objectifs

   • Comprendre la différence entre un site classique et une application monopage (SPA).
   • Manipuler l'historique du navigateur avec pushState(), replaceState() et l'événement popstate.
   • Écrire un petit routeur en JavaScript et configurer le serveur qui l'héberge.
   • Découvrir la Navigation API, la remplaçante moderne de l'API History.

2. Site classique et application monopage

   • Dans un site classique (multi-pages), chaque clic sur un lien demande une nouvelle page HTML au serveur : la page entière est rechargée, l'écran blanchit un instant et l'état de JavaScript (variables, formulaire en cours) est perdu.
   • Dans une application monopage (Single Page Application, SPA), le navigateur charge une seule page HTML. Ensuite, JavaScript intercepte les clics et remplace seulement le contenu qui change. Les données manquantes sont demandées avec fetch.
   • Avantages : navigation instantanée, transitions fluides, état conservé (lecteur audio qui continue, panier…). Inconvénients : premier chargement plus lourd, référencement et accessibilité à soigner.
   • C'est le fonctionnement d'Angular, React et Vue (chapitre 24), de Gmail ou de YouTube. Leurs routeurs (Angular Router, React Router, Vue Router) reposent sur ce que vous allez apprendre ici.

   

3. Le défi : garder des adresses qui fonctionnent

   • Si l'on se contente de changer le contenu avec JavaScript, l'adresse ne bouge pas. Résultat : impossible de mettre une page en favori, de partager un lien, ou d'utiliser les boutons Précédent et Suivant.
   • L'API History (objet history) permet de modifier l'adresse et l'historique sans recharger la page.

4. Les outils de l'API History

Instruction	Effet
history.pushState(etat, "", url)	Ajoute une entrée à l'historique et affiche url dans la barre d'adresse, sans recharger ni contacter le serveur.
history.replaceState(etat, "", url)	Remplace l'entrée actuelle (pratique pour mettre à jour un filtre dans l'adresse sans créer une entrée à chaque frappe).
history.state	L'objet etat associé à l'entrée actuelle.
history.back(), forward(), go(-2)	Équivalent des boutons du navigateur.
Événement popstate (sur window)	Déclenché quand l'utilisateur utilise Précédent / Suivant; event.state contient l'objet enregistré.

• Le 2^e paramètre (titre) est ignoré par les navigateurs : on passe "".
• L'url doit être de la même origine (même domaine) que la page.
• pushState() ne déclenche pas popstate: c'est à vous d'afficher le nouveau contenu.
• etat doit rester petit et « clonable » (nombres, textes, objets simples) : pas de fonctions ni d'éléments du DOM.

5. Exemple complet : un mini-routeur

Le site d'un centre de formation avec quatre types de pages : accueil, liste des formations, fiche d'une formation (/formations/2) et contact, plus une page 404.

index.html:

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <title>Centre de formation</title>
    <script type="module" src="/routeur.js"></script>
  </head>
  <body>
    <nav>
      <a href="/" data-lien>Accueil</a> |
      <a href="/formations" data-lien>Formations</a> |
      <a href="/contact" data-lien>Contact</a>
    </nav>
    <main id="app"></main>
  </body>
</html>

routeur.js:

const app = document.getElementById("app");

const formations = ["Développement web", "Développement mobile", "Réseaux"];

// Une "page" = une fonction qui construit le contenu
const routes = {
  "/": () => creer("h1", "Bienvenue au centre de formation"),
  "/formations": () => {
    const ul = document.createElement("ul");
    formations.forEach((nom, i) => {
      const li = document.createElement("li");
      const lien = creer("a", nom);
      lien.href = `/formations/${i + 1}`;
      lien.dataset.lien = "";
      li.append(lien);
      ul.append(li);
    });
    return [creer("h1", "Nos formations"), ul];
  },
  "/contact": () => creer("h1", "Contact : contact@centre.tn"),
};

function creer(balise, texte) {
  const element = document.createElement(balise);
  element.textContent = texte;
  return element;
}

function pageFormation(numero) {
  const nom = formations[numero - 1];
  return nom ? [creer("h1", nom), creer("p", `Fiche de la formation n° ${numero}.`)] : null;
}

function afficher(chemin) {
  const detail = chemin.match(/^\/formations\/(\d+)$/);
  const contenu = detail ? pageFormation(Number(detail[1])) : routes[chemin]?.();
  app.replaceChildren(...[contenu ?? creer("h1", "404 – Page introuvable")].flat());
  document.title = `${app.querySelector("h1").textContent} – Centre`;
}

function naviguer(chemin) {
  if (chemin !== location.pathname) {
    history.pushState({ chemin }, "", chemin);
  }
  afficher(chemin);
}

// Délégation : un seul écouteur pour tous les liens marqués data-lien
document.addEventListener("click", (event) => {
  const lien = event.target.closest("a[data-lien]");
  if (lien) {
    event.preventDefault();
    naviguer(lien.getAttribute("href"));
  }
});

// Boutons Précédent / Suivant
window.addEventListener("popstate", () => afficher(location.pathname));

// Premier affichage (y compris si l'utilisateur arrive directement sur /contact)
afficher(location.pathname);

• Table des routes: chaque adresse est associée à une fonction qui construit le contenu (avec createElement et textContent, sans innerHTML).
• Route avec paramètre: /formations/2 est reconnue par l'expression régulière /^\/formations\/(\d+)$/, qui capture le numéro.
• Délégation: un seul écouteur sur document intercepte tous les liens marqués data-lien, même ceux créés plus tard (liens de la liste des formations). Les autres liens (sites externes) gardent leur comportement normal.
• popstate: aux boutons Précédent / Suivant, on réaffiche simplement la page correspondant à location.pathname.
• Premier affichage: afficher(location.pathname) au chargement permet d'arriver directement sur /contact depuis un favori.
• Le titre de l'onglet est mis à jour à chaque page, ce qui aide l'historique, les favoris et les lecteurs d'écran.

# Petit serveur de test : renvoie index.html pour toute adresse sans extension
import http.server, os
class Spa(http.server.SimpleHTTPRequestHandler):
    def send_head(self):
        if "." not in os.path.basename(self.path.split("?")[0]):
            self.path = "/index.html"
        return super().send_head()
http.server.ThreadingHTTPServer(("127.0.0.1", 8000), Spa).serve_forever()

# Nginx
location / {
    try_files $uri $uri/ /index.html;
}

# Apache (fichier .htaccess)
FallbackResource /index.html

// Même routeur avec la Navigation API (Baseline depuis janvier 2026)
navigation.addEventListener("navigate", (event) => {
  const url = new URL(event.destination.url);
  if (!event.canIntercept || url.origin !== location.origin) {
    return; // lien externe, téléchargement… : comportement normal
  }
  event.intercept({
    handler() {
      afficher(url.pathname);
    },
  });
});

Activité 1 : tester le routeur

• Dans le dossier spa de votre dépôt js-api-navigateur, reproduisez l'exemple et lancez python serveur.py.
• Naviguez entre les pages et ouvrez la console : tapez history.length après chaque clic. Utilisez Précédent et Suivant.
• Lancez la même page avec Live Server, allez sur « Contact » et appuyez sur F5. Expliquez l'erreur.

Activité 2 : compléter le routeur

• Ajoutez une page /a-propos et un lien dans le menu.
• Ajoutez la classe active au lien du menu correspondant à la page affichée.
• Remplacez la liste formations par un fichier formations.json chargé avec fetch, en affichant « Chargement… » pendant la requête.

Activité 3 : filtre dans l'adresse

• Sur la page des formations, ajoutez un champ de recherche. À chaque saisie, filtrez la liste et mettez à jour l'adresse en /formations?q=web avec replaceState().
• Vérifiez qu'en ouvrant directement cette adresse, le champ est prérempli et la liste filtrée (URLSearchParams). Pourquoi utilise-t-on replaceState() plutôt que pushState() ici ?

Activité 4 : version hash

• Adaptez le routeur au routage par hash (#/formations), puis vérifiez qu'il fonctionne avec Live Server, y compris après F5.