Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / HTML

onpopstate — gérer les changements de l’entrée d’historique active

L’attribut onpopstate de body définit le gestionnaire de l’événement popstate de l’objet Window. Il permet à une page de réagir au parcours de l’historique de session, par exemple avec Précédent et Suivant, et de lire l’état de l’entrée de destination.

Version : WHATWG HTML Living Standard; index snapshot date recorded separately

Syntaxe

<body onpopstate="handleState(event)">
window.onpopstate = handleState;

onpopstate est un attribut de gestionnaire d’événement disponible sur body, et non un attribut global pour n’importe quel élément. Il expose le gestionnaire popstate de l’objet Window. L’affectation window.onpopstate = handleState définit ce même gestionnaire ; elle ne crée pas un second écouteur indépendant.

popstate est lié au parcours de l’historique de session, par exemple avec Précédent, Suivant ou history.back(). Le simple appel de history.pushState() ou de history.replaceState() ne déclenche pas cet événement. Dans le gestionnaire, event.state contient l’état restauré de l’entrée de destination. Il peut être null : il faut en tenir compte avant d’accéder à ses propriétés.

Une affectation ultérieure à window.onpopstate remplace le gestionnaire précédent, et l’affectation de null le supprime. Pour utiliser des gestionnaires indépendants, faites appel à window.addEventListener('popstate', handleState). Ne considérez pas popstate comme un moyen d’annuler la navigation.

L’exemple déclenche volontairement un événement synthétique PopStateEvent avec un état fixe. Il vérifie le lien entre l’attribut et Window, mais ne modifie pas l’historique et ne teste pas un véritable parcours de celui-ci. La CSP d’une application peut bloquer les attributs de gestionnaire inline ; dans ce cas, enregistrez le gestionnaire dans un script autorisé.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>onpopstate demo</title>
</head>
<body onpopstate="document.getElementById('result').textContent = 'step=' + event.state.step">
  <button id="test" type="button">Test</button>
  <output id="result">Ready</output>
  <script>
    document.getElementById('test').addEventListener('click', () => {
      window.dispatchEvent(new PopStateEvent('popstate', {
        state: { step: 1 }
      }));
    });
  </script>
</body>
</html>

Résultat

step=1

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources