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

CKTIS / JavaScript

history.replaceState — mettre à jour l’entrée d’historique actuelle

history.replaceState met à jour l’état et, facultativement, l’URL de l’entrée d’historique actuelle sans recharger la page. Il n’ajoute pas d’entrée et ne crée donc pas d’étape supplémentaire pour le bouton Retour.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

history.replaceState(data, unused)
history.replaceState(data, unused, url)

history.replaceState(data, unused, url) remplace l’état de l’entrée actuelle ; history.pushState ajoute une entrée. Il s’agit d’une API de navigateur définie par HTML, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. La présence de Node 24 ne prouve pas sa disponibilité dans un navigateur.

Passez "" comme argument historique unused, qui est obligatoire ; il ne définit pas le titre. Si url est omis, l’adresse reste inchangée. La méthode renvoie undefined. Elle ne recharge pas le document et ne déclenche pas elle-même popstate ni hashchange.

data est cloné de manière structurée pour être stocké, et non sérialisé en JSON. Lisez la valeur enregistrée avec history.state ; modifier ensuite l’objet d’entrée ne modifie pas la valeur stockée. Les fonctions et les nœuds DOM ne peuvent pas être stockés ainsi et provoquent DataCloneError.

Les règles de réécriture comparent l’URL proposée à l’URL actuelle du document, et non à son origine. Par exemple, un document à l’adresse about:blank peut modifier le fragment de son URL même s’il hérite de son origine. Une URL interdite, un document qui n’est pas pleinement actif ou des restrictions sur la fréquence des appels peuvent provoquer SecurityError. Utilisez cette méthode pour corriger la vue actuelle, et non pour créer une nouvelle étape de navigation.

Exemples

(() => {
  const previousState = history.state;
  const previousURL = location.href;
  const previousLength = history.length;
  const data = { tab: "details" };
  const url = new URL(location.href);
  url.hash = "details";

  try {
    history.replaceState(data, "", url.href);
    data.tab = "changed";
    console.log(history.state.tab);
    console.log(location.hash);
    console.log(history.length === previousLength);
  } finally {
    history.replaceState(previousState, "", previousURL);
  }
})();

Résultat

details
#details
true

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