From c05efa8d7ae464235cf83d7c0956e42dc6974103 Mon Sep 17 00:00:00 2001 From: julieng Date: Sat, 2 Oct 2021 17:20:14 +0200 Subject: move *.html to *.md --- files/fr/web/api/web_storage_api/index.html | 96 --------- files/fr/web/api/web_storage_api/index.md | 96 +++++++++ .../using_the_web_storage_api/index.html | 219 --------------------- .../using_the_web_storage_api/index.md | 219 +++++++++++++++++++++ 4 files changed, 315 insertions(+), 315 deletions(-) delete mode 100644 files/fr/web/api/web_storage_api/index.html create mode 100644 files/fr/web/api/web_storage_api/index.md delete mode 100644 files/fr/web/api/web_storage_api/using_the_web_storage_api/index.html create mode 100644 files/fr/web/api/web_storage_api/using_the_web_storage_api/index.md (limited to 'files/fr/web/api/web_storage_api') diff --git a/files/fr/web/api/web_storage_api/index.html b/files/fr/web/api/web_storage_api/index.html deleted file mode 100644 index bae54c054c..0000000000 --- a/files/fr/web/api/web_storage_api/index.html +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Web Storage API -slug: Web/API/Web_Storage_API -tags: - - API - - Reference - - Storage - - Web Storage - - localStorage - - sessionStorage -translation_of: Web/API/Web_Storage_API ---- -

{{DefaultAPISidebar("Web Storage API")}}

- -

L'API Web Storage fournit des mécanismes par lesquels les navigateurs peuvent stocker des paires clé / valeur, d'une manière beaucoup plus intuitive que l'utilisation de cookies.

- -

Web Storage, concepts et utilisations

- -

Les deux mécanismes au sein du web storage sont les suivantes:

- - - -

Ces mécanismes sont disponibles via les propriétés {{domxref("Window.sessionStorage")}} et {{domxref("Window.localStorage")}} (pour être plus précis, pour le support des navigateurs, l'objet Window implemente le WindowLocalStorage et l'object WindowSessionStorage, dont les propriétés localStorage et sessionStorage dépendent) — L'appel de l'une de ces propriétés va créer une instance de l'objet {{domxref("Storage")}},  à travers de laquelle les éléments de données peuvent être définis, récupérés et éliminés. Un objet de stockage différent est utilisé pour le sessionStorage et le localStorage pour chaque origine — ils fonctionnent et sont contrôlés séparément.

- -
-

Note : À partir de Firefox 45, lorsque le navigateur se bloque / redémarre, la quantité de données sauvegardées par origine est limitée à 10 Mo. Cela a été mis en place pour éviter les problèmes de mémoire causés par une utilisation excessive du stockage Web.

-
- -
-

Note : L'accès au Web Storage à partir d'iframes externes est interdit si l'utilisateur a désactivé les cookies tierce-partie (Firefox a adopté ce comportement à partir de la version 43 et suivantes.)

-
- -
-

Note: Le Web Storage n'est pas identique au mozStorage (interfaces XPCOM de Mozilla vers SQLite) ou l'API Session store (un utilitaire de stockage XPCOM utilisable par des extensions).

-
- -

Web Storage interfaces

- -
-
{{domxref("Storage")}}
-
Vous permet d'ajouter, modifier, lire ou supprimer des données pour un domaine et un type de stockage (session ou local) donnés.
-
{{domxref("Window")}}
-
L'API Web Storage dérive de l'objet {{domxref("Window")}} avec 2 nouvelles propriétés — {{domxref("Window.sessionStorage")}} et {{domxref("Window.localStorage")}} — lesquelles donnent accès, pour le domaine courant, aux objets session et local {{domxref("Storage")}} respectivement.
-
{{domxref("StorageEvent")}}
-
L'événement storage est déclenché sur l'objet Window du document en cas de changement dans un espace de stockage.
-
- -

Exemples

- -

Pour illustrer une utilisation typique du stockage Web, nous avons créé un exemple simple, appelé de manière imaginative Web Storage Demo. La landing page fournit des commandes permettant de personnaliser la couleur, la police et l'image décorative. Lorsque vous choisissez différentes options, la page est instantanément mise à jour. De plus, vos choix sont stockés dans localStorage. Ainsi, lorsque vous quittez la page puis la rechargez plus tard, vos choix sont mémorisés. En outre, nous avons fourni une event output page — Si vous chargez cette page dans un autre onglet, puis modifiez vos choix dans la page d'arrivée, vous verrez les informations de stockage mises à jour générées lors du déclenchement de {{event("StorageEvent")}}.

