browser.storage

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"
  ],
  ...
}

Esempi

I seguenti esempi mostrano le aree di archiviazione local, sync e session:

Esempio (locale)

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

Esempio (sincronizzazione)

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

Esempio (sessione)

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

Per visualizzare altre demo dell'API Storage, esplora uno dei seguenti esempi:

Concetti e utilizzo

L'API Storage fornisce un modo specifico per l'estensione per rendere persistenti i dati utente e lo stato. È simile alle API di archiviazione della piattaforma web (IndexedDB e Storage), ma è stata progettata per soddisfare le esigenze di archiviazione delle estensioni. Di seguito sono riportate alcune funzionalità chiave:

  • Tutti i contesti delle estensioni, inclusi il service worker dell'estensione e gli script dei contenuti, hanno accesso all'API Storage.
  • I valori serializzabili JSON vengono archiviati come proprietà dell'oggetto.
  • L'API Storage è asincrona con operazioni di lettura e scrittura collettive.
  • Anche se l'utente svuota la cache e cancella la cronologia di navigazione, i dati rimangono.
  • Le impostazioni memorizzate vengono mantenute anche quando utilizzi la modalità di navigazione in incognito divisa.
  • Include un'area di archiviazione gestita esclusiva di sola lettura per i criteri aziendali.

Le estensioni possono utilizzare le API di archiviazione web?

Sebbene le estensioni possano utilizzare l'interfaccia Storage (accessibile da window.localStorage) in alcuni contesti (popup e altre pagine HTML), non lo consigliamo per i seguenti motivi:

  • I service worker delle estensioni 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 vengono persi quando l'utente cancella la cronologia di navigazione.

Per spostare i dati dalle API di archiviazione web alle API di archiviazione delle estensioni da un service worker:

  1. Prepara una pagina HTML e un file di script del documento fuori schermo. Il file di script deve contenere una routine di conversione e un gestore onMessage.
  2. Nel service worker dell'estensione, controlla browser.storage per i tuoi dati.
  3. Se i tuoi dati non vengono trovati, chiama il numero createDocument().
  4. Una volta risolta la Promise restituita, chiama sendMessage() per avviare la routine di conversione.
  5. All'interno del gestore onMessage del documento fuori schermo, chiama la routine di conversione.

Esistono anche alcune sfumature nel funzionamento delle API di archiviazione web nelle estensioni. Scopri di più nell'articolo Spazio di archiviazione e cookie.

Limiti di archiviazione e limitazione

L'API Storage presenta limitazioni di utilizzo:

  • L'archiviazione dei dati comporta costi di prestazioni e l'API include quote di spazio di archiviazione. Pianifica i dati che intendi archiviare, in modo da mantenere lo spazio di archiviazione.
  • Il completamento dell'archiviazione può richiedere del tempo. Struttura il codice in modo da tenere conto di questo tempo.

Per informazioni dettagliate sulle limitazioni dell'area di archiviazione e su cosa succede quando vengono superate, consulta le informazioni sulle quote per sync, local e session.

Aree di archiviazione

L'API Storage è suddivisa nelle seguenti aree di archiviazione:

Locale

I dati vengono archiviati localmente 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 utilizzare storage.local per archiviare quantità di dati maggiori. Per impostazione predefinita, è esposto agli script dei contenuti, ma questo comportamento può essere modificato chiamando browser.storage.local.setAccessLevel().

Gestito

Lo spazio di archiviazione gestito è di sola lettura per le estensioni installate tramite policy. È gestito dagli amministratori di sistema, utilizzando uno schema definito dallo sviluppatore e i criteri aziendali. Le policy sono simili alle opzioni, ma vengono configurate da un amministratore di sistema anziché dall'utente. In questo modo, l'estensione può essere preconfigurata per tutti gli utenti di un'organizzazione.

