Descrizione
Utilizza l'API chrome.storage
per archiviare, recuperare e monitorare le modifiche ai dati utente.
Autorizzazioni
storage
Per utilizzare l'API Storage, dichiara l'autorizzazione "storage"
nel manifest dell'estensione. Ad esempio:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Concetti e utilizzo
L'API Storage fornisce un modo specifico dell'estensione per rendere persistenti i dati e lo stato dell'utente. È simile alle API di archiviazione della piattaforma web (IndexedDB e Storage), ma è stata progettata per soddisfare le esigenze di archiviazione delle estensioni. Ecco alcune funzionalità principali:
- Tutti i contesti delle estensioni, inclusi il service worker dell'estensione e gli script dei contenuti, hanno accesso all'API Storage.
- I valori JSON serializzabili vengono archiviati come proprietà dell'oggetto.
- L'API Storage è asincrona con le operazioni collettive di lettura e scrittura.
- Anche se l'utente svuota la cache e cancella la cronologia di navigazione, i dati rimangono memorizzati.
- Le impostazioni memorizzate vengono mantenute anche quando utilizzi la modalità di navigazione in incognito suddivisa.
- Include un'esclusiva area di archiviazione gestita di sola lettura per i criteri aziendali.
Le estensioni possono utilizzare API di archiviazione web?
Sebbene le estensioni possano utilizzare l'interfaccia Storage
(accessibile da window.localStorage
) in alcuni contesti (popup e altre pagine HTML), l'opzione non è consigliata per i seguenti motivi:
- I service worker dell'estensione non possono utilizzare l'API Web Storage.
- Gli script di contenuti condividono lo spazio di archiviazione con la pagina host.
- I dati salvati utilizzando l'API Web Storage andranno persi quando l'utente cancella la sua cronologia di navigazione.
Per spostare i dati dalle API di archiviazione web alle API di archiviazione delle estensioni da un service worker:
- Prepara una pagina HTML del documento fuori schermo e un file di script. Il file di script deve contenere una routine di conversione e un gestore
onMessage
. - Nel service worker dell'estensione, controlla i tuoi dati in
chrome.storage
. - Se non trovi i tuoi dati, chiama il numero
createDocument()
. - Una volta risolta la promessa restituita, chiama
sendMessage()
per avviare la routine di conversione. - All'interno del gestore
onMessage
del documento fuori schermo, chiama la routine di conversione.
Ci sono anche alcune sfumature nel funzionamento delle API di archiviazione web nelle estensioni. Scopri di più nell'articolo Spazio di archiviazione e cookie.
Aree di archiviazione
L'API Storage è suddivisa nelle seguenti aree di archiviazione:
storage.local
- I dati vengono archiviati in locale e cancellati quando l'estensione viene rimossa. Il limite di spazio di archiviazione è di 10 MB (5 MB in Chrome 113 e versioni precedenti), ma può essere aumentato richiedendo l'autorizzazione
"unlimitedStorage"
. Ti consigliamo di utilizzarestorage.local
per archiviare grandi quantità di dati. storage.managed
- L'archiviazione gestita è uno spazio di archiviazione di sola lettura per le estensioni installate mediante criteri e viene gestita dagli amministratori di sistema mediante uno schema definito dallo sviluppatore e criteri aziendali. I criteri sono analoghi alle opzioni, ma vengono configurati da un amministratore di sistema anziché dall'utente, consentendo di preconfigurare l'estensione per tutti gli utenti di un'organizzazione. Per informazioni sulle norme, consulta la documentazione per gli amministratori. Per scoprire di più sull'area di archiviazione di
managed
, consulta Il file manifest per le aree di archiviazione. storage.session
- I dati vengono conservati in memoria per tutta la durata di una sessione del browser. Per impostazione predefinita, non è esposto agli script di contenuti, ma questo comportamento può essere modificato impostando
chrome.storage.session.setAccessLevel()
. Il limite di spazio di archiviazione è di 10 MB (1 MB in Chrome 111 e versioni precedenti). L'interfacciastorage.session
è una delle tante consigliate per i service worker. storage.sync
- Se la sincronizzazione è attiva, i dati vengono sincronizzati con qualsiasi browser Chrome a cui l'utente ha eseguito l'accesso. Se disattivato, si comporta come
storage.local
. Chrome memorizza i dati localmente quando il browser è offline e riprende la sincronizzazione quando è di nuovo online. Il limite di quota è di circa 100 kB, 8 kB per elemento. Ti consigliamo di utilizzarestorage.sync
per preservare le impostazioni utente nei vari browser sincronizzati. Se stai utilizzando dati utente sensibili, utilizza invecestorage.session
.
Limiti di archiviazione e limitazione
L'API Storage prevede le seguenti limitazioni di utilizzo:
- L'archiviazione dei dati spesso comporta costi di prestazioni e l'API include le quote di archiviazione. Consigliamo di fare attenzione ai dati archiviati per non perdere la possibilità di archiviarli.
- Il completamento dell'archiviazione può richiedere del tempo. Assicurati di strutturare il codice per tenere conto di questo intervallo di tempo.
Per maggiori dettagli sulle limitazioni dello spazio di archiviazione e su cosa succede quando vengono superate, consulta le informazioni sulla quota per sync
, local
e session
.
Casi d'uso
Le seguenti sezioni illustrano casi d'uso comuni per l'API Storage.
Risposta sincrona agli aggiornamenti dello spazio di archiviazione
Per tenere traccia delle modifiche apportate allo spazio di archiviazione, aggiungi un listener al relativo evento onChanged
. Quando qualcosa cambia nello spazio di archiviazione, si attiva questo evento. Il codice di esempio rimane in ascolto di queste modifiche:
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}".`
);
}
});
Possiamo andare oltre. In questo esempio abbiamo una pagina Opzioni che consente all'utente di attivare/disattivare una "modalità di debug" (l'implementazione non è mostrata qui). La pagina delle opzioni salva immediatamente le nuove impostazioni in storage.sync
e il service worker utilizza storage.onChanged
per applicare l'impostazione il prima possibile.
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);
}
});
Precaricamento asincrono dallo spazio di archiviazione
Poiché i service worker non sono sempre eseguiti, a volte le estensioni Manifest V3 devono caricare in modo asincrono i dati dallo spazio di archiviazione prima di eseguire i gestori di eventi. A questo scopo, lo snippet seguente utilizza un gestore di eventi action.onClicked
asincrono che attende il completamento del campo globale storageCache
prima di eseguire la logica.
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);
});
Esempi
I seguenti esempi mostrano le aree di archiviazione local
, sync
e session
:
Locali
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);
});
Sincronizzazione
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);
});
Sessione
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);
});
Per vedere altre demo dell'API Storage, esplora uno dei seguenti esempi:
Tipi
AccessLevel
Il livello di accesso dell'area di archiviazione.
Enum
"TRUSTED_CONTEXTS"
Specifica i contesti che hanno origine dall'estensione stessa.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Specifica i contesti che hanno origine al di fuori dell'estensione.
StorageArea
Proprietà
-
onChanged
Evento<functionvoidvoid>
Chrome 73 e versioni successiveAttivato quando vengono modificati uno o più elementi.
La funzione
onChanged.addListener
ha il seguente aspetto:(callback: function) => {...}
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(changes: object) => void
-
modifiche
oggetto
-
-
-
cancella
void
PromessaRimuove tutti gli elementi dallo spazio di archiviazione.
La funzione
clear
ha il seguente aspetto:(callback?: function) => {...}
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
-
returns
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
get
void
PromessaRecupera uno o più elementi dallo spazio di archiviazione.
La funzione
get
ha il seguente aspetto:(keys?: string | string[] | object, callback?: function) => {...}
-
chiavi
stringa | string[] | oggetto facoltativo
Una singola chiave da ottenere, un elenco di chiavi da ottenere o un dizionario che specifica valori predefiniti (vedi la descrizione dell'oggetto). Un elenco o un oggetto vuoto restituisce un oggetto risultato vuoto. Passa in
null
per ottenere l'intero contenuto dello spazio di archiviazione. -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(items: object) => void
-
items
oggetto
Oggetto con elementi nelle mappature delle coppie chiave-valore.
-
-
returns
Promise<object>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
getBytesInUse
void
PromessaRecupera la quantità di spazio (in byte) utilizzata da uno o più elementi.
La funzione
getBytesInUse
ha il seguente aspetto:(keys?: string | string[], callback?: function) => {...}
-
chiavi
string | string[] facoltativo
Una singola chiave o un elenco di chiavi di cui visualizzare l'utilizzo totale. Un elenco vuoto restituirà 0. Supera
null
per ottenere l'utilizzo totale di tutto lo spazio di archiviazione. -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(bytesInUse: number) => void
-
bytesInUse
numero
Quantità di spazio utilizzata nello spazio di archiviazione, in byte.
-
-
returns
Promessa<numero>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
remove
void
PromessaRimuove uno o più elementi dallo spazio di archiviazione.
La funzione
remove
ha il seguente aspetto:(keys: string | string[], callback?: function) => {...}
-
chiavi
stringa | stringa[]
Una singola chiave o un elenco di chiavi da rimuovere per gli elementi.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
-
returns
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
imposta
void
PromessaImposta più elementi.
La funzione
set
ha il seguente aspetto:(items: object, callback?: function) => {...}
-
items
oggetto
Un oggetto che fornisce ogni coppia chiave/valore con cui aggiornare lo spazio di archiviazione. Le altre coppie chiave/valore nello spazio di archiviazione non saranno interessate.
I valori primitivi come i numeri vengono seriali come previsto. I valori con
typeof
"object"
e"function"
in genere vengono serializzati su{}
, ad eccezione diArray
(viene serializzato come previsto),Date
eRegex
(viene serializzato utilizzando la relativa rappresentazioneString
). -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
-
returns
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
setAccessLevel
void
Promessa Chrome 102 e versioni successiveConsente di impostare il livello di accesso desiderato per l'area di archiviazione. Per impostazione predefinita saranno utilizzati solo i contesti attendibili.
La funzione
setAccessLevel
ha il seguente aspetto:(accessOptions: object, callback?: function) => {...}
-
accessOptions
oggetto
-
accessLevel
Il livello di accesso dell'area di archiviazione.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
-
returns
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
StorageChange
Proprietà
-
newValue
qualsiasi facoltativo
Il nuovo valore dell'elemento, se presente.
-
oldValue
qualsiasi facoltativo
Il vecchio valore dell'articolo, se presente.
Proprietà
local
Gli elementi nell'area di archiviazione di local
sono locali per ogni macchina.
Tipo
StorageArea e oggetto
Proprietà
-
QUOTA_BYTES
10485760
La quantità massima (in byte) di dati che può essere archiviata nello spazio di archiviazione locale, misurata dalla stringa JSON di ogni valore più la lunghezza di ogni chiave. Questo valore verrà ignorato se l'estensione ha l'autorizzazione
unlimitedStorage
. Gli aggiornamenti che comporterebbero il superamento di questo limite non andranno a buon fine immediatamente e impostaruntime.lastError
se utilizzi un callback o Promise rifiutato se utilizzi asincroni o in attesa.
managed
Gli elementi nell'area di archiviazione di managed
sono impostati da un criterio aziendale configurato dall'amministratore di dominio e sono di sola lettura per l'estensione; il tentativo di modificare questo spazio dei nomi genera un errore. Per informazioni sulla configurazione di un criterio, consulta Il file manifest per le aree di archiviazione.
Tipo
session
Gli elementi nell'area di archiviazione di session
sono memorizzati in memoria e non saranno resi permanenti su disco.
Tipo
StorageArea e oggetto
Proprietà
-
QUOTA_BYTES
10485760
La quantità massima (in byte) di dati che possono essere archiviati in memoria, misurata mediante la stima dell'utilizzo della memoria allocata dinamicamente di ogni valore e chiave. Gli aggiornamenti che comporterebbero il superamento di questo limite non riusciranno immediatamente e imposta
runtime.lastError
quando utilizzi un callback o quando una promessa viene rifiutata.
sync
Gli elementi nell'area di archiviazione di sync
vengono sincronizzati mediante Sincronizzazione Chrome.
Tipo
StorageArea e oggetto
Proprietà
-
MAX_ITEMS
512
Il numero massimo di elementi che possono essere memorizzati nello spazio di archiviazione sincronizzato. Gli aggiornamenti che comporterebbero il superamento di questo limite non andranno a buon fine immediatamente e imposteranno
runtime.lastError
quando utilizzi un callback o quando una promessa viene rifiutata. -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
DeprecatoL'API storage.sync non ha più una quota di operazioni di scrittura sostenuta.
-
MAX_WRITE_OPERATIONS_PER_HOUR
1800
Il numero massimo di operazioni
set
,remove
oclear
che è possibile eseguire ogni ora. Il valore è 1 ogni 2 secondi, un tetto inferiore rispetto al limite di scritture al minuto più alto a breve termine.Gli aggiornamenti che comporterebbero il superamento di questo limite non riusciranno immediatamente e imposta
runtime.lastError
quando utilizzi un callback o quando una promessa viene rifiutata. -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
Il numero massimo di operazioni
set
,remove
oclear
che è possibile eseguire ogni minuto. Questo valore corrisponde a 2 al secondo, fornendo una velocità effettiva superiore rispetto alle scritture all'ora in un periodo di tempo più breve.Gli aggiornamenti che comporterebbero il superamento di questo limite non riusciranno immediatamente e imposta
runtime.lastError
quando utilizzi un callback o quando una promessa viene rifiutata. -
QUOTA_BYTES
102.400
La quantità totale massima (in byte) di dati che può essere archiviata nell'archiviazione di sincronizzazione, misurata dalla stringa JSON di ogni valore più la lunghezza di ogni chiave. Gli aggiornamenti che comporterebbero il superamento di questo limite non riusciranno immediatamente e imposta
runtime.lastError
quando utilizzi un callback o quando una promessa viene rifiutata. -
QUOTA_BYTES_PER_ITEM
8192
La dimensione massima (in byte) di ogni singolo elemento nello spazio di archiviazione di sincronizzazione, misurata dalla stringa JSON del relativo valore più la lunghezza della chiave. Gli aggiornamenti contenenti elementi di dimensioni superiori a questo limite non andranno a buon fine immediatamente e imposteranno
runtime.lastError
quando si utilizza un callback o quando una promessa viene rifiutata.
Eventi
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
Attivato quando vengono modificati uno o più elementi.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(changes: object, areaName: string) => void
-
modifiche
oggetto
-
areaName
stringa
-