Cette page a été traduite par l'API Cloud Translation.

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 un moyen spécifique à l'extension de conserver les données utilisateur et l'état. Il est semblable aux API de stockage de la plate-forme Web (IndexedDB et Storage), mais 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 de l'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 persistent.
Les paramètres stockés sont conservés même lorsque vous utilisez la navigation privée fractionnée.
Inclut une zone de stockage gérée en lecture seule exclusive pour les règles d'entreprise.

Bien que les extensions puissent utiliser l'interface [Storage][mdn-storage] (accessible depuis window.localStorage) dans certains contextes (fenêtre 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 à l'aide de l'interface Storage sont perdues lorsque l'utilisateur efface son historique de navigation.

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

Créez un document hors écran avec une routine de conversion et un gestionnaire [onMessage][on-message].
Ajoutez une routine de conversion à un document hors écran.
Dans le service worker de l'extension, recherchez chrome.storage pour vos données.
Si vos données ne sont pas trouvées, [create][create-offscreen] un document hors écran et appelez [sendMessage()][send-message] pour démarrer la routine de conversion.
Dans le gestionnaire onMessage du document hors écran, appelez la routine de conversion.

Le fonctionnement des API de stockage Web dans les extensions présente également quelques nuances. Pour en savoir plus, consultez l'article [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 et sont effacé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.

storage.sync: Si la synchronisation est activée, les données sont synchronisées avec tous les navigateurs Chrome auxquels l'utilisateur 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. Envisagez de l'utiliser pour conserver les paramètres utilisateur dans les navigateurs synchronisés.

Avertissement:Les zones de stockage locales et de synchronisation ne doivent pas stocker de données utilisateur confidentielles, car elles ne sont pas chiffrées. Lorsque vous travaillez avec des données sensibles, envisagez d'utiliser la zone de stockage session pour conserver des valeurs en mémoire jusqu'à l'arrêt du navigateur.

storage.session: Stocke les données en mémoire pendant la durée d'une session de navigateur. Par défaut, il n'est pas exposé aux scripts de contenu, mais ce comportement peut être modifié en définissant chrome.storage.session.setAccessLevel(). La limite de quota est d'environ 10 Mo. Pensez à l'utiliser pour stocker des variables globales lors des exécutions du 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 secondaire dans un environnement géré. Cette zone de stockage est en lecture seule.

Fichier manifeste

Pour utiliser l'API Storage, 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 la zone de stockage managed, consultez la section Fichier manifeste pour les zones de stockage.

Limites de stockage et de limitation

N'imaginez pas que l'ajout à l'API Storage consiste à mettre des choses dans un grand camion. Pensez à l'ajout d'espace de stockage comme à la mise d'un objet dans un tuyau. Il est possible que le tuyau contienne déjà du matériel, voire qu'il soit rempli. Prévoyez toujours un délai entre le moment où vous ajoutez des données au stockage et celui où elles sont réellement enregistrées.

Pour en savoir plus sur les limites de zone 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 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 au stockage, vous pouvez ajouter un écouteur à son événement onChanged. Lorsque quelque chose change dans le stockage, cet événement se déclenche. L'exemple de code écoute les modifications suivantes:

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" (l'implémentation n'est pas présentée ici). La page des 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 services workers ne sont pas toujours exécutés, les extensions Manifest V3 doivent parfois charger de manière asynchrone des données à 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 action.onClicked asynchrone qui attend que le global storageCache soit renseigné 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, consultez l'un des exemples suivants:

Types

AccessLevel

Chrome 102 ou version ultérieure

Niveau d'accès de 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 les contextes provenant de l'extérieur de l'extension.

StorageArea

Propriétés

onChanged

Event<functionvoidvoid>

Chrome 73 ou version ultérieure

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

Promesse

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

La fonction clear se présente comme suit :
```
(callback?: function) => {...}
```
- rappel
  
  fonction facultatif
  
  Le paramètre callback se présente comme suit :
```
() => void
```
- retours
  Promise<void>
  
  Chrome 88 ou version 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

Promesse

Récupère un ou plusieurs éléments à partir du stockage.

La fonction get se présente comme suit :
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- clés
  
  chaîne | chaîne[] | objet facultatif
  
  Une seule clé à récupérer, une liste de clés à récupérer 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 du stockage.
