Utiliser l'API Web Storage

Concepts de base

Les objets de stockages sont de simples magasins cl-valeur, similaires aux objets, mais restant intacts aprs des chargements de page. La cl peut tre une chane de caractres ou des entiers, mais la valeur sera toujours une chane. Vous pouvez accder ces valeurs comme pour un objet ou avec les mthodes getItem() et setItem(). Les trois lignes suivantes vont enregistrer la couleur de la mme faon :

localStorage.colorSetting = "#a4509b";
localStorage["colorSetting"] = "#a4509b";
localStorage.setItem("colorSetting", "#a4509b");

Les deux principaux mcanismes internes du Stockage Web sont :

• sessionStorage qui maintient un espace de stockage, spar pour chaque origine diffrente, disponible le temps de la session de la page (tant que le navigateur reste lanc, incluant les rechargements de la page et les restaurations).
• localStorage qui tient le mme rle mais persiste mme aprs le redmarrage du navigateur web.

Ces mcanismes sont disponibles via les proprits Window.sessionStorage et Window.localStorage (plus prcisment, dans les navigateurs web le supportant, l'objet Window implmente les objets WindowLocalStorage et WindowSessionStorage, sur lesquels les proprits localStorage et sessionStorage se basent) l'appel d'un des deux va crer une instance de l'objet Storage, dans lequel des donnes pourront tre ajoutes, rcupres et supprimes. Pour sessionStorage et localStorage, un objet de stockage diffrent est utilis pour chaque origine ils fonctionnent et sont contrls sparment.

Donc, par exemple, un appel initial de localStorage sur un document va retourner un objet Storage ; un appel de sessionStorage sur un document va retourner un objet Storage diffrent. Les deux peuvent se manipuler de la mme faon, mais sparment.

Dtection de la fonction localStorage

Pour tre capable d'utiliser localStorage, nous devons d'abord vrifier qu'il est support et disponible dans la session de navigation actuelle.

Test du support et disponibilit

Les navigateurs qui supportent localStorage ont sur l'objet windows une proprit nomme localStorage. Cependant, pour diffrentes raisons, la vrification seule de l'existence de cette proprit peut provoquer des erreurs. Son absence n'est pas non plus une garantie de son indisponibilit, certains navigateurs offrent un paramtre pour dsactiver localStorage. Donc un navigateur peut supporter localStorage, mais peut ne pas le rendre disponible aux scripts de la page. Un exemple de cela est Safari, qui en mode de navigation prive fournit un objet localStorage vide dont le quota est nul, le rendant inutilisable. Notre fonction de dtection doit prendre en compte ces scnarios.

Voici une fonction qui va dtecter que localStorage est support mais aussi disponible:

function storageAvailable(type) {
  try {
    var storage = window[type],
      x = "__storage_test__";
    storage.setItem(x, x);
    storage.removeItem(x);
    return true;
  } catch (e) {
    return (
      e instanceof DOMException &&
      // everything except Firefox
      (e.code === 22 ||
        // Firefox
        e.code === 1014 ||
        // test name field too, because code might not be present
        // everything except Firefox
        e.name === "QuotaExceededError" ||
        // Firefox
        e.name === "NS_ERROR_DOM_QUOTA_REACHED") &&
      // acknowledge QuotaExceededError only if there's something already stored
      storage.length !== 0
    );
  }
}

Et voici comment l'utiliser :

if (storageAvailable("localStorage")) {
  // Nous pouvons utiliser localStorage
} else {
  // Malheureusement, localStorage n'est pas disponible
}

Au lieu de cela, vous pouvez tester la disponibilit de sessionStorage en appelant storageAvailable('sessionStorage').

Vous pouvez retrouver ici une brve histoire de la dtection de localStorage.

Un exemple simple

Pour illustrer certains usages typiques du Stockage Web, nous avons cr un exemple simple ingnieusement appel Web Storage Demo. La page de lancement fournit des contrles afin de personnaliser la couleur, la police de caractre et l'image de dcoration:

[]

Quand vous choisissez une option diffrente, la page est mise jour instantanment; de plus, vos choix sont stocks avec localStorage, donc quand vous quitterez la page et la rechargerez plus tard, vos choix auront t mmoriss.

Nous avons aussi fournit une page pour l'vnement mis - Si vous chargez cette page dans un autre onglet, puis faite les changements de votre choix sur la page de dmarrage, vous allez voir une information lie l'vnement StorageEvent qui a t lanc.

[]

Tester si le stockage a dj t rempli

Pour dmarrer avec main.js, nous allons tester que l'objet de stockage a bien t rempli (c--d, que l'on a dj accd la page):

