History : méthode pushState()

Syntaxe

pushState(state, unused)
pushState(state, unused, url)

Paramètres

state

L'objet state est un objet JavaScript qui est associé à la nouvelle entrée de l'historique créée par pushState(). Chaque fois que l'utilisateur·ice navigue vers le nouveau state, un évènement popstate est déclenché, et la propriété state de l'évènement contient une copie de l'objet state de l'entrée de l'historique.

L'objet state peut être n'importe quoi qui peut être sérialisé.

Note : Comme certains navigateurs enregistrent les objets state sur le disque de l'utilisateur·ice afin qu'ils puissent être restaurés après le redémarrage du navigateur par l'utilisateur·ice, et imposent une limite de taille sur la représentation sérialisée d'un objet state, une exception est levée si vous passez un objet state dont la représentation sérialisée est plus grande que cette limite de taille. Donc, dans les cas où vous voulez vous assurer d'avoir plus d'espace que ce que certains navigateurs peuvent imposer, il est recommandé d'utiliser sessionStorage et/ou localStorage.

unused

Ce paramètre existe pour des raisons historiques et ne peut pas être omis ; passer une chaîne de caractères vide est sûr par rapport aux futures modifications de la méthode.

url Facultatif

L'URL de la nouvelle entrée de l'historique. Notez que le navigateur n'essaie pas de charger cette URL après un appel à pushState(), mais il peut tenter de charger l'URL plus tard, par exemple après que l'utilisateur·ice ait redémarré le navigateur. La nouvelle URL n'a pas besoin d'être absolue : si elle est relative, elle est résolue par rapport à l'URL actuelle. La nouvelle URL doit être de la même origine que l'URL actuelle ; sinon, pushState() lève une exception. Si ce paramètre n'est pas défini, il est défini sur l'URL actuelle du document.

Valeur de retour

Aucune (undefined).

Exceptions

SecurityError DOMException

Levée si le document associé n'est pas entièrement actif, si le paramètre url fourni n'est pas une URL valide, ou si la méthode est appelée trop fréquemment.

DataCloneError DOMException

Levée si le paramètre state fourni ne peut pas être sérialisé.

Description

Dans un certain sens, appeler pushState() est similaire à définir window.location = "#toto", en ce que les deux créent et activent également une autre entrée de l'historique associée au document actuel. Mais pushState() présente quelques avantages :

• La nouvelle URL peut être n'importe quelle URL dans la même origine que l'URL actuelle. En revanche, définir window.location vous maintient au même document uniquement si vous ne modifiez que le fragment.
• Modifier l'URL de la page est optionnel. En revanche, définir window.location = "#toto"; ne crée une nouvelle entrée de l'historique que si le fragment actuel n'est pas #toto.
• Vous pouvez associer des données arbitraires à votre nouvelle entrée de l'historique. Avec l'approche basée sur le fragment, vous devez encoder toutes les données pertinentes dans une courte chaîne de caractères.

Notez que pushState() ne déclenche jamais un évènement hashchange, même si la nouvelle URL diffère de l'ancienne URL uniquement par son fragment.

Exemples

Cela crée une nouvelle entrée de l'historique du navigateur en définissant l'état et l'url.

JavaScript

const etat = { page_id: 1, user_id: 5 };
const url = "bonjour-le-monde.html";

history.pushState(etat, "", url);

Modifier un paramètre de requête

const url = new URL(location);
url.searchParams.set("toto", "truc");
history.pushState({}, "", url);

Spécifications

Compatibilité des navigateurs

Voir aussi

• Travailler avec l'API History
• Window : évènement popstate