- rappel
  
  fonction facultatif
  
  Le paramètre callback se présente comme suit :
```
(items: object) => void
```
  - éléments
    
    objet
    
    Objet avec des éléments dans ses mappages clé-valeur.
- retours
  Promise<object>
  
  Chrome 88 ou version 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

Promesse

Obtient l'espace (en octets) utilisé par un ou plusieurs éléments.

La fonction getBytesInUse se présente comme suit :
```
(keys?: string | string[], callback?: function) => {...}
```
- clés
  
  chaîne | chaîne[] facultatif
  
  Clé unique ou liste de clés pour lesquelles obtenir l'utilisation totale. Une liste vide renvoie la valeur 0. Transmettez null pour obtenir l'utilisation totale de l'espace de stockage.
- rappel
  
  fonction facultatif
  
  Le paramètre callback se présente comme suit :
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    number
    
    Espace utilisé dans l'espace de stockage, en octets.
- retours
  Promise<number>
  
  Chrome 88 ou version 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

Promesse : Chrome 130 ou version ultérieure

Récupère toutes les clés du stockage.

La fonction getKeys se présente comme suit :
```
(callback?: function) => {...}
```
- rappel
  
  fonction facultatif
  
  Le paramètre callback se présente comme suit :
```
(keys: string[]) => void
```
  - clés
    
    chaîne[]
    
    Tableau contenant les clés lues à partir de l'espace de stockage.
- retours
  Promise<string[]>
  
  Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
supprimer

vide

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[]
  
  Clé unique ou liste de clés pour les éléments à supprimer.
- rappel
  
  fonction facultatif
  
  Le paramètre callback se présente comme suit :
```
() => void
```
- retours
  Promise<void>
  
  Chrome 88 ou version 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

Promesse

Définit plusieurs éléments.

La fonction set se présente comme suit :
```
(items: object, callback?: function) => {...}
```
- éléments
  
  objet
  
  Objet qui fournit chaque paire clé/valeur à utiliser pour mettre à jour le stockage. Les autres paires clé/valeur stockées 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" sont généralement sérialisées en {}, à l'exception de Array (sérialisée comme prévu), Date et Regex (sérialisée à l'aide de leur représentation String).
- rappel
  
  fonction facultatif
  
  Le paramètre callback se présente comme suit :
```
() => void
```
- retours
  Promise<void>
  
  Chrome 88 ou version 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

Promise Chrome 102 et versions ultérieures

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

La fonction setAccessLevel se présente comme suit :
```
(accessOptions: object, callback?: function) => {...}
```
- accessOptions
  
  objet
  - accessLevel
    
    AccessLevel
    
    Niveau d'accès de l'espace de stockage.
- rappel
  
  fonction facultatif
  
  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

tout facultatif

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

tout 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 sérialisation JSON de chaque valeur, plus la longueur de chaque clé. Cette valeur est 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 lors de l'utilisation d'un rappel ou d'une promesse refusée si vous utilisez async/await.

managed

Les éléments de la zone de stockage managed sont définis par une stratégie d'entreprise configurée par l'administrateur de domaine et sont en lecture seule pour l'extension. Toute tentative de modification de cet espace de noms entraîne une erreur. Pour en savoir plus sur la configuration d'une règle, consultez la section Fichier manifeste pour les zones de stockage.

Type

StorageArea

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 le 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. Il s'agit d'une écriture toutes les deux secondes, ce qui est inférieur à la limite supérieure d'écritures par minute à court terme.

Les mises à jour qui entraîneraient le dépassement de cette limite échouent immédiatement et définissent runtime.lastError lors de l'utilisation d'un rappel ou lorsqu'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. Cela correspond à deux par seconde, ce qui offre un débit supérieur aux é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 lors de l'utilisation d'un rappel ou lorsqu'une promesse est rejetée.
QUOTA_BYTES

102 400

Quantité totale maximale (en octets) de données pouvant être stockées dans l'espace de stockage de synchronisation, mesurée par la sérialisation 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 lors de l'utilisation d'un rappel ou lorsqu'une promesse est rejetée.
QUOTA_BYTES_PER_ITEM

8 192

Taille maximale (en octets) de chaque élément individuel dans l'espace de stockage de synchronisation, mesurée par la sérialisation JSON de sa valeur 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 lors de l'utilisation d'un rappel ou lorsqu'une promesse est rejeté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