Per impostazione predefinita, storage.managed è esposto agli script dei contenuti, ma questo comportamento può essere modificato chiamando browser.storage.managed.setAccessLevel(). Per informazioni sulle policy, consulta la documentazione per gli amministratori. Per scoprire di più sull'area di archiviazione managed, consulta Manifesto per le aree di archiviazione.

Sessione

Lo spazio di archiviazione della sessione conserva i dati in memoria mentre un'estensione è caricata. Lo spazio di archiviazione viene cancellato se l'estensione viene disattivata, ricaricata, aggiornata e quando il browser viene riavviato. Per impostazione predefinita, non è esposto agli script dei contenuti, ma questo comportamento può essere modificato chiamando browser.storage.session.setAccessLevel(). Il limite di spazio di archiviazione è di 10 MB (1 MB in Chrome 111 e versioni precedenti).

L'interfaccia storage.session è una delle diverse che consigliamo per i service worker.

Sincronizza

Se l'utente attiva la sincronizzazione, i dati vengono sincronizzati con ogni browser Chrome a cui l'utente ha eseguito l'accesso. Se l'opzione è disattivata, si comporta come storage.local. Chrome archivia i dati localmente quando il browser è offline e riprende la sincronizzazione quando torna online. Il limite della quota è di circa 100 kB, 8 kB per elemento.

Ti consigliamo di utilizzare storage.sync per conservare le impostazioni utente nei browser sincronizzati. Se utilizzi dati utente sensibili, utilizza invece storage.session. Per impostazione predefinita, storage.sync è esposto agli script dei contenuti, ma questo comportamento può essere modificato chiamando browser.storage.sync.setAccessLevel().

Metodi ed eventi

Tutte le aree di archiviazione implementano l'interfaccia StorageArea.

get()

Il metodo get() consente di leggere una o più chiavi da un StorageArea.

getBytesInUse()

Il metodo getBytesInUse() consente di visualizzare la quota utilizzata da un StorageArea.

getKeys()

Il metodo getKeys() consente di recuperare tutte le chiavi archiviate in un StorageArea.

remove()

Il metodo remove() consente di rimuovere un elemento da un StorageArea.

set()

Il metodo set() consente di impostare un elemento in un StorageArea.

setAccessLevel()

Il metodo setAccessLevel() consente di controllare l'accesso a un StorageArea.

clear()

Il metodo clear() consente di cancellare tutti i dati da un StorageArea.

onChanged

L'evento onChanged ti consente di monitorare le modifiche a un StorageArea.

Casi d'uso

Le sezioni seguenti mostrano i casi d'uso comuni dell'API Storage.

Rispondi agli aggiornamenti dello spazio di archiviazione

Per monitorare le modifiche apportate allo spazio di archiviazione, aggiungi un listener al relativo evento onChanged. Quando cambia qualcosa nello spazio di archiviazione, viene attivato l'evento. Il codice campione rimane in ascolto di queste modifiche:

background.js:

browser.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 portare questa idea ancora più avanti. In questo esempio, abbiamo una pagina delle opzioni che consente all'utente di attivare/disattivare una "modalità di debug" (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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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 vengono eseguiti continuamente, a volte le estensioni Manifest V3 devono caricare i dati dallo spazio di archiviazione in modo asincrono prima di eseguire i gestori di eventi. Per farlo, lo snippet seguente utilizza un gestore di eventi action.onClicked asincrono che attende che la variabile globale storageCache venga compilata 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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

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

DevTools

Puoi visualizzare e modificare i dati archiviati utilizzando l'API in DevTools. Per saperne di più, consulta la pagina Visualizza e modifica lo spazio di archiviazione delle estensioni nella documentazione di DevTools.

Tipi

AccessLevel

Browser Chrome 102 e versioni successive.* A partire da Chrome 148

Il livello di accesso dell'area di archiviazione.

Enum

"TRUSTED_CONTEXTS"
Specifica i contesti provenienti dall'estensione stessa.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Specifica i contesti provenienti dall'esterno dell'estensione.

