chrome.storage

Description

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

Autorisations

storage

Présentation

L'API Storage fournit une méthode spécifique à l'extension pour conserver les données utilisateur et l'état. Elle est semblable aux API de stockage de la plate-forme Web (IndexedDB et Storage), mais 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 JSON sérialisables 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 efface l'historique de navigation, ces données sont conservées.
  • Les paramètres stockés sont conservés même en mode mode navigation privée fractionnée.
  • Inclut un espace de stockage géré exclusif en lecture seule pour les règles d'entreprise.

Bien que les extensions puissent utiliser l'interface [Storage][mdn-storage] (accessible depuis window.localStorage) dans certains contextes (pop-up et autres pages HTML), elle n'est pas recommandée pour les raisons suivantes:

  • Le service worker de l'extension ne peut pas accéder à Storage.
  • Les scripts de contenu partagent le stockage avec la page hôte.
  • Les données enregistrées à l'aide de l'interface Storage sont perdues lorsque l'utilisateur efface son historique de navigation.

Pour transférer des données des API de stockage Web vers les API de stockage d'extensions à partir d'un service worker:

  1. Créez un document hors écran avec une routine de conversion et un gestionnaire [onMessage][on-message].
  2. Ajoutez une routine de conversion à un document hors écran.
  3. Dans le service worker de l'extension, vérifiez les données sur chrome.storage.
  4. Si vos données sont introuvables, [create][create-offscreen] un document hors écran et appelez [sendMessage()][send-message] pour lancer la routine de conversion.
  5. Dans le gestionnaire onMessage du document hors écran, appelez la routine de conversion.

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

Zones de stockage

L'API Storage est divisée en quatre buckets ("espaces de stockage"):

storage.local
Les données sont stockées localement, ce qui est effacé lorsque l'extension est supprimée. La limite de quota est d'environ 10 Mo, mais vous pouvez l'augmenter en demandant l'autorisation "unlimitedStorage". Pensez à l'utiliser pour stocker de plus grandes quantités de données.
storage.sync
Si la synchronisation est activée, les données sont synchronisées avec n'importe quel navigateur Chrome auquel l'utilisateur est connecté. Si cette règle 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, 8 Ko par élément. Pensez à l'utiliser pour conserver les paramètres utilisateur dans les navigateurs synchronisés.
storage.session
Conserve les données en mémoire pendant la durée d'une session de navigateur. Par défaut, elle n'est pas exposée aux scripts de contenu, mais vous pouvez modifier ce comportement en définissant chrome.storage.session.setAccessLevel(). La limite de quota est d'environ 10 Mo. Pensez à l'utiliser pour stocker des variables globales sur les exécutions de service worker.
storage.managed
Les administrateurs peuvent utiliser un schéma et des règles d'entreprise pour configurer les paramètres d'une extension compatible dans un environnement géré. Cet espace de stockage est en lecture seule.

Manifest

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

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

Utilisation

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

storage.local

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.sync

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

storage.session

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value currently is " + result.key);
});

Pour en savoir plus sur l'espace de stockage managed, consultez Fichier manifeste des zones de stockage.

Limites de stockage et de limitation

Ne pensez pas à ajouter des éléments à l'API Storage comme à mettre des choses dans un gros camion. Considérez l’ajout au stockage comme étant comme mettre quelque chose dans un pipe. Le tuyau peut déjà contenir du matériau, et il peut même être rempli. Supposons toujours un délai entre l'ajout à l'espace de stockage et l'enregistrement réel.

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

Cas d'utilisation

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

Réponse synchrone aux mises à jour du stockage

Pour suivre les modifications apportées à l'espace de stockage, vous pouvez ajouter un écouteur à son événement onChanged. Lorsqu'un élément change dans l'espace de stockage, il se déclenche. L'exemple de code écoute ces modifications:

background.js:

