chrome.storage

Descrizione

Autorizzazioni

Per utilizzare l'API Storage, dichiara l'autorizzazione "storage" nel manifest dell'estensione. Ad esempio:

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

Esempi

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

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);
});

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);
});

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

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

• Estensione della ricerca globale.
• Estensione per l'allarme acqua.

Concetti e utilizzo

L'API Storage fornisce un modo specifico per le estensioni per rendere persistenti i dati e lo stato degli utenti. È simile alle API Storage 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 di 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 la cronologia di navigazione, i dati vengono conservati.
• Le impostazioni memorizzate vengono mantenute anche quando utilizzi la modalità di navigazione in incognito suddivisa.
• 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 per un documento fuori schermo. Il file di script deve contenere una routine di conversione e un gestore onMessage.
2. Nel service worker dell'estensione, controlla chrome.storage per i tuoi dati.
3. Se i tuoi dati non vengono trovati, chiama il numero createDocument().
4. Una volta risolta la promessa 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 Archiviazione e cookie.

Limiti di spazio 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 archiviazione. Pianifica i dati che intendi archiviare per mantenere lo spazio di archiviazione.
• Il completamento dell'archiviazione può richiedere 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 stoccaggio

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 archiviazione è 10 MB (5 MB in Chrome 113 e versioni precedenti), ma può essere aumentato richiedendo l'autorizzazione "unlimitedStorage". Consigliamo di utilizzare storage.local per archiviare quantità maggiori di dati. Per impostazione predefinita, è esposto agli script dei contenuti, ma questo comportamento può essere modificato chiamando chrome.storage.local.setAccessLevel().

Gestito

L'archiviazione gestita è di sola lettura per le estensioni installate tramite criteri. È gestito dagli amministratori di sistema, utilizzando uno schema definito dallo sviluppatore e criteri aziendali. I criteri sono simili alle opzioni, ma vengono configurati 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 chrome.storage.managed.setAccessLevel(). Per informazioni sulle norme, consulta la documentazione per gli amministratori. Per saperne di più sull'area di archiviazione managed, consulta Manifest per le aree di archiviazione.

Sessione

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

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

Sincronizza

Se l'utente attiva la sincronizzazione, i dati vengono sincronizzati con tutti i browser Chrome a cui l'utente ha eseguito l'accesso. Se disattivato, si comporta come storage.local. Chrome archivia i dati localmente quando il browser è offline e riprende la sincronizzazione quando torna online. La limitazione 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 lavori con dati utente sensibili, utilizza invece storage.session. Per impostazione predefinita, storage.sync è esposto agli script dei contenuti, ma questo comportamento può essere modificato chiamando chrome.storage.sync.setAccessLevel().

Metodi ed eventi

Tutte le aree di archiviazione implementano l'interfaccia StorageArea.

get()

Il metodo get() ti 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 per l'API Storage.

Rispondere agli aggiornamenti dello spazio di archiviazione

Per monitorare le modifiche apportate allo spazio di archiviazione, aggiungi un listener all'evento onChanged. Quando cambia qualcosa nello spazio di archiviazione, viene attivato l'evento. Il codice di esempio rileva le seguenti 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 spingere questo concetto ancora più in là. In questo esempio, abbiamo una pagina delle 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 vengono eseguiti sempre, 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 popolamento della variabile globale storageCache prima di eseguire la sua 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);
});

DevTools

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

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