chrome.storage

Descrizione

Utilizza l'API chrome.storage per archiviare, recuperare e tenere traccia delle modifiche apportate ai dati utente.

Autorizzazioni

storage

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

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

Concetti e utilizzo

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

  • Tutti i contesti delle estensioni, inclusi il service worker di estensione e gli script dei contenuti, hanno accesso all'API Storage.
  • I valori serializzabili JSON vengono archiviati come proprietà degli oggetti.
  • L'API Storage è asincrona con le operazioni collettive di lettura e scrittura.
  • I dati rimangono memorizzati anche se l'utente svuota la cache e cancella la cronologia di navigazione.
  • Le impostazioni memorizzate vengono mantenute anche quando si utilizza la modalità di navigazione in incognito.
  • 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 di Storage (accessibile da window.localStorage) in alcuni contesti (popup e altre pagine HTML), questa soluzione non è consigliata per i seguenti motivi:

  • I service worker di 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 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 del documento fuori schermo e un file di script. Il file di script deve contenere una routine di conversione e un gestore onMessage.
  2. Nel service worker dell'estensione, cerca i tuoi dati in chrome.storage.
  3. Se i dati non vengono trovati, chiama createDocument().
  4. Una volta risolta la promessa restituita, chiama sendMessage() per avviare la routine di conversione.
  5. Chiama la routine di conversione all'interno del gestore onMessage del documento fuori schermo.

Ci sono anche alcune sfumature nel funzionamento delle API di archiviazione web nelle estensioni. Scopri di più nel Articolo Archiviazione e cookie.

Aree di deposito

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

storage.local
I dati vengono archiviati localmente e cancellati quando viene rimossa l'estensione. 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 grandi quantità di dati.
storage.managed
L'archiviazione gestita è l'archiviazione di sola lettura per le estensioni con installazione di criteri e gestita dagli amministratori di sistema tramite uno schema definito dallo sviluppatore e criteri aziendali. I criteri sono analoghi alle opzioni, ma sono configurati da un amministratore di sistema anziché dall'utente, consentendo di preconfigurare l'estensione per tutti gli utenti di un'organizzazione. Per informazioni sui criteri, consulta la documentazione per gli amministratori. Per scoprire di più sull'area di archiviazione managed, consulta Manifest per le aree di archiviazione.
storage.session
Conserva i dati in memoria per l'intera 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 è 10 MB (1 MB in Chrome 111 e versioni precedenti). L'interfaccia di storage.session è una delle tante consigliate ai service worker.
storage.sync
Se la sincronizzazione è attivata, i dati vengono sincronizzati con qualsiasi 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 è di nuovo online. Il limite di quota è di circa 100 kB, 8 kB per elemento. Ti consigliamo di utilizzare storage.sync per mantenere le impostazioni utente nei browser sincronizzati. Se stai lavorando con dati utente sensibili, usa storage.session.

Limiti di spazio di archiviazione e limitazione

L'API Storage presenta le seguenti limitazioni di utilizzo:

  • L'archiviazione dei dati spesso comporta costi per le prestazioni e l'API include quote di archiviazione. Consigliamo di fare attenzione ai dati che archivi, in modo da non perdere la possibilità di archiviarli.
  • Il completamento dello spazio di archiviazione può richiedere del tempo. Assicurati di strutturare il codice in base a questo periodo di tempo.

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

Casi d'uso

Le sezioni seguenti illustrano casi d'uso comuni per l'API Storage.

Risposta sincrona agli aggiornamenti dello spazio di archiviazione

Per monitorare le modifiche apportate allo spazio di archiviazione, aggiungi un listener al relativo evento onChanged. Quando qualcosa cambia nello spazio di archiviazione, viene attivato quell'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 portare questa idea anche oltre. In questo esempio, abbiamo una pagina 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 usa 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 da spazio di archiviazione

Poiché i service worker non vengono eseguiti sempre, a volte le estensioni Manifest V3 devono Caricano in modo asincrono i dati dallo spazio di archiviazione prima che eseguano i relativi gestori di eventi. Per fare ciò, lo snippet seguente utilizza un gestore di eventi action.onClicked asincrono che attende l'evento storageCache globale da compilare 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);
});

Esempi

I seguenti esempi dimostrano gli elementi local, sync e session aree di archiviazione:

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

Sincronizza

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 degli esempi seguenti:

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.

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
Specifica i contesti che hanno origine dall'esterno dell'estensione.

StorageArea

