browser.storage

Description

Utilisez l'API chrome.storage pour stocker, récupérer et suivre les modifications apportées aux données utilisateur.

Autorisations

storage

Pour utiliser l'API Storage, déclarez l'autorisation "storage" dans le fichier manifeste de l'extension. Exemple :

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

Exemples

Les exemples suivants illustrent les zones de stockage local, sync et session :

Exemple (local)

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

Exemple (synchrone)

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

Exemple (session)

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

Pour voir d'autres démonstrations de l'API Storage, explorez l'un des exemples suivants :

Concepts et utilisation

L'API Storage fournit un moyen spécifique aux extensions de conserver les données et l'état de l'utilisateur. Elle est semblable aux API de stockage de la plate-forme Web (IndexedDB et Storage), mais elle a été conçue pour répondre aux besoins de stockage des extensions. Voici quelques-unes des principales fonctionnalités :

  • Tous les contextes d'extension, y compris le service worker d'extension et les scripts de contenu, ont accès à l'API Storage.
  • Les valeurs sérialisables JSON sont stockées en tant que propriétés d'objet.
  • L'API Storage est asynchrone avec des opérations de lecture et d'écriture groupées.
  • Même si l'utilisateur vide le cache et l'historique de navigation, les données sont conservées.
  • Les paramètres stockés sont conservés même lorsque vous utilisez le mode navigation privée fractionné.
  • Inclut une zone de stockage gérée exclusive en lecture seule pour les règles d'entreprise.

Les extensions peuvent-elles utiliser les API de stockage Web ?

Bien que les extensions puissent utiliser l'interface Storage (accessible depuis window.localStorage) dans certains contextes (pop-up et autres pages HTML), nous ne le recommandons pas pour les raisons suivantes :

  • Les service workers d'extension ne peuvent pas utiliser l'API Web Storage.
  • Les scripts de contenu partagent l'espace de stockage avec la page hôte.
  • Les données enregistrées à l'aide de l'API Web Storage sont perdues lorsque l'utilisateur efface son historique de navigation.

Pour déplacer des données des API de stockage Web vers les API de stockage d'extension à partir d'un service worker :

  1. Préparez une page HTML et un fichier de script pour le document hors écran. Le fichier de script doit contenir une routine de conversion et un gestionnaire onMessage.
  2. Dans le service worker de l'extension, vérifiez browser.storage pour vos données.
  3. Si vos données sont introuvables, appelez createDocument().
  4. Une fois la promesse renvoyée, appelez sendMessage() pour lancer la routine de conversion.
  5. Dans le gestionnaire onMessage du document hors écran, appelez la routine de conversion.

Il existe également quelques nuances dans le fonctionnement des API de stockage Web dans les extensions. Pour en savoir plus, consultez l'article Stockage et cookies.

Limites de stockage et de limitation du débit

L'API Storage est soumise à des limites d'utilisation :

  • Le stockage des données a un coût en termes de performances, et l'API inclut des quotas de stockage. Planifiez les données que vous souhaitez stocker afin de conserver de l'espace de stockage.
  • Le stockage peut prendre un certain temps. Structurez votre code pour tenir compte de ce délai.

Pour en savoir plus sur les limites des zones de stockage et sur ce qui se passe lorsqu'elles sont dépassées, consultez les informations sur les quotas pour sync, local et session.

Espaces de stockage

L'API Storage est divisée en plusieurs zones de stockage :

Local

Les données sont stockées localement et effacées lorsque l'extension est supprimée. La limite de stockage est de 10 Mo (5 Mo dans Chrome 113 et versions antérieures), mais elle peut être augmentée en demandant l'autorisation "unlimitedStorage". Nous vous recommandons d'utiliser storage.local pour stocker de plus grandes quantités de données. Par défaut, il est exposé aux scripts de contenu, mais ce comportement peut être modifié en appelant browser.storage.local.setAccessLevel().

Géré

Le stockage géré est en lecture seule pour les extensions installées par des règles. Il est géré par les administrateurs système, à l'aide d'un schéma défini par le développeur et de règles d'entreprise. Les règles sont semblables aux options, mais elles sont configurées par un administrateur système, et non par l'utilisateur. Cela permet de préconfigurer l'extension pour tous les utilisateurs d'une organisation.

