browser.storage

Beschrijving

Rechten

Als je de Storage API wilt gebruiken, definieer je het recht "storage" in het manifest van de extensie. Voorbeeld:

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

Voorbeelden

De volgende voorbeelden tonen de opslaggebieden local, sync en session:

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

Bekijk de volgende voorbeelden voor andere demo's van de Storage API:

• Algemene zoekextensie.
• Extensie voor wateralarm.

Concepten en gebruik

De Storage API biedt een extensiespecifieke manier om gebruikersgegevens en -status te behouden. Deze API is vergelijkbaar met de opslag-API's van het webplatform (IndexedDB en Storage), maar is ontworpen om te voldoen aan de opslagbehoeften van extensies. Dit zijn enkele belangrijke functies:

• Alle extensiecontexten, waaronder de extensieserviceworker en contentscripts, hebben toegang tot de Storage API.
• De JSON-serialiseerbare waarden worden opgeslagen als objecteigenschappen.
• De Storage API is asynchroon met bulkbewerkingen voor lezen en schrijven.
• Zelfs als de gebruiker het cachegeheugen en de browsegeschiedenis wist, blijven de gegevens bewaard.
• Opgeslagen instellingen blijven behouden, zelfs als je gesplitste incognitomodus gebruikt.
• Bevat een exclusief alleen-lezen beheerd opslaggebied voor bedrijfsbeleid.

Kunnen extensies API's voor webopslag gebruiken?

