chrome.storage

Descrizione

Utilizza l'API chrome.storage per archiviare, recuperare e monitorare le modifiche ai dati utente.

Autorizzazioni

storage

Panoramica

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.

Anche se le estensioni possono utilizzare l'interfaccia [Storage][mdn-storage] (accessibile da window.localStorage) in alcuni contesti (popup e altre pagine HTML), non è consigliabile per i seguenti motivi:

  • Il service worker dell'estensione non può accedere a Storage.
  • Gli script di contenuti condividono lo spazio di archiviazione con la pagina host.
  • I dati salvati utilizzando l'interfaccia di 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:

  1. Crea un documento fuori schermo con una routine di conversione e un gestore [onMessage][on-message].
  2. Aggiungi una routine di conversione a un documento fuori schermo.
  3. Nel service worker dell'estensione, controlla chrome.storage per i tuoi dati.
  4. Se i dati non vengono trovati, [crea][crea][crea] un documento fuori schermo e chiama il numero [sendMessage()][send-message] per avviare la routine di conversione.
  5. 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][storage-and-cookies].

Aree di archiviazione

L'API Storage è suddivisa nei seguenti quattro bucket ("aree di archiviazione"):

storage.local
I dati vengono archiviati localmente e vengono cancellati quando l'estensione viene rimossa. Il limite di quota è di circa 10 MB, ma può essere aumentato richiedendo l'autorizzazione "unlimitedStorage". Valuta la possibilità di utilizzarlo per archiviare grandi quantità di dati.
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. Valuta la possibilità di utilizzarlo per preservare le impostazioni utente nei vari browser sincronizzati.
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 quota è di circa 10 MB. Valuta la possibilità di utilizzarlo per archiviare variabili globali nelle esecuzioni dei service worker.
storage.managed
Gli amministratori possono utilizzare uno schema e criteri aziendali per configurare le impostazioni di un'estensione di supporto in un ambiente gestito. Questa area di archiviazione è di sola lettura.

Manifest

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

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

Utilizzo

I seguenti esempi mostrano le aree di archiviazione local, sync e 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);
});

Per scoprire di più sull'area di archiviazione di managed, vedi Il file manifest per le aree di archiviazione.

Limiti di archiviazione e limitazione

Non pensare ad aggiungere all'API Storage come a un enorme impiego di oggetti. Immagina di aggiungere qualcosa in più come uno spazio in più. Il tubo potrebbe contenere già del materiale e potrebbe perfino essere riempito. Ipotizziamo sempre un ritardo tra il momento in cui aggiungi lo spazio di archiviazione e il momento in cui viene effettivamente registrato.

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, puoi aggiungere 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 in esecuzione, le estensioni Manifest V3 a volte 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 di estensioni

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

Tipi

AccessLevel

Chrome 102 e versioni successive

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 successive

    Attivato 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

    Promessa

    Rimuove 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 successive

      Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

  • get

    void

    Promessa

    Recupera uno o più elementi dallo spazio di archiviazione.

    La funzione get ha il seguente aspetto: 

    (keys?: string|string[]|object,callback?: function)=> {...}

    • chiavi

      string|string[]|object optional

      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 successive

      Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

  • getBytesInUse

    void

    Promessa

    Recupera 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[] optional

      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 successive

      Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

  • rimozione

    void

    Promessa

    Rimuove 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 successive

      Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

  • imposta

    void

    Promessa

    Imposta 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 di Array (viene serializzato come previsto), Date e Regex (viene serializzato utilizzando la relativa rappresentazione String).

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      ()=>void

    • returns

      Promise<void>

      Chrome 88 e versioni successive

      Le promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.

  • setAccessLevel

    void

    Promessa Chrome 102 e versioni successive

    Consente 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

        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 solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i 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&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 imposta runtime.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

StorageArea

session

Chrome 102 e versioni successive MV3 o versioni successive

Gli elementi nell'area di archiviazione di session sono memorizzati in memoria e non saranno resi permanenti su disco.

Tipo

StorageArea&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&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

    Deprecato

    L'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 o clear 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 o clear 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