Par défaut, storage.managed est exposé aux scripts de contenu, mais ce comportement peut être modifié en appelant browser.storage.managed.setAccessLevel(). Pour en savoir plus sur les règles, consultez la documentation pour les administrateurs. Pour en savoir plus sur la zone de stockage managed, consultez Manifeste pour les zones de stockage.

Session

Le stockage de session conserve les données en mémoire pendant le chargement d'une extension. L'espace de stockage est vidé si l'extension est désactivée, actualisée ou mise à jour, et lorsque le navigateur redémarre. Par défaut, il n'est pas exposé aux scripts de contenu, mais ce comportement peut être modifié en appelant browser.storage.session.setAccessLevel(). La limite de stockage est de 10 Mo (1 Mo dans Chrome 111 et versions antérieures).

L'interface storage.session est l'une des interfaces que nous recommandons pour les service workers.

Synchroniser

Si l'utilisateur active la synchronisation, les données sont synchronisées avec tous les navigateurs Chrome auxquels il est connecté. Si elle est désactivée, elle se comporte comme storage.local. Chrome stocke les données localement lorsque le navigateur est hors connexion et reprend la synchronisation lorsqu'il est de nouveau en ligne. La limite de quota est d'environ 100 Ko, soit 8 Ko par élément.

Nous vous recommandons d'utiliser storage.sync pour conserver les paramètres utilisateur sur les navigateurs synchronisés. Si vous travaillez avec des données utilisateur sensibles, utilisez plutôt storage.session. Par défaut, storage.sync est exposé aux scripts de contenu, mais ce comportement peut être modifié en appelant browser.storage.sync.setAccessLevel().

Méthodes et événements

Toutes les zones de stockage implémentent l'interface StorageArea.

get()

La méthode get() vous permet de lire une ou plusieurs clés à partir d'un StorageArea.

getBytesInUse()

La méthode getBytesInUse() vous permet de voir le quota utilisé par un StorageArea.

getKeys()

La méthode getKeys() vous permet d'obtenir toutes les clés stockées dans un StorageArea.

remove()

La méthode remove() vous permet de supprimer un élément d'un StorageArea.

set()

La méthode set() vous permet de définir un élément dans un StorageArea.

setAccessLevel()

La méthode setAccessLevel() vous permet de contrôler l'accès à un StorageArea.

clear()

La méthode clear() vous permet d'effacer toutes les données d'un StorageArea.

onChanged

L'événement onChanged vous permet de surveiller les modifications apportées à un StorageArea.

Cas d'utilisation

Les sections suivantes présentent des cas d'utilisation courants de l'API Storage.

Répondre aux mises à jour du stockage

Pour suivre les modifications apportées au stockage, ajoutez un écouteur à son événement onChanged. Lorsqu'un changement se produit dans l'espace de stockage, cet événement se déclenche. L'exemple de code écoute les modifications suivantes :

background.js:

browser.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

Nous pouvons aller encore plus loin. Dans cet exemple, nous avons une page d'options qui permet à l'utilisateur d'activer ou de désactiver un "mode débogage" (implémentation non présentée ici). La page d'options enregistre immédiatement les nouveaux paramètres dans storage.sync, et le service worker utilise storage.onChanged pour appliquer le paramètre dès que possible.

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
browser.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

Préchargement asynchrone depuis l'espace de stockage

Étant donné que les service workers ne s'exécutent pas en permanence, les extensions Manifest V3 doivent parfois charger des données de manière asynchrone à partir de l'espace de stockage avant d'exécuter leurs gestionnaires d'événements. Pour ce faire, l'extrait de code suivant utilise un gestionnaire d'événements action.onClicked asynchrone qui attend que la variable globale storageCache soit renseignée avant d'exécuter sa logique.

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  browser.storage.sync.set(storageCache);
});

Outils de développement

Vous pouvez afficher et modifier les données stockées à l'aide de l'API dans les outils de développement. Pour en savoir plus, consultez la page Afficher et modifier l'espace de stockage des extensions dans la documentation des outils de développement.

Types

AccessLevel

Navigateur Chrome 102 ou version ultérieure * depuis Chrome 148

Niveau d'accès de la zone de stockage.

Énumération

"TRUSTED_CONTEXTS"
Spécifie les contextes provenant de l'extension elle-même.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Spécifie les contextes provenant de l'extérieur de l'extension.

StorageChange

