Questa pagina è stata tradotta dall'API Cloud Translation.

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

Anche se le estensioni possono utilizzare l'interfaccia [Storage][mdn-storage] (accessibile da window.localStorage) in alcuni contesti (popup e altre pagine HTML), non è consigliata 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 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:

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

Aree di stoccaggio

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. La limitazione della quota è di circa 10 MB, ma può essere aumentata richiedendo l'autorizzazione "unlimitedStorage". Prendi in considerazione l'utilizzo di questo servizio per archiviare quantità maggiori di dati.

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 torna online. La limitazione della quota è di circa 100 kB, 8 kB per elemento. Valuta la possibilità di utilizzarlo per conservare le impostazioni utente nei browser sincronizzati.

Avviso: le aree di archiviazione locale e di sincronizzazione non devono archiviare dati utente riservati perché non sono criptate. Quando lavori con dati sensibili, valuta la possibilità di utilizzare l'area di archiviazione session per conservare i valori in memoria fino alla chiusura del browser.

storage.session: Conserva i dati in memoria per la durata di una sessione del browser. Per impostazione predefinita, non è esposto agli script dei contenuti, ma questo comportamento può essere modificato impostando chrome.storage.session.setAccessLevel(). La limitazione della 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

Gli esempi seguenti 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 saperne di più sull'area di archiviazione managed, consulta Manifest per le aree di archiviazione.

Limiti di spazio di archiviazione e limitazione

Non pensare di aggiungere elementi all'API Storage come se li stessi mettendo in un grande camion. Pensa all'aggiunta allo spazio di archiviazione come all'inserimento di qualcosa in un tubo. La pipe potrebbe già contenere materiale e potrebbe essere anche piena. Supponi sempre che ci sia un ritardo tra il momento in cui aggiungi un contenuto allo spazio di archiviazione e il momento in cui viene effettivamente registrato.

Per informazioni dettagliate sulle limitazioni dello spazio 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 i 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, puoi aggiungere un listener al relativo evento onChanged. Quando qualcosa cambia 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 sono sempre in esecuzione, 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);
});

Esempi di estensioni

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

Tipi

AccessLevel

Chrome 102+

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

qualsiasi facoltativo

Il nuovo valore dell'elemento, se presente.
oldValue

qualsiasi facoltativo

Il vecchio valore dell'elemento, se presente.

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 nell'archivio locale, misurata in base alla serializzazione 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 una policy, vedi Manifest per le aree di archiviazione.

Tipo

StorageArea

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 si utilizza un callback o quando una promessa viene rifiutata.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1.000.000

Obsoleto

L'API storage.sync non ha più una quota per le 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 una richiesta ogni 2 secondi, un limite inferiore rispetto a quello a breve termine di scritture al minuto.

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. Si tratta di 2 al secondo, il che offre una velocità effettiva superiore 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 in base alla 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 serializzazione JSON del suo 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 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

chrome.storage Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Descrizione

Autorizzazioni

Panoramica

Aree di stoccaggio

Manifest

Utilizzo

storage.local

storage.sync

storage.session

Limiti di spazio di archiviazione e limitazione

Casi d'uso

Risposta sincrona agli aggiornamenti dello spazio di archiviazione

Precaricamento asincrono dallo spazio di archiviazione

Esempi di estensioni

Tipi

AccessLevel

Enum

StorageChange

Proprietà

Proprietà

local

Tipo

Proprietà

managed

Tipo

sync

Tipo

Proprietà

Eventi

onChanged

Parametri

chrome.storage