chrome.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/de désactiver un "mode débogage" (implémentation non illustré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;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.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
chrome.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 à partir du stockage

Étant donné que les service workers ne s'exécutent pas toujours, 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 valeur 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 = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.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;
  chrome.storage.sync.set(storageCache);
});

Exemples d'extensions

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

Types

AccessLevel

Chrome 102 et versions ultérieures

Niveau d'accès à la zone de stockage

Enum

"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.

StorageArea

Propriétés

  • onChanged

    Événement<functionvoidvoid>

    Chrome 73 et versions ultérieures

    Déclenché lorsqu'un ou plusieurs éléments changent

    La fonction onChanged.addListener se présente comme suit : 

    (callback: function)=> {...}

    • rappel

      function

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

      (changes: object)=>void

      • modifications

        objet

  • effacer

    void

    Promesse

    Supprime tous les éléments de l'espace de stockage.

    La fonction clear se présente comme suit : 

    (callback?: function)=> {...}

    • rappel

      fonction facultative

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

      ()=>void

    • retours

      Promise<void>

      Chrome 88 et versions ultérieures

      Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

  • get

    void

    Promesse

    Récupère un ou plusieurs éléments de l'espace de stockage.

    La fonction get se présente comme suit : 

    (keys?: string|string[]|object,callback?: function)=> {...}

    • clés

      string|string[]|object optional

      Une seule clé à obtenir, une liste de clés à obtenir ou un dictionnaire spécifiant des valeurs par défaut (voir la description de l'objet). Une liste ou un objet vide renvoie un objet de résultat vide. Transmettez null pour obtenir l'intégralité du contenu de l'espace de stockage.

    • rappel

      fonction facultative

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

      (items: object)=>void

      • items

        objet

        Objet comportant des éléments dans leurs mappages de clé-valeur

    • retours

      Promise<object>

      Chrome 88 et versions ultérieures

      Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

  • getBytesInUse

    void

    Promesse

    Récupère la quantité d'espace (en octets) utilisée par un ou plusieurs éléments.

    La fonction getBytesInUse se présente comme suit : 

    (keys?: string|string[],callback?: function)=> {...}

    • clés

      string|string[] optional

      Une seule clé ou liste de clés pour laquelle vous souhaitez obtenir l'utilisation totale. Une liste vide renvoie 0. Transmettez null pour obtenir l'utilisation totale de tout l'espace de stockage.

    • rappel

      fonction facultative

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

      (bytesInUse: number)=>void

      • bytesInUse

        Nombre

        Quantité d'espace utilisée dans l'espace de stockage, en octets.

    • retours

      Promesse<number>

      Chrome 88 et versions ultérieures

      Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

  • supprimer

    void

    Promesse

    Supprime un ou plusieurs éléments de l'espace de stockage.

    La fonction remove se présente comme suit : 

    (keys: string|string[],callback?: function)=> {...}

    • clés

      chaîne|chaîne[]

      Une seule clé ou une liste de clés pour les éléments à supprimer.

    • rappel

      fonction facultative

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

      ()=>void

    • retours

      Promise<void>

      Chrome 88 et versions ultérieures

      Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

  • set

    void

    Promesse

    Définit plusieurs éléments.

    La fonction set se présente comme suit : 

    (items: object,callback?: function)=> {...}

    • items

      objet

      Objet qui donne à chaque paire clé/valeur à utiliser pour mettre à jour l'espace de stockage. Les autres paires clé/valeur présentes dans l'espace de stockage ne seront pas affectées.

      Les valeurs primitives telles que les nombres seront sérialisées comme prévu. Les valeurs avec typeof "object" et "function" seront généralement sérialisées en {}, à l'exception de Array (sérialise comme prévu), Date et Regex (sérialiser à l'aide de leur représentation String).

    • rappel

      fonction facultative

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

      ()=>void

    • retours

      Promise<void>

      Chrome 88 et versions ultérieures

      Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

  • setAccessLevel

    void

    Promesse Chrome 102 et versions ultérieures

    Définit le niveau d'accès souhaité pour l'espace de stockage. Par défaut, seuls les contextes approuvés sont considérés comme approuvés.

    La fonction setAccessLevel se présente comme suit : 

    (accessOptions: object,callback?: function)=> {...}

    • accessOptions

      objet

      • accessLevel

        AccessLevel

        Niveau d'accès à l'espace de stockage.

    • rappel

      fonction facultative

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

      ()=>void

    • retours

      Promise<void>

      Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

