chrome.storage

Descrizione

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

Autorizzazioni

storage

Per utilizzare l'API di archiviazione, 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 per l'estensione per mantenere 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. Di seguito sono riportate alcune funzionalità chiave:

  • Tutti i contesti dell'estensione, inclusi il worker del servizio 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 le operazioni di lettura e scrittura collettive.
  • Anche se l'utente svuota la cache e la cronologia di navigazione, i dati rimangono invariati.
  • Le impostazioni memorizzate rimangono invariate anche quando si utilizza la navigazione in incognito divisa.
  • Include un'area di archiviazione gestita in sola lettura esclusiva 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 offscreen. Il file dello script deve contenere una routine di conversione e un gestore onMessage.
  2. Nel worker del servizio dell'estensione, controlla chrome.storage per i tuoi dati.
  3. Se i tuoi dati non vengono trovati, chiama createDocument().
  4. Una volta risolta la promessa restituita, chiama sendMessage() per avviare la routine di conversione.
  5. All'interno dell'handler onMessage del documento offscreen, chiama la routine di conversione.

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

Aree di stoccaggio

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

storage.local
I dati vengono archiviati localmente e cancellati quando l'estensione viene rimossa. Il limite di spazio di archiviazione è 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à maggiori di dati.
storage.managed
Lo spazio di archiviazione gestito è uno spazio di archiviazione di sola lettura per le estensioni installate in base ai criteri e gestito dagli amministratori di sistema utilizzando uno schema definito dallo sviluppatore e i criteri aziendali. I criteri sono simili alle opzioni, ma vengono configurati da un amministratore di sistema anziché dall'utente, il che consente 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 for storage areas (Manifesto per le aree di archiviazione).
storage.session
Mantiene i dati in memoria per la durata di una sessione del browser. Per impostazione predefinita, non è visibile agli script dei 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 storage.session è una delle diverse che consigliamo per i worker di servizio.
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 archivia i dati localmente quando il browser è offline e riprende la sincronizzazione quando è di nuovo 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 invece utilizzi dati utente sensibili, utilizza storage.session.

Limiti di spazio di archiviazione e throttling

L'API Storage presenta i seguenti limiti di utilizzo:

  • L'archiviazione dei dati comporta spesso costi in termini di prestazioni e l'API include quote di archiviazione. Ti consigliamo di prestare attenzione ai dati che memorizzi per non perdere la possibilità di archiviarli.
  • Il completamento dell'operazione di trasferimento dei dati nello spazio di archiviazione può richiedere del tempo. Assicurati di strutturare 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.

Casi d'uso

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

Risposta sincrona agli aggiornamenti dello spazio di archiviazione

Per monitorare le modifiche apportate allo spazio di archiviazione, aggiungi un listener all'evento onChanged. Quando si verificano modifiche nello spazio di archiviazione, viene attivato questo evento. Il codice di esempio è in ascolto per 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 spingere questa idea ancora oltre. In questo esempio, abbiamo una pagina di 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.sync per applicare l'impostazione il prima possibile.storage.onChanged

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 worker dei servizi non vengono eseguiti sempre, a volte le estensioni Manifest V3 devono caricare i dati in modo asincrono dallo spazio di archiviazione prima di eseguire i relativi gestori eventi. Per farlo, il seguente snippet utilizza un gestore di eventi action.onClicked asincrono che attende che la variabile globale storageCache venga compilata prima di eseguire la relativa 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:

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 visualizzare altre dimostrazioni dell'API Storage, consulta 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 provenienti dall'estensione stessa.

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

StorageArea