Hoewel extensies in sommige contexten (pop-ups en andere HTML-pagina's) de interface Storage (toegankelijk via window.localStorage) kunnen gebruiken, raden we dit om de volgende redenen af:

• Service workers voor extensies kunnen de Web Storage API niet gebruiken.
• Contentscripts delen opslag met de hostpagina.
• Gegevens die zijn opgeslagen met de Web Storage API, gaan verloren als de gebruiker de browsegeschiedenis wist.

Zo verplaats je gegevens van webopslag-API's naar extensieopslag-API's vanuit een serviceworker:

1. Bereid een html-pagina en scriptbestand voor een document buiten het scherm voor. Het scriptbestand moet een conversieroutine en een onMessage-handler bevatten.
2. Controleer in de serviceworker van de extensie browser.storage op je gegevens.
3. Als je gegevens niet worden gevonden, bel je createDocument().
4. Nadat de geretourneerde Promise is opgelost, roept u sendMessage() aan om de conversieroutine te starten.
5. Roep de conversieroutine aan in de onMessage-handler van het document buiten het scherm.

Er zijn ook enkele nuances in de manier waarop API's voor webopslag werken in extensies. Meer informatie vindt u in het artikel Opslag en cookies.

Opslag- en throttlinglimieten

De Storage API heeft gebruikslimieten:

• Gegevensopslag heeft prestatiekosten en de API bevat opslagquota. Plan de gegevens die je wilt opslaan, zodat je opslagruimte behoudt.
• Het kan even duren voordat de opslag is afgerond. Structureer je code om rekening te houden met die tijd.

Ga naar de quotumgegevens voor sync, local en session voor meer informatie over de beperkingen van opslagruimtes en wat er gebeurt als deze worden overschreden.

Opslagruimtes

De Storage API is onderverdeeld in de volgende opslaggebieden:

Lokaal

Gegevens worden lokaal opgeslagen en gewist als de extensie wordt verwijderd. De opslaglimiet is 10 MB (5 MB in Chrome 113 en lager), maar kan worden verhoogd door het recht "unlimitedStorage" aan te vragen. We raden je aan storage.local te gebruiken om grotere hoeveelheden gegevens op te slaan. Standaard wordt de API blootgesteld aan contentscripts, maar dit gedrag kan worden gewijzigd door browser.storage.local.setAccessLevel() aan te roepen.

Beheerd

Beheerde opslag is alleen-lezen voor extensies die zijn geïnstalleerd via beleid. Het wordt beheerd door systeembeheerders met een door de ontwikkelaar gedefinieerd schema en bedrijfsbeleid. Beleid is vergelijkbaar met opties, maar wordt ingesteld door een systeembeheerder in plaats van de gebruiker. Zo kan de extensie vooraf worden ingesteld voor alle gebruikers van een organisatie.

Standaard wordt storage.managed blootgesteld aan contentscripts, maar dit gedrag kan worden gewijzigd door browser.storage.managed.setAccessLevel() aan te roepen. Ga naar Documentatie voor beheerders voor meer informatie over beleid. Ga naar Manifest voor opslagruimtes voor meer informatie over de opslagruimte managed.

Sessie

Sessieopslag bewaart gegevens in het geheugen terwijl een extensie is geladen. De opslag wordt gewist als de extensie wordt uitgezet, opnieuw wordt geladen of wordt geüpdatet en als de browser opnieuw wordt opgestart. Standaard wordt deze niet blootgesteld aan contentscripts, maar dit gedrag kan worden gewijzigd door browser.storage.session.setAccessLevel() aan te roepen. De opslaglimiet is 10 MB (1 MB in Chrome 111 en lager).

De storage.session-interface is een van de interfaces die we aanbevelen voor serviceworkers.

Synchroniseren

Als de gebruiker synchronisatie aanzet, worden de gegevens gesynchroniseerd met elke Chrome-browser waarbij de gebruiker is ingelogd. Als je het beleid uitzet, gedraagt het zich als storage.local. Chrome slaat de gegevens lokaal op als de browser offline is en hervat de synchronisatie als de browser weer online is. De quotumlimiet is ongeveer 100 KB, 8 KB per item.

We raden je aan storage.sync te gebruiken om gebruikersinstellingen te behouden in gesynchroniseerde browsers. Als je met gevoelige gebruikersgegevens werkt, gebruik je storage.session. Standaard wordt storage.sync blootgesteld aan contentscripts, maar dit gedrag kan worden gewijzigd door browser.storage.sync.setAccessLevel() aan te roepen.

Methoden en gebeurtenissen

Alle opslagruimtes implementeren de StorageArea-interface.

get()

Met de methode get() kun je een of meer sleutels lezen uit een StorageArea.

getBytesInUse()

Met de methode getBytesInUse() kunt u het quotum bekijken dat wordt gebruikt door een StorageArea.

getKeys()

Met de methode getKeys() kunt u alle sleutels ophalen die zijn opgeslagen in een StorageArea.

remove()

Met de methode remove() kunt u een item verwijderen uit een StorageArea.

set()

Met de methode set() kun je een item instellen in een StorageArea.

setAccessLevel()

Met de methode setAccessLevel() kunt u de toegang tot een StorageArea beheren.

clear()

Met de methode clear() kunt u alle gegevens uit een StorageArea wissen.

onChanged

Met de gebeurtenis onChanged kunt u wijzigingen in een StorageArea bijhouden.

Toepassingen

In de volgende gedeelten worden veelvoorkomende use cases voor de Storage API beschreven.

Reageren op opslagupdates

Als je wijzigingen in de opslag wilt bijhouden, voeg je een listener toe aan de gebeurtenis onChanged. Als er iets verandert in de opslag, wordt die gebeurtenis geactiveerd. De voorbeeldcode luistert naar deze wijzigingen:

background.js:

browser.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}".`
    );
  }
});

We kunnen dit idee nog verder uitwerken. In dit voorbeeld hebben we een optiepagina waarmee de gebruiker een foutopsporingsmodus kan aan- of uitzetten (implementatie wordt hier niet getoond). De optiepagina slaat de nieuwe instellingen onmiddellijk op in storage.sync en de servicemedewerker gebruikt storage.onChanged om de instelling zo snel mogelijk toe te passen.

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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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);
  }
});

Asynchroon vooraf laden vanuit opslag

Omdat serviceworkers niet altijd actief zijn, moeten Manifest V3-extensies soms asynchroon gegevens uit de opslag laden voordat ze hun gebeurtenishandlers uitvoeren. Hiervoor gebruikt het volgende fragment een asynchrone action.onClicked-gebeurtenishandler die wacht tot de globale storageCache is ingevuld voordat de logica wordt uitgevoerd.

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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.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;
  browser.storage.sync.set(storageCache);
});

DevTools

Je kunt gegevens die zijn opgeslagen met de API bekijken en bewerken in DevTools. Ga naar de pagina Extensieopslag bekijken en bewerken in de DevTools-documentatie voor meer informatie.

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