API History
Baseline
Large disponibilité
Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.
L'API History fournit un accès à l'historique de session du navigateur (à ne pas confondre avec l'historique des WebExtensions) depuis l'objet global history. Elle expose des méthodes et des propriétés utiles qui vous permettent de naviguer en avant et en arrière dans l'historique de l'utilisateur·ice, et de manipuler le contenu de la pile d'historique.
Concepts et utilisation
La navigation en avant et en arrière dans l'historique de l'utilisateur·ice se fait à l'aide des méthodes back(), forward() et go().
Naviguer en avant et en arrière
Pour revenir en arrière dans l'historique :
history.back();
Cela agit exactement comme si l'utilisateur·ice clique sur le bouton Précédent de la barre d'outils de son navigateur.
De même, vous pouvez avancer dans l'historique (comme si l'utilisateur·ice clique sur le bouton Suivant), comme ceci :
history.forward();
Se déplacer vers un point spécifique dans l'historique
Vous pouvez utiliser la méthode go() pour charger une page spécifique à partir de l'historique de session, identifiée par sa position relative par rapport à la page actuelle. (La position relative de la page actuelle est 0.)
Pour revenir d'une page en arrière (l'équivalent d'appeler back()) :
history.go(-1);
Pour avancer d'une page, comme avec l'appel de forward() :
history.go(1);
De même, vous pouvez avancer de 2 pages en passant 2, et ainsi de suite.
Une autre utilisation de la méthode go() consiste à actualiser la page actuelle en passant soit 0, soit en l'invoquant sans argument :
// Les instructions suivantes
// ont tous deux pour effet de
// actualiser la page
history.go(0);
history.go();
Vous pouvez déterminer le nombre de pages dans la pile d'historique en regardant la valeur de la propriété length :
const nombreEntrees = history.length;
Interfaces
History-
Permet de manipuler l'historique de session du navigateur (c'est‑à‑dire les pages visitées dans l'onglet ou le cadre où la page actuelle est chargée).
PopStateEvent-
L'interface de l'évènement
popstate.
Exemples
L'exemple suivant ajoute un écouteur pour l'évènement popstate. Il illustre ensuite certaines des méthodes de l'objet history pour ajouter, remplacer et naviguer dans l'historique du navigateur de l'onglet courant.
window.addEventListener("popstate", (event) => {
alert(
`location: ${document.location}, state: ${JSON.stringify(event.state)}`,
);
});
history.pushState({ page: 1 }, "titre 1", "?page=1");
history.pushState({ page: 2 }, "titre 2", "?page=2");
history.replaceState({ page: 3 }, "titre 3", "?page=3");
history.back(); // alertes "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // alertes "location: http://example.com/example.html, state: null"
history.go(2); // alertes "location: http://example.com/example.html?page=3, state: {"page":3}"
Spécifications
| Spécification |
|---|
| HTML # the-history-interface |