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 offre un moyen spécifique à l'extension de conserver les données utilisateur et l'état. Ce service est semblable aux API de stockage de la plate-forme Web (IndexedDB et Storage), mais il a été conçu 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 les opérations de lecture et d'écriture groupées.
• Même si l'utilisateur vide le cache et vide 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.
• Inclut un espace de stockage géré exclusif en lecture seule pour les règles d'entreprise.

Même si les extensions peuvent utiliser l'interface [Storage][mdn-storage] (accessible depuis window.localStorage) dans certains contextes (pop-up et autres pages HTML), cela n'est pas recommandé pour les raisons suivantes:

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

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

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 d'extension, vérifiez vos données dans chrome.storage.
4. Si vos données sont introuvables, [créez][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 concernant le fonctionnement des API de stockage Web dans les extensions. Pour en savoir plus, consultez le [Stockage et cookies][storage-and-cookies].

Zones de stockage

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

storage.local

Les données sont stockées localement, puis supprimées 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.

Attention : Avant Chrome 114, le quota était d'environ 5 Mo.

storage.sync

Si la synchronisation est activée, les données sont synchronisées avec le 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 ou 8 Ko par élément. Pensez à l'utiliser pour conserver les paramètres utilisateur sur les navigateurs synchronisés.

Avertissement: Les zones de stockage locales et synchronisées ne doivent pas stocker de données utilisateur confidentielles, car elles ne sont pas chiffrées. Lorsque vous manipulez des données sensibles, pensez à utiliser l'espace de stockage session pour conserver les valeurs en mémoire jusqu'à l'arrêt du navigateur.

storage.session

Stocke les données en mémoire pendant toute la durée d'une session de navigateur. Par défaut, il n'est pas exposé 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 dans les exécutions de service workers.

Avertissement: Avant Chrome 112, le quota était d'environ 1 Mo.

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.

Fichier manifeste

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

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

Utilisation

Les exemples suivants illustrent les paramètres local, sync et session d'espaces de stockage:

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 la zone de stockage managed, consultez Fichier manifeste pour les zones de stockage.

Limites de stockage et de limitation

Ne considérez pas l'ajout à l'API Storage comme une installation dans un gros camion. Pensez à ajouter à le stockage comme étant comme mettre quelque chose dans un tuyau. Il se peut que le tuyau contienne déjà de la matière peut même être rempli. Partez toujours du principe qu'il existe un délai entre le moment où vous ajoutez du contenu à l'espace de stockage et le moment où il est réellement enregistré.

Pour en savoir plus sur les limites de l'espace de stockage et ce qui se passe en cas de dépassement, consultez les informations sur les quotas pour sync, local et session.

Cas d'utilisation

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

Réponse synchrone aux mises à jour de l'espace de stockage

Pour suivre les modifications apportées à l'espace de stockage, vous pouvez ajouter un écouteur à son événement onChanged. Lorsqu'un changement est effectué dans l'espace de stockage, cet événement 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 pousser cette idée encore plus loin. Dans cet exemple, la page d'options permet à l'utilisateur d'activer/de désactiver le "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

Comme les service workers ne s'exécutent pas toujours, les extensions Manifest V3 doivent parfois de charger les données de manière asynchrone à partir du stockage avant d'exécuter leurs gestionnaires d'événements. Pour ce faire, L'extrait de code suivant utilise un gestionnaire d'événements asynchrones action.onClicked qui attend l'événement storageCache. global à remplir 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:

• Extension Global Search :
• Extension de détecteur d'eau.

Types

AccessLevel

Chrome 102 et versions ultérieures

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

Énumération

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

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

StorageArea

Propriétés

• onChanged

  Événement<functionvoid>

  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

    fonction

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

    (changes: object) => void

    • modifications

      objet

• effacer

  vide

  <ph type="x-smartling-placeholder"></ph> Promesse

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

  La fonction clear se présente comme suit:

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

  • rappel

    function facultatif

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

    () => void

  • retours

    Promesse<void>

    Chrome (version 88 ou ultérieure)

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

• get

  vide

  <ph type="x-smartling-placeholder"></ph> 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[] | objet facultatif

    Une clé unique à obtenir, une liste de clés à obtenir ou un dictionnaire spécifiant les 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

    function facultatif

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

    (items: object) => void

    • articles

      objet

      Objet avec éléments dans leurs mappages clé-valeur.

  • retours

    Promise&lt;object&gt;

    Chrome (version 88 ou ultérieure)

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

• getBytesInUse

  vide

  <ph type="x-smartling-placeholder"></ph> 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[] facultatif

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

  • rappel

    function facultatif

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

    (bytesInUse: number) => void

    • bytesInUse

      Nombre

      Quantité d'espace de stockage utilisée (en octets).

  • retours

    Promise&lt;number&gt;

    Chrome (version 88 ou ultérieure)

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

• getKeys

  vide

  <ph type="x-smartling-placeholder"></ph> Promesse En attente

  Récupère toutes les clés de l'espace de stockage.

  La fonction getKeys se présente comme suit:

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

  • rappel

    function facultatif

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

    (keys: string[]) => void

    • clés

      chaîne[]

      Tableau avec des clés lues dans l'espace de stockage.

  • retours

    Promise&lt;string[]&gt;

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

• supprimer

  vide

  <ph type="x-smartling-placeholder"></ph> 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

    string | chaîne[]

    Clé unique ou liste de clés pour les éléments à supprimer.

  • rappel

    function facultatif

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

    () => void

  • retours

    Promesse<void>

    Chrome (version 88 ou ultérieure)

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

• set

  vide

  <ph type="x-smartling-placeholder"></ph> Promesse

  Définit plusieurs éléments.

  La fonction set se présente comme suit:

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

  • articles

    objet

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

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

  • rappel

    function facultatif

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

    () => void

  • retours

    Promesse<void>

    Chrome (version 88 ou ultérieure)

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

• setAccessLevel

  vide

  <ph type="x-smartling-placeholder"></ph> Promesse Chrome 102 ou version ultérieure

  Définit le niveau d'accès souhaité pour la zone de stockage. Par défaut, seuls les contextes de confiance sont sélectionnés.

  La fonction setAccessLevel se présente comme suit:

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

  • accessOptions

    objet

    • accessLevel

      AccessLevel

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

  • rappel

    function facultatif

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

    () => void

  • retours

    Promesse<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

  Tout facultatif

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

• oldValue

  Tout facultatif

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

Propriétés

local

Les éléments de la zone de stockage local se trouvent 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 le stockage local, mesurée par la concaténation 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 lorsque vous utilisez 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+

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 & objet

Propriétés

• QUOTA_BYTES

  10485760
  

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

sync

Les éléments de l'espace de stockage sync sont synchronisés à l'aide de 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 qui entraîneraient le dépassement de cette limite échoueront immédiatement et définiront runtime.lastError en cas de rappel ou de rejet d'une promesse.

• MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

  1000000
  

  <ph type="x-smartling-placeholder"></ph> 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. Cette valeur est de 1 toutes les deux secondes, c'est-à-dire un plafond inférieur à la limite d'écritures par minute plus élevée à court terme.

  Les mises à jour qui entraîneraient le dépassement de cette limite échouent immédiatement et définissent runtime.lastError en cas de rappel ou 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, ce qui offre un débit plus élevé que les écritures par heure sur une période plus courte.

  Les mises à jour qui entraîneraient le dépassement de cette limite échouent immédiatement et définissent runtime.lastError en cas de rappel ou de rejet d'une promesse.

• QUOTA_BYTES

  102400
  

  Quantité totale maximale (en octets) de données pouvant être stockée dans l'espace de stockage synchronisé, mesurée par la concaténation JSON de chaque valeur plus la longueur de chaque clé. Les mises à jour qui entraîneraient le dépassement de cette limite échouent immédiatement et définissent runtime.lastError en cas de rappel ou 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 concaténation de sa valeur JSON plus la longueur de sa clé. Les mises à jour contenant des éléments supérieurs à cette limite échouent immédiatement et définissent runtime.lastError lorsque vous utilisez un rappel ou qu'une promesse est refusée.

Événements

onChanged

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

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

Paramètres

• rappel

  fonction

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

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

  • modifications

    objet

  • areaName

    chaîne