Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.
Stable
Permet au add-on le stockage des données afin qu'il soit conservé entre les redémarrages de Firefox. Ce module fonctionne de façon similaire au DOM Storage du Web, mais il est uniquement disponible pour des add-ons.
Utilisation
Le module de stockage simple exporte un objet appelé storage qui est persistant et à porté de votre add-on. C'est un objet JavaScript normal, et vous pouvez le traiter comme vous le feriez pour tout autre.
Pour stocker une valeur, il faut juste l'affecter avec la propriété storage:
var ss = require("sdk/simple-storage");
ss.storage.myArray = [1, 1, 2, 3, 5, 8, 13];
ss.storage.myBoolean = true;
ss.storage.myNull = null;
ss.storage.myNumber = 3.1337;
ss.storage.myObject = { a: "foo", b: { c: true }, d: null };
ss.storage.myString = "O frabjous day!";
Vous pouvez stocker des valeurs tableau, booléennes, nombre, objet, null et des textes. Si vous souhaitez stocker d'autres types de valeurs, vous devrez d'abord les convertir en chaînes ou un autre de ces types.
Veillez à définir les propriétés avec storage et non avec le module lui-même:
// This is not good!
var ss = require("sdk/simple-storage");
ss.foo = "I will not be saved! :(";
stockage simple et "jpm run"
Le module de stockage simple stocke ses données dans votre profil. Parce que jpm run utilise par défaut un profil frais chaque fois qu'il est exécuté, le stockage simple ne fonctionnera pas avec des add-ons exécutées en utilisant jpm run - les données stockées ne persisteront pas d'une exécution à l'autre.
La solution la plus simple à ce problème est d'utiliser l'option --profile de jpm avec un chemin d'accès à un profil - pas seulement un nom de profil. Vous pouvez aussi avoir besoin d'inclure l'option --no-copie pour empêcher Firefox de copier le profil dans un répertoire de temporaire chaque fois qu'il démarre.
jpm run --no-copy --profile path/to/profile/dir
Si vous spécifiez un profil non-existant, il sera créé.
Important: Si vous utilisez cette méthode, vous devez mettre fin à votre session de débogage en quittant Firefox normalement, en annulant la commande shell. Si vous ne fermez pas Firefox normalement, puis un simple stockage ne sera pas informé que la session est terminée, et ne sera pas écrire vos données à la mémoire de sauvegarde.
Accès au stockage à partir de la console
Dans l' Add-on Debugger , vous pouvez accéder à vos addons simple stockage par programmation à partir de la console en utilisant ce qui suit:
loader.modules['resource://gre/modules/commonjs/sdk/simple-storage.js'].exports.storage
Constructeur de tableaux
Pour ne pas remettre à zéro un tableau, attention au constructeur. Par exemple, cet add-on essaie de stocker les URL des pages visitées:
var ss = require("sdk/simple-storage");
ss.storage.pages = [];
require("sdk/tabs").on("ready", function(tab) {
ss.storage.pages.push(tab.url);
});
require("sdk/ui/button/action").ActionButton({
id: "read",
label: "Read",
icon: "./read.png",
onClick: function() {
console.log(ss.storage.pages);
}
});
Mais cela ne fonctonne pas, car il vide le tableau chaque fois que l'add-on est apellée (par exemple, chaque fois que Firefox est lancé). La ligne 2 a besoin d'être subordonné, de sorte que le tableau est uniquement construite si il n'existe pas déjà:
if (!ss.storage.pages) ss.storage.pages = [];
Suppression de données
Vous pouvez supprimer des propriétés en utilisant l'opérateur delete. Voici une add-on qui ajoute trois boutons pour écrire, lire et supprimer une valeur:
var ss = require("sdk/simple-storage");
require("sdk/ui/button/action").ActionButton({
id: "write",
label: "Write",
icon: "./write.png",
onClick: function() {
ss.storage.value = 1;
console.log("Setting value");
}
});
require("sdk/ui/button/action").ActionButton({
id: "read",
label: "Read",
icon: "./read.png",
onClick: function() {
console.log(ss.storage.value);
}
});
require("sdk/ui/button/action").ActionButton({
id: "delete",
label: "Delete",
icon: "./delete.png",
onClick: function() {
delete ss.storage.value;
console.log("Deleting value");
}
});
Si vous l'exécutez, vous verrez que si vous cliquez sur "Lire" après avoir cliqué sur "Supprimer" vous aurez le résultat escompté:
info: undefined
Notez que pour exécuter cet add-on, vous aurez à enregistrer des fichiers icône nommées "write.png", "read.png", et "delete.png" dans le répertoire "data".
Quotas
Le stockage simple à la disposition de votre add-on est limité. Actuellement, cette limite est environ cinq mégaoctets (5,242,880 octets). Vous pouvez choisir d'être averti lorsque vous dépassez le quota, et vous devez répondre en réduisant la quantité de données dans le stockage. Si vous quittez l'application pendant que vous êtes hors quota, toutes les données stockées depuis la dernière fois que vous étiez sous le quota ne sont pas conservées. Vous ne devriez pas laisser cela se produire.
Pour écouter les notifications du quota, utiliser l'evenement "OverQuota". il sera appelée quand votre stockage dépasse le quota.
function myOnOverQuotaListener() {
console.log("Uh oh.");
}
ss.on("OverQuota", myOnOverQuotaListener);
Les auditeurs peuvent également être retirés:
ss.removeListener("OverQuota", myOnOverQuotaListener);Pour connaitre le % de saturation du quota utiliser la proprieté quotaUsage. Si vous êtes dans votre quota, c'est un nombre entre 0 et 1. Si votre add-on utilise plus que son quota, cette valeur est supérieure à 1,0.
Par conséquent, lorsque vous êtes averti que vous êtes hors quota, vous devez répondre en supprimant les données de l'espace de stockage jusqu'à ce que votre quotaUsage soit inférieur ou égal à 1.
ss.storage.myList = [ /* some long array */ ];
ss.on("OverQuota", function () {
while (ss.quotaUsage > 1)
ss.storage.myList.pop();
});
Navigation privée
Si votre mémoire est liée à l'histoire de vos utilisateurs Web, des renseignements personnels, ou d'autres données sensibles, votre add-on devrait respecter la navigation privé .
Pour en savoir plus sur la façon de choisir en mode de navigation privée et comment utiliser le SDK pour éviter de stocker des données d'utilisateur associées aux fenêtres privées, reportez-vous à la documentation du private-browsing Module .
Globals
Propriétés
storage
Un objet persistant privé de votre add-on.
quotaUsage
Un certain nombre dans l'intervalle [0, Infinity) qui indique le pourcentage de quota occupé par le stockage. Une valeur dans l'intervalle [0, 1] indique que le stockage est dans le quota. Une valeur supérieure à 1 indique que le stockage dépasse le quota.
Événements
OverQuota
Le module émet cet événement lorsque votre stockage add-ons dépasse son quota.