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.