if (!localStorage.getItem("bgcolor")) {
  populateStorage();
} else {
  setStyles();
}

La mthode Storage.getItem() est utilise pour obtenir les donnes de l'lment depuis le stockage ; dans ce cas nous testons l'existence de l'lment bgcolor; si il n'existe pas nous lanons populateStorage() pour ajouter des valeurs personnalises dans le stockage. Si il y a dj des valeurs ici, nous lanons setStyles() pour mettre jour le style de la page avec les valeurs stockes.

Note: Vous pouvez aussi utiliser Storage.length pour tester si l'objet de stockage est vide ou non.

Obtenir les valeurs du stockage

Comme vu ci dessus, les valeurs peuvent tre recupres du stockage en utilisant Storage.getItem(). La mthode prend en argument la cl de l'lment, et retourne la valeur. Par exemple:

function setStyles() {
  var currentColor = localStorage.getItem("bgcolor");
  var currentFont = localStorage.getItem("font");
  var currentImage = localStorage.getItem("image");

  document.getElementById("bgcolor").value = currentColor;
  document.getElementById("font").value = currentFont;
  document.getElementById("image").value = currentImage;

  htmlElem.style.backgroundColor = "#" + currentColor;
  pElem.style.fontFamily = currentFont;
  imgElem.setAttribute("src", currentImage);
}

Ici, les trois premires lignes vont chercher les valeurs dans le stockage local. Puis, nous dfinissons les valeurs exposes par le formulaire avec ces valeurs, afin qu'elles persistent quand on recharge la page. Enfin, nous mettons jour le style et l'image de dcoration de la page, ainsi nos options de personnalisation reviennent lors du rechargement de la page.

Enregistrer une valeur dans le stockage

Storage.setItem() est aussi bien utilise pour la cration d'une donne, que pour la modification d'une donne existante (si cette donne existe dja). Elle prend deux arguments la cl de l'lment crer/modifier, et la valeur associe stocker.

function populateStorage() {
  localStorage.setItem("bgcolor", document.getElementById("bgcolor").value);
  localStorage.setItem("font", document.getElementById("font").value);
  localStorage.setItem("image", document.getElementById("image").value);

  setStyles();
}

La fonction populateStorage() dfinit trois lments dans le stockage local la couleur de fond, la police de caractre et le chemin de l'image. Ensuite elle lance la fonction setStyles() pour mettre jour le style de la page, etc.

Nous avons aussi inclu un handler onchange sur chaque lment du formulaire, ainsi les donnes et le style sont mis jour quelque soit la valeur du formulaire qui a chang:

bgcolorForm.onchange = populateStorage;
fontForm.onchange = populateStorage;
imageForm.onchange = populateStorage;

Rpondre aux changements du stockage avec StorageEvent

L'vnement StorageEvent est lanc ds lors qu'un changement est fait sur l'objet Storage. Cela ne va pas marcher sur la mme page qui a provoqu le changement: c'est vraiment un moyen pour que les autres pages du domaine qui utilisent le stockage local puissent se synchroniser avec tous les changements qui ont t fait.

Les pages des autres domaines ne peuvent pas accder aux mmes objets de stockage.

Sur la page d'vnement (voir events.js) le seul JavaScript est :

window.addEventListener("storage", function (e) {
  document.querySelector(".my-key").textContent = e.key;
  document.querySelector(".my-old").textContent = e.oldValue;
  document.querySelector(".my-new").textContent = e.newValue;
  document.querySelector(".my-url").textContent = e.url;
  document.querySelector(".my-storage").textContent = e.storageArea;
});

Ici nous avons ajout un couteur d'vnement l'objet window qui se lance quand l'objet Storage, associ l'origine courante, est modifi. Comme vous pouvez le voir ci-dessus, l'objet vnement associ cet vnement a de nombreuses proprits contenant des informations utiles : la cl de la donne qui a chang, l'ancienne valeur avant le changement, la nouvelle valeur aprs le changement, l'URL du document qui a chang le stockage et l'objet stockage lui-mme.

Supprimer des donnes

l'API de Stockage Web fournit aussi un couple de mthodes simples pour supprimer des donnes. Nous ne les utilisons pas dans notre dmo, mais elles sont simples ajouter dans votre projet :

• Storage.removeItem() prend un seul argument la cl de l'lment que vous souhaitez supprimer et le supprime de l'objet de stockage pour le domaine.
• Storage.clear() ne prend pas d'argument, et vide l'ensemble des donnes de l'objet de stockage pour le domaine.

Spcifications

Compatibilit des navigateurs

api.Window.localStorage

api.Window.sessionStorage

Voir aussi

• Page API du Stockage Web