Proprietà

  • onChanged

    Event<functionvoidvoid>

    Chrome 73 e versioni successive

    Viene attivato quando uno o più elementi cambiano.

    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

    nullo

    Promessa

    Rimuove tutti gli elementi dallo spazio di archiviazione.

    La funzione clear ha il seguente aspetto: 

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

    • callback

      function facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promise<void>

      Chrome 88 e versioni successive

      Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

  • get

    nullo

    Promessa

    Recupera uno o più elementi dallo spazio di archiviazione.

    La funzione get ha il seguente aspetto: 

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

    • chiavi

      stringa | stringa[] | oggetto facoltativo

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

    • callback

      function facoltativa

      Il parametro callback ha il seguente aspetto: 

      (items: object) => void

      • elementi

        oggetto

        Oggetto con elementi nelle relative mappature di coppie chiave-valore.

    • returns

      Promise<object>

      Chrome 88 e versioni successive

      Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

  • getBytesInUse

    nullo

    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

      stringa | stringa[] facoltativo

      Una singola chiave o un elenco di chiavi per le quali ottenere l'utilizzo totale. Un elenco vuoto restituirà 0. Passa null per ottenere l'utilizzo totale di tutto lo spazio di archiviazione.

    • callback

      function facoltativa

      Il parametro callback ha il seguente aspetto: 

      (bytesInUse: number) => void

      • bytesInUse

        numero

        Quantità di spazio utilizzato nello spazio di archiviazione, in byte.

    • returns

      Promise<number>

      Chrome 88 e versioni successive

      Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

  • getKeys

    nullo

    Promessa Chrome 130 e versioni successive

    Recupera tutte le chiavi dallo spazio di archiviazione.

    La funzione getKeys ha il seguente aspetto: 

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

    • callback

      function facoltativa

      Il parametro callback ha il seguente aspetto: 

      (keys: string[]) => void

      • chiavi

        stringa[]

        Array con le chiavi lette dallo spazio di archiviazione.

    • returns

      Promise<string[]>

      Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

  • rimuovi

    nullo

    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 per gli elementi da rimuovere.

    • callback

      function facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promise<void>

      Chrome 88 e versioni successive

      Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

  • imposta

    nullo

    Promessa

    Imposta più elementi.

    La funzione set ha il seguente aspetto: 

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

    • elementi

      oggetto

      Un oggetto che fornisce ogni coppia chiave/valore per aggiornare lo spazio di archiviazione. Le 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" vengono generalmente serializzati in {}, ad eccezione di Array (viene serializzato come previsto), Date e Regex (viene serializzato utilizzando la relativa rappresentazione String).

    • callback

      function facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promise<void>

      Chrome 88 e versioni successive

      Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

  • setAccessLevel

    nullo

    Promessa Chrome 102 e versioni successive

    Imposta il livello di accesso desiderato per l'area di archiviazione. L'impostazione predefinita sarà solo 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

      function facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promise<void>

      Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

StorageChange

Proprietà

  • newValue

    qualsiasi facoltativo

    Il nuovo valore dell'elemento, se presente.

  • oldValue

    qualsiasi facoltativo

    Il vecchio valore 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 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 Manifest per le aree di archiviazione.

Tipo

StorageArea

session

Chrome 102 e versioni successive MV3 e versioni successive

Gli elementi nell'area di archiviazione session vengono memorizzati in memoria e non verranno mantenuti sul disco.

Tipo

StorageArea e oggetto

Proprietà

  • QUOTA_BYTES

    10485760

    La quantità massima (in byte) di dati che possono essere memorizzati nella memoria, misurata stimando l'utilizzo della memoria 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 viene utilizzato 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 sincronizzato. Gli aggiornamenti che causerebbero il superamento di questo limite non andranno a buon fine immediatamente e imposteranno runtime.lastError quando viene utilizzato un callback o quando una promessa viene rifiutata.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Obsoleto

    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 possono essere eseguite ogni ora. Si tratta di una scrittura ogni 2 secondi, un limite inferiore rispetto al limite di scrittura al minuto più elevato a breve termine.

    Gli aggiornamenti che causerebbero il superamento di questo limite non vanno a buon fine immediatamente e impostano runtime.lastError quando viene utilizzato 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. ovvero 2 al secondo, che offre una maggiore velocità effettiva 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 viene utilizzato 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 sincronizzato, 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 viene utilizzato 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 stringificazione JSON del relativo valore più la lunghezza della chiave. Gli aggiornamenti contenenti elementi più grandi di questo limite non andranno a buon fine immediatamente e imposteranno runtime.lastError quando viene utilizzato un callback o quando una promessa viene rifiutata.

Eventi

onChanged

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

Viene 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