StorageChange

Propriétés

  • newValue

    Toute valeur facultatif

    Nouvelle valeur de l'élément, s'il existe une nouvelle valeur.

  • oldValue

    Toute valeur facultatif

    Ancienne valeur de l'élément, s'il existait une ancienne valeur.

Propriétés

local

Les éléments de l'espace de stockage local sont stockés localement sur chaque machine.

Type

StorageArea&objet

Propriétés

  • QUOTA_BYTES

    10485760

    Quantité maximale (en octets) de données pouvant être stockée dans l'espace de stockage local. Elle est mesurée par la 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 le dépassement de cette limite échouent immédiatement et définissent runtime.lastError en cas d'utilisation d'un rappel, ou une promesse refusée si vous utilisez async/await.

managed

Les éléments de l'espace 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 génère une erreur. Pour en savoir plus sur la configuration d'une règle, consultez Fichier manifeste pour les zones de stockage.

Type

StorageArea

session

Chrome 102 et versions ultérieures MV3 et versions ultérieures

Les éléments présents dans l'espace de stockage session sont stockés en mémoire et ne sont pas conservés sur le disque.

Type

StorageArea&objet

Propriétés

  • QUOTA_BYTES

    10485760

    Quantité maximale (en octets) de données pouvant être stockées en mémoire. Elle est mesurée en estimant l'utilisation de la mémoire allouée de manière dynamique pour chaque valeur et chaque clé. Les mises à jour susceptibles de dépasser cette limite échouent immédiatement et définissent runtime.lastError lors de l'utilisation d'un rappel ou en cas de rejet d'une promesse.

sync

Les éléments de l'espace de stockage sync sont synchronisés via la synchronisation Chrome.

Type

StorageArea&objet

Propriétés

  • MAX_ITEMS

    512

    Nombre maximal d'éléments pouvant être stockés dans l'espace de stockage synchronisé. Les mises à jour entraînant le dépassement de cette limite échoueront immédiatement et définiront runtime.lastError lors de l'utilisation d'un rappel ou en cas de refus d'une promesse.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Obsolète

    L'API storage.sync ne dispose plus d'un 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 à 1 toutes les deux secondes, soit un plafond inférieur à la limite supérieure d'écritures par minute à court terme.

    Les mises à jour susceptibles de dépasser cette limite échouent immédiatement et définissent runtime.lastError lors de l'utilisation d'un rappel ou en cas de rejet d'une promesse.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Nombre maximal d'opérations set, remove ou clear pouvant être effectuées chaque minute. Cela correspond à 2 par seconde, offrant un débit supérieur aux écritures par heure sur une période plus courte.

    Les mises à jour susceptibles de dépasser cette limite échouent immédiatement et définissent runtime.lastError lors de l'utilisation d'un rappel ou en cas de rejet d'une promesse.

  • QUOTA_BYTES

    102400

    Volume total maximal (en octets) de données pouvant être stocké dans l'espace de stockage synchronisé. Il est mesuré par la chaîne JSON de chaque valeur plus la longueur de chaque clé. Les mises à jour susceptibles de dépasser cette limite échouent immédiatement et définissent runtime.lastError lors de l'utilisation d'un rappel ou en cas de rejet d'une promesse.

  • QUOTA_BYTES_PER_ITEM

    8192

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

Événements

onChanged

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

Déclenché lorsqu'un ou plusieurs éléments changent

Paramètres

  • rappel

    function

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

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

    • modifications

      objet

    • areaName

      chaîne