Proprietà

  • onChanged

    Evento<functionvoidvoid>

    Chrome 73 e versioni successive .

    Attivato quando uno o più elementi cambiano.

    La funzione onChanged.addListener ha questo aspetto: 

    (callback: function) => {...}

    • callback

      funzione

      Il parametro callback ha il seguente aspetto: 

      (changes: object) => void

      • modifiche

        oggetto

  • cancella

    null

    Promesso .

    Rimuove tutti gli elementi dallo spazio di archiviazione.

    La funzione clear ha questo aspetto: 

    (callback?: function) => {...}

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promesso<void>

      Chrome 88 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • get

    null

    Promesso .

    Recupera uno o più elementi dallo spazio di archiviazione.

    La funzione get ha questo aspetto: 

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

    • chiavi

      string | string[] | oggetto facoltativo

      Una singola chiave da ottenere, un elenco di chiavi da ottenere o un dizionario che specifica valori predefiniti (consulta la descrizione dell'oggetto). Un elenco o un oggetto vuoto restituirà un oggetto risultato vuoto. Supera null per avere l'intero contenuto dello spazio di archiviazione.

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      (items: object) => void

      • elementi

        oggetto

        Oggetto con elementi nelle mappature chiave-valore.

    • returns

      Promise&lt;object&gt;

      Chrome 88 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • getBytesInUse

    null

    Promesso .

    Recupera la quantità di spazio (in byte) utilizzata da uno o più elementi.

    La funzione getBytesInUse ha questo aspetto: 

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

    • chiavi

      string | string[] facoltativo

      Una singola chiave o un elenco di chiavi per cui ottenere l'utilizzo totale. Un elenco vuoto restituirà 0. Passa 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

      Promise&lt;number&gt;

      Chrome 88 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • getKey

    null

    Promesso In attesa

    Recupera tutte le chiavi dallo spazio di archiviazione.

    La funzione getKeys ha questo aspetto: 

    (callback?: function) => {...}

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      (keys: string[]) => void

      • chiavi

        stringa[]

        Array con chiavi lette dallo spazio di archiviazione.

    • returns

      Promise&lt;string[]&gt;

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • rimuovi

    null

    Promesso .

    Rimuove uno o più elementi dallo spazio di archiviazione.

    La funzione remove ha questo aspetto: 

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

    • chiavi

      string | stringa[]

      Una singola chiave o un elenco di chiavi da rimuovere dagli elementi.

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promesso<void>

      Chrome 88 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • imposta

    null

    Promesso .

    Consente di impostare più elementi.

    La funzione set ha questo aspetto: 

    (items: object, callback?: function) => {...}

    • elementi

      oggetto

      Un oggetto che fornisce a ogni coppia chiave/valore l'aggiornamento dello spazio di archiviazione. Eventuali altre coppie chiave/valore nello spazio di archiviazione non saranno interessate.

      I valori primitivi come i numeri verranno serializzati come previsto. I valori con typeof "object" e "function" in genere vengono serializzati in {}, ad eccezione di Array (seriale come previsto), Date e Regex (seriale utilizzando la relativa rappresentazione String).

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promesso<void>

      Chrome 88 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • setAccessLevel

    null

    Promesso Chrome 102 e versioni successive

    Imposta il livello di accesso desiderato per l'area di archiviazione. Per impostazione predefinita saranno selezionati solo i contesti attendibili.

    La funzione setAccessLevel ha questo 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

      Promesso<void>

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

StorageChange

Proprietà

  • newValue

    qualsiasi opzione facoltativa

    Il nuovo valore dell'elemento, se presente.

  • oldValue

    qualsiasi opzione facoltativa

    Il valore precedente dell'elemento, se ne esiste uno precedente.

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 possono essere archiviati nello spazio di archiviazione locale, misurata mediante la 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 causano il superamento di questo limite non vanno a buon fine e vengono impostati su runtime.lastError quando si utilizza un callback, oppure di una Promessa rifiutata se si utilizza Async/Await.

managed

Gli elementi nell'area di archiviazione 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 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 vengono archiviati in memoria e non saranno resi persistenti 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 l'utilizzo della memoria allocata dinamicamente di ogni valore e chiave. Gli aggiornamenti che causano il superamento di questo limite non riescono immediatamente e vengono impostati su runtime.lastError quando si utilizza un callback o quando una promessa viene rifiutata.

sync

Gli elementi nell'area di archiviazione di sync vengono sincronizzati tramite 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 causano il superamento di questo limite non riusciranno immediatamente e verranno impostati su runtime.lastError quando si utilizza un callback o quando una promessa viene rifiutata.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Obsoleta

    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. Si tratta di 1 ogni 2 secondi, un limite inferiore rispetto al limite di scritture al minuto più alto a breve termine.

    Gli aggiornamenti che causano il superamento di questo limite non riescono immediatamente e vengono impostati su 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 è possibile eseguire ogni minuto. Si tratta di 2 al secondo, per una velocità effettiva superiore rispetto alle scritture all'ora in un periodo di tempo più breve.

    Gli aggiornamenti che causano il superamento di questo limite non riescono immediatamente e vengono impostati su runtime.lastError quando si utilizza un callback o quando una promessa viene rifiutata.

  • QUOTA_BYTES

    102400

    La quantità massima totale (in byte) di dati che possono essere archiviati nello spazio di archiviazione sincronizzato, misurata mediante la stringificazione JSON di ogni valore più la lunghezza di ogni chiave. Gli aggiornamenti che causano il superamento di questo limite non riescono immediatamente e vengono impostati su 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 sincronizzato, misurata dalla stringa di dati JSON del suo valore più la lunghezza della chiave. Gli aggiornamenti contenenti elementi di dimensioni superiori a questo limite non riusciranno immediatamente e verranno impostati su runtime.lastError quando si utilizza un callback o quando una promessa viene rifiutata.

Eventi

onChanged

chrome.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