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

CKTIS / HTML

onstorage — gérer les modifications de Web Storage

L’attribut onstorage sur body définit le gestionnaire Window de l’événement storage. Il permet de réagir aux modifications de localStorage ou sessionStorage partagés effectuées dans un autre document, et non dans celui qui réalise l’écriture.

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

Syntaxe

<body onstorage="handleStorage(event)">…</body>
window.onstorage = handleStorage;

onstorage est un attribut de gestionnaire d’événement sur body, et non un attribut global. Sa valeur contient du code JavaScript avec le paramètre event disponible. Il gère l’événement storage de l’objet Window, et non un événement ciblant body lui-même. Son équivalent JavaScript est window.onstorage ; l’affectation d’une nouvelle fonction remplace le gestionnaire existant, et l’affectation de null le supprime.

Une véritable modification du stockage notifie de façon asynchrone les autres documents qui partagent cet espace de stockage, mais pas le document qui effectue l’écriture. Pour localStorage, il peut s’agir d’autres onglets de la même origine. Pour sessionStorage, ils doivent aussi appartenir au même contexte de navigation de premier niveau, par exemple des cadres dans le même onglet. Écrire une valeur identique ne déclenche aucune notification.

Le StorageEvent expose key, oldValue, newValue, l’url du document qui effectue la modification et storageArea. Pour une nouvelle clé, oldValue vaut null ; pour une clé supprimée, newValue vaut null ; et clear() définit les trois champs de données sur null. Une opération qui ne change rien n’envoie aucune notification.

L’exemple déclenche un événement synthétique sans modifier le stockage afin de montrer le fonctionnement de l’attribut de manière déterministe. Il ne teste pas la communication entre documents. Son exécution nécessite que JavaScript soit activé et que les gestionnaires d’événements inline soient autorisés.

Exemples

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>onstorage demo</title>
<body onstorage="document.getElementById('result').textContent = event.key + ': ' + event.oldValue + ' -> ' + event.newValue">
<pre id="result">Waiting</pre>
<script>
window.dispatchEvent(new StorageEvent('storage', {
  key: 'theme',
  oldValue: 'light',
  newValue: 'dark'
}));
</script>
</body>
</html>

Résultat

theme: light -> dark

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