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 de stockage, déclarez l'autorisation "storage"
dans le fichier manifeste de l'extension. Exemple :
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Concepts et utilisation
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.
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 vous déconseillons de le faire pour les raisons suivantes:
- Les service workers d'extension ne peuvent pas utiliser l'API Web Storage.
- Les scripts de contenu partagent le 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 transférer des données des API de stockage Web vers les API de stockage d'extensions à partir d'un service worker:
- Préparez une page HTML du document et un fichier de script hors écran. Le fichier de script doit contenir une routine de conversion et un gestionnaire
onMessage
. - Dans le service worker de l'extension, recherchez vos données sur
chrome.storage
. - Si vos données sont introuvables, appelez
createDocument()
. - Une fois la promesse renvoyée résolue, appelez
sendMessage()
pour démarrer la routine de conversion. - 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.
Zones de stockage
L'API Storage comporte les zones de stockage suivantes:
storage.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 vous pouvez l'augmenter en demandant l'autorisation
"unlimitedStorage"
. Nous vous recommandons d'utiliserstorage.local
pour stocker de plus grandes quantités de données. storage.managed
- L'espace de stockage géré est un espace de stockage en lecture seule pour les extensions de règles installées. 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 sont configurées par un administrateur système plutôt que par l'utilisateur, ce qui permet de préconfigurer l'extension pour tous les utilisateurs d'une organisation. Pour en savoir plus sur les règles, consultez la documentation pour les administrateurs. Pour en savoir plus sur l'espace de stockage
managed
, consultez Fichier manifeste des zones de stockage. 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 stockage est de 10 Mo (1 Mo sous Chrome 111 et versions antérieures). L'interfacestorage.session
est l'une des nombreuses recommandations pour les service workers. 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. Nous vous recommandons d'utiliserstorage.sync
pour conserver les paramètres utilisateur sur les navigateurs synchronisés. Si vous travaillez avec des données utilisateur sensibles, utilisez plutôtstorage.session
.
Limites de stockage et de limitation
L'API Storage présente les limites d'utilisation suivantes:
- Le stockage des données entraîne souvent des coûts de performances, et l'API inclut des quotas de stockage. Nous vous recommandons de faire attention aux données que vous stockez afin de ne pas perdre la possibilité de les stocker.
- Le stockage peut prendre un certain temps. Veillez à structurer votre code de manière à tenir compte de ce temps.
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, ajoutez 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 en permanence, 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 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
Les exemples suivants illustrent les zones de stockage local
, sync
et session
:
Interprétabilité locale
chrome.storage.local.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.local.get(["key"]).then((result) => {
console.log("Value is " + result.key);
});
Synchroniser
chrome.storage.sync.set({ key: value }).then(() => {
console.log("Value is set");
});
chrome.storage.sync.get(["key"]).then((result) => {
console.log("Value is " + result.key);
});
Session
chrome.storage.session.set({ key: value }).then(() => {
console.log("Value was set");
});
chrome.storage.session.get(["key"]).then((result) => {
console.log("Value is " + result.key);
});
Pour voir d'autres démonstrations de l'API Storage, explorez l'un des exemples suivants:
Types
AccessLevel
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érieuresDé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
PromesseSupprime 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érieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
-
-
get
void
PromesseRé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
chaîne | chaîne[] | objet facultatif
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érieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
-
-
getBytesInUse
void
PromesseRé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 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érieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
-
-
remove
void
PromesseSupprime 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érieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
-
-
set
void
PromesseDé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 deArray
(sérialise comme prévu),Date
etRegex
(sérialiser à l'aide de leur représentationString
). -
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
-
retours
Promise<void>
Chrome 88 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
-
-
setAccessLevel
void
Promesse Chrome 102 et versions ultérieuresDé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
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 sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
-
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 et 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éfinissentruntime.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
session
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 et 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 et 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èteL'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
ouclear
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
ouclear
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
-