- -

Spécifications

- - - - - - - - - - - - - - -
SpécificationÉtatCommentaires
{{SpecName('HTML WHATWG', 'webstorage.html#webstorage')}}{{Spec2('HTML WHATWG')}}
- -

Compatibilité des navigateurs

- -

Window.localStorage

- -

{{Compat("api.Window.localStorage")}}

- -

Window.sessionStorage

- -

{{Compat("api.Window.sessionStorage")}}

- - - -

De nos jours, la plupart des navigateurs prennent en charge une option de confidentialité appelée "mode Incognito" ou "navigation privée", qui permet de s'assurer que la session de navigation privée ne laisse aucune trace après la fermeture du navigateur. Ceci est fondamentalement incompatible avec le stockage Web pour des raisons évidentes. En tant que tels, les éditeurs de navigateurs expérimentent différents scénarios pour gérer cette incompatibilité.

- -

La plupart des navigateurs ont opté pour une stratégie dans laquelle les API de stockage sont toujours disponibles et apparemment totalement fonctionnelles, à la différence près que toutes les données stockées sont effacées après la fermeture du navigateur. Pour ces navigateurs, il existe toujours différentes interprétations de ce qui devrait être fait avec les données stockées existantes (à partir d'une session de navigation normale). Devrait-il être disponible en lecture en mode privé? Certains navigateurs, notamment Safari, ont opté pour une solution dans laquelle le stockage est disponible, vide et doté d'un quota de 0 octets, ce qui rend impossible l'écriture de données.

- -

Les développeurs doivent connaître ces différentes implémentations et en tenir compte lors du développement de sites Web en fonction des API de stockage Web. Pour plus d'informations, consultez cet article de blog du WHATWG qui traite spécifiquement de ce sujet

- -

Voir aussi

- - diff --git a/files/fr/web/api/web_storage_api/index.md b/files/fr/web/api/web_storage_api/index.md new file mode 100644 index 0000000000..bae54c054c --- /dev/null +++ b/files/fr/web/api/web_storage_api/index.md @@ -0,0 +1,96 @@ +--- +title: Web Storage API +slug: Web/API/Web_Storage_API +tags: + - API + - Reference + - Storage + - Web Storage + - localStorage + - sessionStorage +translation_of: Web/API/Web_Storage_API +--- +

{{DefaultAPISidebar("Web Storage API")}}

+ +

L'API Web Storage fournit des mécanismes par lesquels les navigateurs peuvent stocker des paires clé / valeur, d'une manière beaucoup plus intuitive que l'utilisation de cookies.

+ +

Web Storage, concepts et utilisations

+ +

Les deux mécanismes au sein du web storage sont les suivantes:

+ + + +

Ces mécanismes sont disponibles via les propriétés {{domxref("Window.sessionStorage")}} et {{domxref("Window.localStorage")}} (pour être plus précis, pour le support des navigateurs, l'objet Window implemente le WindowLocalStorage et l'object WindowSessionStorage, dont les propriétés localStorage et sessionStorage dépendent) — L'appel de l'une de ces propriétés va créer une instance de l'objet {{domxref("Storage")}},  à travers de laquelle les éléments de données peuvent être définis, récupérés et éliminés. Un objet de stockage différent est utilisé pour le sessionStorage et le localStorage pour chaque origine — ils fonctionnent et sont contrôlés séparément.

+ +
+

Note : À partir de Firefox 45, lorsque le navigateur se bloque / redémarre, la quantité de données sauvegardées par origine est limitée à 10 Mo. Cela a été mis en place pour éviter les problèmes de mémoire causés par une utilisation excessive du stockage Web.

+
+ +
+

Note : L'accès au Web Storage à partir d'iframes externes est interdit si l'utilisateur a désactivé les cookies tierce-partie (Firefox a adopté ce comportement à partir de la version 43 et suivantes.)

+
+ +
+

Note: Le Web Storage n'est pas identique au mozStorage (interfaces XPCOM de Mozilla vers SQLite) ou l'API Session store (un utilitaire de stockage XPCOM utilisable par des extensions).

+
+ +

Web Storage interfaces

+ +
+
{{domxref("Storage")}}
+
Vous permet d'ajouter, modifier, lire ou supprimer des données pour un domaine et un type de stockage (session ou local) donnés.
+
{{domxref("Window")}}
+
L'API Web Storage dérive de l'objet {{domxref("Window")}} avec 2 nouvelles propriétés — {{domxref("Window.sessionStorage")}} et {{domxref("Window.localStorage")}} — lesquelles donnent accès, pour le domaine courant, aux objets session et local {{domxref("Storage")}} respectivement.
+
{{domxref("StorageEvent")}}
+
L'événement storage est déclenché sur l'objet Window du document en cas de changement dans un espace de stockage.
+
+ +

Exemples

+ +

Pour illustrer une utilisation typique du stockage Web, nous avons créé un exemple simple, appelé de manière imaginative Web Storage Demo. La landing page fournit des commandes permettant de personnaliser la couleur, la police et l'image décorative. Lorsque vous choisissez différentes options, la page est instantanément mise à jour. De plus, vos choix sont stockés dans localStorage. Ainsi, lorsque vous quittez la page puis la rechargez plus tard, vos choix sont mémorisés. En outre, nous avons fourni une event output page — Si vous chargez cette page dans un autre onglet, puis modifiez vos choix dans la page d'arrivée, vous verrez les informations de stockage mises à jour générées lors du déclenchement de {{event("StorageEvent")}}.

+ +

Spécifications

+ + + + + + + + + + + + + + +
SpécificationÉtatCommentaires
{{SpecName('HTML WHATWG', 'webstorage.html#webstorage')}}{{Spec2('HTML WHATWG')}}
+ +

Compatibilité des navigateurs

+ +

Window.localStorage

+ +

{{Compat("api.Window.localStorage")}}

+ +

Window.sessionStorage

+ +

{{Compat("api.Window.sessionStorage")}}

+ + + +

De nos jours, la plupart des navigateurs prennent en charge une option de confidentialité appelée "mode Incognito" ou "navigation privée", qui permet de s'assurer que la session de navigation privée ne laisse aucune trace après la fermeture du navigateur. Ceci est fondamentalement incompatible avec le stockage Web pour des raisons évidentes. En tant que tels, les éditeurs de navigateurs expérimentent différents scénarios pour gérer cette incompatibilité.

+ +

La plupart des navigateurs ont opté pour une stratégie dans laquelle les API de stockage sont toujours disponibles et apparemment totalement fonctionnelles, à la différence près que toutes les données stockées sont effacées après la fermeture du navigateur. Pour ces navigateurs, il existe toujours différentes interprétations de ce qui devrait être fait avec les données stockées existantes (à partir d'une session de navigation normale). Devrait-il être disponible en lecture en mode privé? Certains navigateurs, notamment Safari, ont opté pour une solution dans laquelle le stockage est disponible, vide et doté d'un quota de 0 octets, ce qui rend impossible l'écriture de données.

+ +

Les développeurs doivent connaître ces différentes implémentations et en tenir compte lors du développement de sites Web en fonction des API de stockage Web. Pour plus d'informations, consultez cet article de blog du WHATWG qui traite spécifiquement de ce sujet

+ +

Voir aussi

+ + diff --git a/files/fr/web/api/web_storage_api/using_the_web_storage_api/index.html b/files/fr/web/api/web_storage_api/using_the_web_storage_api/index.html deleted file mode 100644 index 96ce992c18..0000000000 --- a/files/fr/web/api/web_storage_api/using_the_web_storage_api/index.html +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: Utiliser l'API Web Storage -slug: Web/API/Web_Storage_API/Using_the_Web_Storage_API -tags: - - API - - Guide - - Stockage - - Stockage Web - - localStorage -translation_of: Web/API/Web_Storage_API/Using_the_Web_Storage_API ---- -

L'API "Web Storage" fournit des mécanismes par lesquels les navigateurs web peuvent stocker des paires de clé-valeur, d'une manière plus intuitive qu'en utilisant des cookies. Cet article décrit pas à pas comment se servir de cette technologie facile d'utilisation.

- -

Concepts de base

- -

Les objets de stockages sont de simples magasins clé-valeur, similaires aux objets, mais restant intacts après des chargements de page. La clé peut être une chaîne de caractères ou des entiers, mais la valeur sera toujours une chaîne. Vous pouvez accéder à ces valeurs comme pour un objet ou avec les méthodes getItem() et setItem(). Les trois lignes suivantes vont enregistrer la couleur de la même façon :

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

Note : Il est recommandé d'utiliser l'API "Web Storage" (setItem, getItem, removeItem, key, length) pour prévenir les embûches associées à l'utilisation d'objets capable de stocker des couples clé-valeur.

-
- -

Les deux principaux mécanismes internes du Stockage Web sont :

- - - -

Ces mécanismes sont disponibles via les propriétés {{domxref("Window.sessionStorage")}} et {{domxref("Window.localStorage")}}  (plus précisément, dans les navigateurs web le supportant, l'objet Window  implémente les objets WindowLocalStorage et WindowSessionStorage, sur lesquels les propriétés localStorage et sessionStorage se basent) — l'appel d'un des deux va créer une instance de l'objet {{domxref("Storage")}}, dans lequel des données pourront être ajoutées, récupérées et supprimées. Pour sessionStorage et localStorage, un objet de stockage différent est utilisé pour chaque origine — ils fonctionnent et sont contrôlés séparément.

- -

Donc, par exemple, un appel initial de localStorage sur un document va retourner un objet {{domxref("Storage")}} ; un appel de sessionStorage sur un document va retourner un objet {{domxref("Storage")}} différent. Les deux peuvent se manipuler de la même façon, mais séparément.

- -

Détection de la fonction localStorage

- -

Pour être capable d'utiliser localStorage, nous devons d'abord vérifier 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 propriété nommée localStorage. Cependant, pour différentes raisons, la vérification seule de l'existnce de cette propriété peut provoquer des erreurs. .Son absence n'est pas non plus une garantie de son indisponibilité, certains navigateurs offrent un paramètre pour désactiver 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 privée fournit un objet localStorage vide dont le quota est nul, le rendant inutilisable. Notre fonction de détection doit prendre en compte ces scénarios.

- -

Voici une fonction qui va détecter 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 brève histoire de la détection de localStorage.

- -

Un exemple simple

- -

Pour illustrer certains usages typiques du Stockage Web, nous avons créé un exemple simple ingénieusement appelé Web Storage Demo. La page de lancement fournit des contrôles afin de personnaliser la couleur, la police de caractère et l'image de décoration:

- -

- -

Quand vous choisissez une option différente, la page est mise à jour instantanément; de plus, vos choix sont stockés avec localStorage, donc quand vous quitterez la page et la rechargerez plus tard, vos choix auront été mémorisés.

- -

Nous avons aussi fournit une page pour l'événement émis - Si vous chargez cette page dans un autre onglet, puis faite les changements de votre choix sur la page de démarrage, vous allez voir une information liée à l'événement {{domxref("StorageEvent")}} qui a été lancé.

- -

- -
-

Note : En plus de l'affichage en temps réel des pages en utilisant les liens ci-dessus, vous pouvez aussi regarder le code-source.

-
- -

Tester si le stockage a déjà été rempli

- -

Pour démarrer avec main.js, nous allons tester que l'objet de stockage a bien été rempli (c-à-d, que l'on a déjà accédé à la page):

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

La méthode {{domxref("Storage.getItem()")}} est utilisée pour obtenir les données de l'élément depuis le stockage ; dans ce cas nous testons l'existence de l'élément bgcolor; si il n'existe pas nous lançons populateStorage() pour ajouter des valeurs personnalisées dans le stockage. Si il y a déjà des valeurs ici, nous lançons setStyles() pour mettre à jour le style de la page avec les valeurs stockées.

- -

Note: Vous pouvez aussi utiliser {{domxref("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 recupérées du stockage en utilisant {{domxref("Storage.getItem()")}}. La méthode prend en argument la clé de l'élément, 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 premières lignes vont chercher les valeurs dans le stockage local. Puis, nous définissons les valeurs exposées 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 décoration de la page, ainsi nos options de personnalisation reviennent lors du rechargement de la page.

- -

Enregistrer une valeur dans le stockage

- -

{{domxref("Storage.setItem()")}} est aussi bien utilisée pour la création d'une donnée,  que pour la modification d'une donnée existante (si cette donnée existe déja). Elle prend deux arguments — la clé de l'élément à créer/modifier, et la valeur associée à 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() définit trois éléments dans le stockage local — la couleur de fond, la police de caractère 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 élément du formulaire, ainsi les données et le style sont mis à jour quelque soit la valeur du formulaire qui a changé:

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

Répondre aux changements du stockage avec StorageEvent

- -

L'événement {{event("StorageEvent")}} est lancé dès lors qu'un changement est fait sur l'objet {{domxref("Storage")}}. Cela ne va pas marcher sur la même 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 accéder aux mêmes objets de stockage.

- -

Sur la page d'événement (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 event listener à l'objet window qui se lance quand l'objet {{domxref("Storage")}}, associée à l'origine courante, est modifié. Comme vous pouvez le voir ci-dessus, l'objet événement associé à cet événement a de nombreuses propriétés contenant des informations utiles: la clé de la donnée qui a changé, l'ancienne valeur avant le changement, la nouvelle valeur après le changement, l'URL du document qui a changé le stockage et l'objet stockage lui-même.

- -

Supprimer des données

- -

l'API de Stockage Web fournit aussi un couple de méthodes simples pour supprimer des données. Nous ne les utilisons pas dans notre démo, mais elles sont simples à ajouter dans votre projet :

- - - -

Spécifications

- - - - - - - - - - - - - - -
SpécificationStatutCommentaire
{{SpecName('Web Storage')}}{{Spec2('Web Storage')}}
- -

Compatibilité des navigateurs

- -

Window.localStorage

- -

{{Compat("api.Window.localStorage")}}

- -

Window.sessionStorage

- -

{{Compat("api.Window.sessionStorage")}}

- -

Tous les navigateurs ont des niveaux de capacité différents pour localStorage et sessionStorage. Voici un détail des capacités de stockage pour différents navigateurs.

- -
-

Note : Depuis iOS 5.1, Safari Mobile stocke les données de localStorage dans le repertoire de cache, qui est parfois sujet à des nettoyages, à la demande de l'OS, typiquement quand l'espace restant est faible.

-
- -

Voir aussi

- - diff --git a/files/fr/web/api/web_storage_api/using_the_web_storage_api/index.md b/files/fr/web/api/web_storage_api/using_the_web_storage_api/index.md new file mode 100644 index 0000000000..96ce992c18 --- /dev/null +++ b/files/fr/web/api/web_storage_api/using_the_web_storage_api/index.md @@ -0,0 +1,219 @@ +--- +title: Utiliser l'API Web Storage +slug: Web/API/Web_Storage_API/Using_the_Web_Storage_API +tags: + - API + - Guide + - Stockage + - Stockage Web + - localStorage +translation_of: Web/API/Web_Storage_API/Using_the_Web_Storage_API +--- +

L'API "Web Storage" fournit des mécanismes par lesquels les navigateurs web peuvent stocker des paires de clé-valeur, d'une manière plus intuitive qu'en utilisant des cookies. Cet article décrit pas à pas comment se servir de cette technologie facile d'utilisation.

+ +

Concepts de base

+ +

Les objets de stockages sont de simples magasins clé-valeur, similaires aux objets, mais restant intacts après des chargements de page. La clé peut être une chaîne de caractères ou des entiers, mais la valeur sera toujours une chaîne. Vous pouvez accéder à ces valeurs comme pour un objet ou avec les méthodes getItem() et setItem(). Les trois lignes suivantes vont enregistrer la couleur de la même façon :

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

Note : Il est recommandé d'utiliser l'API "Web Storage" (setItem, getItem, removeItem, key, length) pour prévenir les embûches associées à l'utilisation d'objets capable de stocker des couples clé-valeur.

+
+ +

Les deux principaux mécanismes internes du Stockage Web sont :

+ + + +

Ces mécanismes sont disponibles via les propriétés {{domxref("Window.sessionStorage")}} et {{domxref("Window.localStorage")}}  (plus précisément, dans les navigateurs web le supportant, l'objet Window  implémente les objets WindowLocalStorage et WindowSessionStorage, sur lesquels les propriétés localStorage et sessionStorage se basent) — l'appel d'un des deux va créer une instance de l'objet {{domxref("Storage")}}, dans lequel des données pourront être ajoutées, récupérées et supprimées. Pour sessionStorage et localStorage, un objet de stockage différent est utilisé pour chaque origine — ils fonctionnent et sont contrôlés séparément.

+ +

Donc, par exemple, un appel initial de localStorage sur un document va retourner un objet {{domxref("Storage")}} ; un appel de sessionStorage sur un document va retourner un objet {{domxref("Storage")}} différent. Les deux peuvent se manipuler de la même façon, mais séparément.

+ +

Détection de la fonction localStorage

+ +

Pour être capable d'utiliser localStorage, nous devons d'abord vérifier 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 propriété nommée localStorage. Cependant, pour différentes raisons, la vérification seule de l'existnce de cette propriété peut provoquer des erreurs. .Son absence n'est pas non plus une garantie de son indisponibilité, certains navigateurs offrent un paramètre pour désactiver 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 privée fournit un objet localStorage vide dont le quota est nul, le rendant inutilisable. Notre fonction de détection doit prendre en compte ces scénarios.

+ +

Voici une fonction qui va détecter 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 brève histoire de la détection de localStorage.

+ +

Un exemple simple

+ +

Pour illustrer certains usages typiques du Stockage Web, nous avons créé un exemple simple ingénieusement appelé Web Storage Demo. La page de lancement fournit des contrôles afin de personnaliser la couleur, la police de caractère et l'image de décoration:

+ +

+ +

Quand vous choisissez une option différente, la page est mise à jour instantanément; de plus, vos choix sont stockés avec localStorage, donc quand vous quitterez la page et la rechargerez plus tard, vos choix auront été mémorisés.

+ +

Nous avons aussi fournit une page pour l'événement émis - Si vous chargez cette page dans un autre onglet, puis faite les changements de votre choix sur la page de démarrage, vous allez voir une information liée à l'événement {{domxref("StorageEvent")}} qui a été lancé.

+ +

+ +
+

Note : En plus de l'affichage en temps réel des pages en utilisant les liens ci-dessus, vous pouvez aussi regarder le code-source.

+
+ +

Tester si le stockage a déjà été rempli

+ +

Pour démarrer avec main.js, nous allons tester que l'objet de stockage a bien été rempli (c-à-d, que l'on a déjà accédé à la page):

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

La méthode {{domxref("Storage.getItem()")}} est utilisée pour obtenir les données de l'élément depuis le stockage ; dans ce cas nous testons l'existence de l'élément bgcolor; si il n'existe pas nous lançons populateStorage() pour ajouter des valeurs personnalisées dans le stockage. Si il y a déjà des valeurs ici, nous lançons setStyles() pour mettre à jour le style de la page avec les valeurs stockées.

+ +

Note: Vous pouvez aussi utiliser {{domxref("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 recupérées du stockage en utilisant {{domxref("Storage.getItem()")}}. La méthode prend en argument la clé de l'élément, 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 premières lignes vont chercher les valeurs dans le stockage local. Puis, nous définissons les valeurs exposées 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 décoration de la page, ainsi nos options de personnalisation reviennent lors du rechargement de la page.

+ +

Enregistrer une valeur dans le stockage

+ +

{{domxref("Storage.setItem()")}} est aussi bien utilisée pour la création d'une donnée,  que pour la modification d'une donnée existante (si cette donnée existe déja). Elle prend deux arguments — la clé de l'élément à créer/modifier, et la valeur associée à 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() définit trois éléments dans le stockage local — la couleur de fond, la police de caractère 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 élément du formulaire, ainsi les données et le style sont mis à jour quelque soit la valeur du formulaire qui a changé:

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

Répondre aux changements du stockage avec StorageEvent

+ +

L'événement {{event("StorageEvent")}} est lancé dès lors qu'un changement est fait sur l'objet {{domxref("Storage")}}. Cela ne va pas marcher sur la même 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 accéder aux mêmes objets de stockage.

+ +

Sur la page d'événement (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 event listener à l'objet window qui se lance quand l'objet {{domxref("Storage")}}, associée à l'origine courante, est modifié. Comme vous pouvez le voir ci-dessus, l'objet événement associé à cet événement a de nombreuses propriétés contenant des informations utiles: la clé de la donnée qui a changé, l'ancienne valeur avant le changement, la nouvelle valeur après le changement, l'URL du document qui a changé le stockage et l'objet stockage lui-même.

+ +

Supprimer des données

+ +

l'API de Stockage Web fournit aussi un couple de méthodes simples pour supprimer des données. Nous ne les utilisons pas dans notre démo, mais elles sont simples à ajouter dans votre projet :

+ + + +

Spécifications

+ + + + + + + + + + + + + + +
SpécificationStatutCommentaire
{{SpecName('Web Storage')}}{{Spec2('Web Storage')}}
+ +

Compatibilité des navigateurs

+ +

Window.localStorage

+ +

{{Compat("api.Window.localStorage")}}

+ +

Window.sessionStorage

+ +

{{Compat("api.Window.sessionStorage")}}

+ +

Tous les navigateurs ont des niveaux de capacité différents pour localStorage et sessionStorage. Voici un détail des capacités de stockage pour différents navigateurs.

+ +
+

Note : Depuis iOS 5.1, Safari Mobile stocke les données de localStorage dans le repertoire de cache, qui est parfois sujet à des nettoyages, à la demande de l'OS, typiquement quand l'espace restant est faible.

+
+ +

Voir aussi

+ + -- cgit v1.2.3-54-g00ecf