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

CKTIS / JavaScript

Storage.setItem — enregistrer et remplacer une valeur

Storage.setItem enregistre du texte sous une clé dans localStorage ou sessionStorage, en remplaçant la valeur précédente. Une écriture peut échouer : il faut donc tenir compte des exceptions et des restrictions d’accès au stockage.

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

storage.setItem(key, value)

Appelez Storage.setItem sur un objet localStorage ou sessionStorage : storage.setItem(key, value). La méthode crée une entrée ou remplace la valeur d’une clé existante et renvoie undefined. Cette API fait partie de la norme HTML ; elle ne relève pas d’une édition particulière d’ECMAScript. Les moteurs de navigateur modernes la prennent en charge ; la présence de Node 24 dans un dépôt ne prouve pas la disponibilité d’une API de navigateur.

Les clés et les valeurs sont converties en chaînes. Pour stocker un objet, sérialisez-le explicitement sous forme de chaîne. À la lecture de la valeur stockée, le stockage renvoie une chaîne que l’application doit décoder selon le format utilisé à l’écriture. Si vous écrivez du JSON avec JSON.stringify, utilisez JSON.parse pour décoder cette chaîne. localStorage conserve les données d’une origine entre les sessions, tandis que sessionStorage est aussi séparé selon le contexte de navigation de premier niveau, généralement l’onglet. Les données peuvent être supprimées.

Une écriture échouée peut déclencher QuotaExceededError ; l’accès au stockage lui-même peut déclencher SecurityError. Entourez l’accès et l’écriture de try/catch si l’application doit fonctionner sans stockage. Écrire une chaîne identique ne change rien. La notification storage concerne les autres documents concernés, pas la fenêtre qui effectue l’écriture.

Exemples

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Storage.setItem: writing and replacing text</title>
</head>
<body>
<h1>Replacing a storage value</h1>
<p id="source"></p>
<script>
  function writeValues(storage) {
    let key = 'cktis:setItem';
    while (storage.getItem(key) !== null) key += ':';

    try {
      storage.setItem(key, 'first');
      const before = storage.getItem(key);
      storage.setItem(key, 'second');
      return [before, storage.getItem(key)];
    } finally {
      storage.removeItem(key);
    }
  }

  let lines;
  let source = 'Using browser sessionStorage.';
  try {
    lines = writeValues(window.sessionStorage);
  } catch (error) {
    if (error.name !== 'SecurityError' && error.name !== 'QuotaExceededError') throw error;
    source = 'Browser storage is unavailable. Using an in-memory fixture, not Web Storage.';
    const entries = new Map();
    lines = writeValues({
      getItem(key) { return entries.has(key) ? entries.get(key) : null; },
      setItem(key, value) { entries.set(key, String(value)); },
      removeItem(key) { entries.delete(key); }
    });
  }
  document.getElementById('source').textContent = source;
  for (const line of lines) console.log(line);
</script>
</body>
</html>

Résultat

first
second

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