StorageChange

Proprietà

  • newValue

    any optional

    Il nuovo valore dell'elemento, se esiste.

  • oldValue

    any optional

    Il valore precedente dell'elemento, se esistente.

Proprietà

local

Gli elementi nell'area di archiviazione local sono locali per ogni macchina.

Tipo

StorageArea e oggetto

Proprietà

  • QUOTA_BYTES

    10485760

    La quantità massima (in byte) di dati che possono essere archiviati nello spazio di archiviazione locale, misurata dalla stringificazione JSON di ogni valore più la lunghezza di ogni chiave. Questo valore verrà ignorato se l'estensione dispone dell'autorizzazione unlimitedStorage. Gli aggiornamenti che causerebbero il superamento di questo limite non vanno a buon fine immediatamente e impostano runtime.lastError quando si utilizza un callback o una promessa rifiutata se si utilizza async/await.

managed

Gli elementi nell'area di archiviazione managed sono impostati da una policy aziendale configurata dall'amministratore di dominio e sono di sola lettura per l'estensione. Se provi a modificare questo spazio dei nomi, si verifica un errore. Per informazioni sulla configurazione di una policy, consulta Manifest per le aree di archiviazione.

Tipo

StorageArea

session

Chrome 102+ browser.* da Chrome 148 MV3+

Gli elementi nell'area di archiviazione session vengono archiviati in memoria e non verranno salvati su disco.

Tipo

StorageArea e oggetto

Proprietà

  • QUOTA_BYTES

    10485760

    La quantità massima (in byte) di dati che possono essere archiviati in memoria, misurata stimando la memoria utilizzata allocata dinamicamente di ogni valore e chiave. Gli aggiornamenti che causerebbero il superamento di questo limite non vanno a buon fine immediatamente e impostano runtime.lastError quando si utilizza un callback o quando una promessa viene rifiutata.

sync

Gli elementi nell'area di archiviazione sync vengono sincronizzati utilizzando Sincronizzazione Chrome.

Tipo

StorageArea e oggetto

Proprietà

  • MAX_ITEMS

    512

    Il numero massimo di elementi che possono essere archiviati nello spazio di archiviazione di sincronizzazione. Gli aggiornamenti che causerebbero il superamento di questo limite non andranno a buon fine immediatamente e imposteranno runtime.lastError quando si utilizza un callback o quando una Promise viene rifiutata.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Deprecato

    L'API storage.sync non ha più una quota di operazioni di scrittura sostenute.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    Il numero massimo di operazioni set, remove o clear che possono essere eseguite ogni ora. Si tratta di 1 ogni 2 secondi, un limite inferiore rispetto al limite di scritture al minuto a breve termine.

    Gli aggiornamenti che causerebbero il superamento di questo limite non vanno a buon fine immediatamente e impostano runtime.lastError quando si utilizza un callback o quando una promessa viene rifiutata.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Il numero massimo di operazioni set, remove o clear che possono essere eseguite ogni minuto. Si tratta di 2 operazioni al secondo, che offrono una velocità effettiva maggiore rispetto alle scritture all'ora in un periodo di tempo più breve.

    Gli aggiornamenti che causerebbero il superamento di questo limite non vanno a buon fine immediatamente e impostano runtime.lastError quando si utilizza un callback o quando una promessa viene rifiutata.

  • QUOTA_BYTES

    102400

    La quantità totale massima (in byte) di dati che possono essere archiviati nello spazio di archiviazione di sincronizzazione, misurata dalla stringificazione JSON di ogni valore più la lunghezza di ogni chiave. Gli aggiornamenti che causerebbero il superamento di questo limite non vanno a buon fine immediatamente e impostano runtime.lastError quando si utilizza 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 stringificazione JSON del suo 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 Promise viene rifiutata.

Eventi

onChanged

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

Attivato quando uno o più elementi cambiano.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • modifiche

      oggetto

    • areaName

      stringa