Propriétés

  • newValue

    facultatif

    Nouvelle valeur de l'élément, s'il y en a une.

  • oldValue

    facultatif

    Ancienne valeur de l'élément, le cas échéant.

Propriétés

local

Les éléments de la zone de stockage local sont locaux pour chaque machine.

Type

StorageArea et objet

Propriétés

  • QUOTA_BYTES

    10485760

    Quantité maximale (en octets) de données pouvant être stockées dans l'espace de stockage local, mesurée par la conversion en chaîne JSON de chaque valeur plus la longueur de chaque clé. Cette valeur sera ignorée si l'extension dispose de l'autorisation unlimitedStorage. Les mises à jour qui entraîneraient un dépassement de cette limite échouent immédiatement et définissent runtime.lastError si vous utilisez un rappel, ou une promesse refusée si vous utilisez async/await.

managed

Les éléments de la zone de stockage managed sont définis par une règle d'entreprise configurée par l'administrateur du domaine et sont en lecture seule pour l'extension. Toute tentative de modification de cet espace de noms entraîne une erreur. Pour savoir comment configurer une règle, consultez Manifeste pour les zones de stockage.

Type

StorageArea

session

Navigateur Chrome 102 ou version ultérieure * Depuis Chrome 148 MV3 ou version ultérieure

Les éléments de la zone de stockage session sont stockés en mémoire et ne sont pas conservés sur le disque.

Type

StorageArea et objet

Propriétés

  • QUOTA_BYTES

    10485760

    Quantité maximale (en octets) de données pouvant être stockées en mémoire, mesurée en estimant l'utilisation de la mémoire allouée dynamiquement pour chaque valeur et clé. Les mises à jour qui entraîneraient un dépassement de cette limite échouent immédiatement et définissent runtime.lastError lorsqu'un rappel est utilisé ou qu'une promesse est rejetée.

sync

Les éléments de la zone de stockage sync sont synchronisés à l'aide de la synchronisation Chrome.

Type

StorageArea et objet

Propriétés

  • MAX_ITEMS

    512

    Nombre maximal d'éléments pouvant être stockés dans l'espace de stockage de synchronisation. Les mises à jour qui entraîneraient un dépassement de cette limite échoueront immédiatement et définiront runtime.lastError lors de l'utilisation d'un rappel ou lorsqu'une promesse est rejetée.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Obsolète

    L'API storage.sync n'a plus de quota d'opérations d'écriture soutenues.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    Nombre maximal d'opérations set, remove ou clear pouvant être effectuées chaque heure. Cela correspond à une requête toutes les deux secondes, un plafond inférieur à la limite d'écritures par minute plus élevée à court terme.

    Les mises à jour qui entraîneraient un dépassement de cette limite échouent immédiatement et définissent runtime.lastError lorsqu'un rappel est utilisé ou qu'une promesse est rejetée.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Nombre maximal d'opérations set, remove ou clear pouvant être effectuées chaque minute. Cette limite est de deux par seconde, ce qui permet un débit plus élevé que les écritures par heure sur une période plus courte.

    Les mises à jour qui entraîneraient un dépassement de cette limite échouent immédiatement et définissent runtime.lastError lorsqu'un rappel est utilisé ou qu'une promesse est rejetée.

  • QUOTA_BYTES

    102400

    Quantité totale maximale (en octets) de données pouvant être stockées dans l'espace de stockage de synchronisation, mesurée par la chaîne JSON de chaque valeur plus la longueur de chaque clé. Les mises à jour qui entraîneraient un dépassement de cette limite échouent immédiatement et définissent runtime.lastError lorsqu'un rappel est utilisé ou qu'une promesse est rejetée.

  • QUOTA_BYTES_PER_ITEM

    8192

    Taille maximale (en octets) de chaque élément individuel dans l'espace de stockage de synchronisation, mesurée par la chaîne JSON de sa valeur plus la longueur de sa clé. Les mises à jour contenant des éléments dépassant cette limite échoueront immédiatement et définiront runtime.lastError lors de l'utilisation d'un rappel ou lorsqu'une promesse est refusée.

Événements

onChanged

browser.storage.onChanged.addListener(
  callback: function,
)

Se déclenche lorsqu'un ou plusieurs éléments sont modifiés.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (changes: object, areaName: string) => void

    • modifications

      objet

    • areaName

      chaîne