API Storage JavaScript

Introduction à l'API Storage

En développement web moderne, gérer les données efficacement est essentiel. La Web Storage API de JavaScript offre un moyen simple et synchrone de stocker des paires clé/valeur directement dans le navigateur — sans aller-retour avec le serveur. C'est l'outil le plus courant pour mémoriser les préférences utilisateur, mettre en cache de petites quantités de données et conserver l'état de l'interface entre les rechargements de page.

Ce guide couvre les deux objets de stockage exposés par l'API — localStorage et sessionStorage — ainsi que l'ensemble des méthodes disponibles, la façon de stocker des objects, comment réagir aux changements entre onglets, et les pièges courants. Les deux objets partagent la même interface (l'interface Storage) ; la seule différence réside dans la durée de vie des données et leur portée de partage.

Comme le Web Storage n'est jamais envoyé au serveur, il n'est pas adapté aux jetons d'authentification dont le backend a besoin — c'est le rôle des cookies.

L'interface Storage

Chaque valeur dans le Web Storage est une string. localStorage et sessionStorage exposent tous les deux les mêmes cinq méthodes ainsi qu'une propriété length :

Les exemples ci-dessous utilisent localStorage, mais chaque méthode fonctionne de manière identique sur sessionStorage.

Comprendre localStorage

localStorage stocke les données sans date d'expiration. Les données persistent même après la fermeture et la réouverture de la fenêtre du navigateur, ce qui le rend idéal pour des données de longue durée telles que les préférences utilisateur, un choix de thème ou un brouillon de formulaire.

Stocker des données dans localStorage

Pour stocker des données, utilisez la méthode setItem avec une clé et une valeur :

// Storing data in localStorage
localStorage.setItem('username', 'JohnDoe');

Les deux arguments sont convertis en strings. Écrire setItem('count', 5) stocke en réalité la string "5", pensez donc à reconvertir lors de la lecture.

Récupérer des données depuis localStorage

Utilisez getItem pour lire une valeur. Si la clé n'existe pas, vous obtenez null (et non undefined) :

// Retrieving data from localStorage
const username = localStorage.getItem('username');
console.log(username);                 // "JohnDoe"
console.log(localStorage.getItem('missing')); // null

Supprimer des données de localStorage

Supprimez une clé unique avec removeItem, ou effacez tout pour l'origine avec clear :

// Remove one key
localStorage.removeItem('username');

// Remove every key for this origin
localStorage.clear();

clear() n'affecte que l'origine courante (schéma + hôte + port) ; il ne touche jamais les données d'un autre site.

Stocker des objects : JSON.stringify et JSON.parse

Les valeurs de stockage devant être des strings, vous ne pouvez pas stocker un object directement — setItem('user', {name: 'Ann'}) stockerait la string inutile "[object Object]". Sérialisez avec JSON.stringify à l'entrée et JSON.parse à la sortie :

const user = { name: 'Ann', theme: 'dark', visits: 3 };

// Save: serialize the object to a JSON string
localStorage.setItem('user', JSON.stringify(user));

// Load: parse the string back into an object
const restored = JSON.parse(localStorage.getItem('user'));
console.log(restored.theme); // "dark"
console.log(restored.visits + 1); // 4

Consultez Travailler avec JSON pour en savoir plus sur la sérialisation, et Les objects JavaScript pour les bases des objects.

Itérer sur les clés stockées

Utilisez length conjointement avec key(index) pour parcourir tout ce qui est stocké pour l'origine :

localStorage.setItem('a', '1');
localStorage.setItem('b', '2');

for (let i = 0; i < localStorage.length; i++) {
  const name = localStorage.key(i);
  console.log(`${name} = ${localStorage.getItem(name)}`);
}
// a = 1
// b = 2

Utiliser sessionStorage

sessionStorage partage la même API mais dispose d'une durée de vie plus courte, limitée à l'onglet. Les données sont effacées à la fin de la session de la page, c'est-à-dire lorsque l'onglet est fermé. Ouvrir le même site dans un deuxième onglet crée un sessionStorage distinct, de sorte que les deux onglets ne voient jamais les données de l'autre. C'est idéal pour des données qui ne doivent pas se propager entre onglets, comme la progression d'un assistant multi-étapes.

// Store, read, and remove — same methods as localStorage
sessionStorage.setItem('sessionName', 'Session1');
console.log(sessionStorage.getItem('sessionName')); // "Session1"
sessionStorage.removeItem('sessionName');

Réagir aux changements entre onglets

Lorsque localStorage est modifié dans un onglet, le navigateur déclenche un événement storage dans tous les autres onglets de la même origine (mais pas dans l'onglet qui a effectué le changement). Cela vous permet de garder plusieurs onglets synchronisés — par exemple, déconnecter l'utilisateur partout en même temps :

window.addEventListener('storage', (event) => {
  // event.key, event.oldValue, event.newValue, event.url
  if (event.key === 'theme') {
    console.log('Theme changed in another tab to', event.newValue);
  }
});

Remarque : l'événement storage ne se déclenche que pour localStorage (partagé entre les onglets), pas pour sessionStorage.

Gérer les erreurs et les limites

Les écritures peuvent lever une QuotaExceededError lorsque vous dépassez la limite de ~5 Mo, et le stockage peut être totalement indisponible en navigation privée ou lorsque les cookies sont désactivés. Enveloppez les écritures dans un try...catch et vérifiez la disponibilité avant de vous appuyer sur l'API :

function safeSet(key, value) {
  try {
    localStorage.setItem(key, value);
    return true;
  } catch (err) {
    // QuotaExceededError, or storage blocked by the browser
    console.warn('Storage write failed:', err.name);
    return false;
  }
}

console.log(safeSet('theme', 'dark')); // true (when storage is available)

Bonnes pratiques pour utiliser le Web Storage

• Sécurité : Prenez toujours en compte les implications de sécurité lors du stockage de données sensibles dans le navigateur. Évitez de stocker des informations confidentielles telles que des mots de passe ou des données d'identification personnelle.
• Limites de stockage : Gardez à l'esprit les limites de stockage (généralement environ 5 Mo) et gérez les cas où le stockage pourrait être plein.
• Compatibilité entre navigateurs : Assurez-vous que votre code gère les cas où un navigateur ne supporte pas les API de stockage.
• Stockage de strings uniquement : Le Web Storage n'accepte que des strings. Utilisez JSON.stringify() pour sauvegarder des objects et JSON.parse() pour les récupérer.
• Synchronisation entre onglets : Utilisez le StorageEvent pour écouter les changements effectués dans d'autres onglets et maintenir les données synchronisées.

Un exemple complet pour tout saisir

Cette démonstration illustre l'utilisation de la Web Storage API, notamment localStorage et sessionStorage. Des boutons vous permettent de stocker, récupérer et supprimer des données du stockage :

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Storage API Interactive Demo</title>
  </head>
  <body>
    <h2>localStorage and sessionStorage Demo</h2>
    <div style="display: flex; gap: 10px">
      <button onclick="storeInLocal()">Store in localStorage</button>
      <button onclick="retrieveFromLocal()">Retrieve from localStorage</button>
      <button onclick="removeFromLocal()">Remove from localStorage</button>
    </div>

    <div style="margin: 20px 0" id="localStorageResult"></div>

    <div style="display: flex; gap: 10px; margin-top: 10px">
      <button onclick="storeInSession()">Store in sessionStorage</button>
      <button onclick="retrieveFromSession()">
        Retrieve from sessionStorage
      </button>
      <button onclick="removeFromSession()">Remove from sessionStorage</button>
    </div>

    <div style="margin-top: 20px" id="sessionStorageResult"></div>

    <script>
      function storeInLocal() {
        localStorage.setItem("demo", "Hi from LocalStorage!");
        document.getElementById("localStorageResult").textContent =
          "Stored in localStorage: " + localStorage.getItem("demo");
      }

      function retrieveFromLocal() {
        const value = localStorage.getItem("demo") || "Nothing in localStorage";
        document.getElementById("localStorageResult").textContent =
          "Retrieved from localStorage: " + value;
      }

      function removeFromLocal() {
        localStorage.removeItem("demo");
        document.getElementById("localStorageResult").textContent =
          "Item removed from localStorage.";
      }

      function storeInSession() {
        sessionStorage.setItem("demo", "Hi from SessionStorage!");
        document.getElementById("sessionStorageResult").textContent =
          "Stored in sessionStorage: " + sessionStorage.getItem("demo");
      }

      function retrieveFromSession() {
        const value =
          sessionStorage.getItem("demo") || "Nothing in sessionStorage";
        document.getElementById("sessionStorageResult").textContent =
          "Retrieved from sessionStorage: " + value;
      }

      function removeFromSession() {
        sessionStorage.removeItem("demo");
        document.getElementById("sessionStorageResult").textContent =
          "Item removed from sessionStorage.";
      }
    </script>
  </body>
</html>

• LocalStorage : Les données stockées ici persistent même après la fermeture et la réouverture du navigateur, ce qui le rend parfait pour sauvegarder les préférences utilisateur ou d'autres données à long terme.
• SessionStorage : Similaire à localStorage, mais les données sont effacées à la fin de la session (par exemple, lors de la fermeture du navigateur).

En cliquant sur les différents boutons, vous pouvez voir comment les données sont ajoutées, récupérées et supprimées de chaque type de stockage. Les résultats s'affichent directement sous chaque bouton, vous donnant un retour immédiat sur ce qui se passe avec les données en stockage. Cette configuration interactive vous aide à visualiser et à comprendre comment les applications web peuvent mémoriser des données entre les rechargements de page ou les sessions de navigateur.

En plus d'interagir avec les opérations de stockage via les boutons de cette démonstration, vous pouvez également afficher et gérer les données stockées directement dans votre navigateur. Ouvrez les outils de développement de votre navigateur, naviguez vers la section Application, puis regardez sous l'onglet Storage. Vous pourrez y voir les entrées localStorage et sessionStorage.

Cet outil visuel vous permet de voir les effets de vos actions (comme stocker et supprimer des données) en temps réel et offre un moyen pratique d'explorer le fonctionnement du stockage web dans les navigateurs.

Conclusion

L'API Storage JavaScript fournit une méthode robuste et facile à utiliser pour gérer les données dans le navigateur. En comprenant et en exploitant localStorage et sessionStorage, les développeurs peuvent améliorer considérablement l'expérience utilisateur de leurs applications web. Prenez toujours en compte la sécurité et les limites de stockage pour garantir que vos applications sont robustes et conviviales. Grâce à ces outils, vous pouvez créer des états persistants et des fonctionnalités de gestion des données essentielles aux applications web modernes.

Pratique