chrome.storage

refresh date: 2026-09-25 robots: noindex

Beschrijving

Gebruik de chrome.storage API om wijzigingen in gebruikersgegevens op te slaan, op te halen en bij te houden.

Rechten

storage

Overzicht

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.

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

  • De servicemedewerker van de extensie heeft geen toegang tot Storage.
  • Contentscripts delen opslag met de hostpagina.
  • Gegevens die zijn opgeslagen via de Storage-interface, gaan verloren als de gebruiker de browsegeschiedenis wist.

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

  1. Maak een document buiten het scherm met een conversieroutine en een [onMessage][on-message]-handler.
  2. Voeg een conversieroutine toe aan een document buiten het scherm.
  3. Controleer chrome.storage op je gegevens in de servicemedewerker van de extensie.
  4. Als je gegevens niet worden gevonden, [maak][create-offscreen] je een offscreen document en roep je [sendMessage()][send-message] 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 vind je in het artikel [Opslag en cookies][storage-and-cookies].

Opslagruimtes

De Storage API is onderverdeeld in de volgende 4 buckets ('opslaggebieden'):

storage.local
Gegevens worden lokaal opgeslagen en worden gewist als de extensie wordt verwijderd. De quotumlimiet is ongeveer 10 MB, maar kan worden verhoogd door het recht "unlimitedStorage" aan te vragen. Gebruik deze optie om grotere hoeveelheden gegevens op te slaan.
storage.sync
Als synchronisatie aanstaat, 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. Gebruik deze instelling om gebruikersinstellingen te behouden in gesynchroniseerde browsers.
storage.session
Slaat gegevens op in het geheugen voor de duur van een browsersessie. Standaard wordt deze niet blootgesteld aan contentscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.session.setAccessLevel() in te stellen. De quotumlimiet is ongeveer 10 MB. Je kunt deze gebruiken om globale variabelen op te slaan voor verschillende service worker-uitvoeringen.
storage.managed
Beheerders kunnen een schema en bedrijfsbeleid gebruiken om de instellingen van een ondersteunende extensie te configureren in een beheerde omgeving. Dit opslaggebied is alleen-lezen.

Manifest

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

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

Gebruik

De volgende voorbeelden tonen de opslaggebieden local, sync en 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);
});

Ga naar Manifest voor opslagruimtes voor meer informatie over de opslagruimte managed.

Opslag- en throttlinglimieten

Denk niet dat je dingen in een grote vrachtwagen stopt als je ze toevoegt aan de Storage API. Je kunt het toevoegen aan de opslag vergelijken met iets in een buis stoppen. De buis kan al materiaal bevatten en kan zelfs gevuld zijn. Ga er altijd van uit dat er een vertraging is tussen het moment waarop je iets aan de opslag toevoegt en het moment waarop het daadwerkelijk wordt geregistreerd.

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

Toepassingen

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

Synchrone reactie op opslagupdates

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

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

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

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

Voorbeelden van extensies

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

Typen

AccessLevel

Chrome 102 of hoger

Het toegangsniveau van de opslagruimte.

Enum

TRUSTED_CONTEXTS
Geeft contexten aan die afkomstig zijn van de extensie zelf.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Hiermee worden contexten aangegeven die van buiten de extensie komen.

StorageChange

Eigenschappen

  • newValue

    alleen optioneel

    De nieuwe waarde van het item, als er een nieuwe waarde is.

  • oldValue

    alleen optioneel

    De oude waarde van het item, als er een oude waarde was.

Eigenschappen

local

Items in het opslaggebied local zijn lokaal voor elke machine.

Type

StorageArea-object

Eigenschappen

  • QUOTA_BYTES

    10485760

    De maximale hoeveelheid (in bytes) gegevens die kan worden opgeslagen in de lokale opslag, gemeten door de json-stringificatie van elke waarde plus de lengte van elke sleutel. Deze waarde wordt genegeerd als de extensie het recht unlimitedStorage heeft. Updates die ertoe leiden dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in als je een callback gebruikt, of een afgewezen Promise als je async/await gebruikt.

managed

Items in het opslaggebied managed worden ingesteld door een bedrijfsbeleid dat is geconfigureerd door de domeinbeheerder en zijn alleen-lezen voor de extensie. Als je deze naamruimte probeert aan te passen, krijg je een foutmelding. Ga naar Manifest voor opslagruimtes voor informatie over hoe je een beleid instelt.

Type

StorageArea

sync

Items in het opslaggebied sync worden gesynchroniseerd via Chrome-synchronisatie.

Type

StorageArea-object

Eigenschappen

  • MAX_ITEMS

    512

    Het maximale aantal items dat kan worden opgeslagen in de synchronisatieopslag. Updates die ertoe leiden dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in als je een callback gebruikt of als een Promise wordt afgewezen.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Beëindigd

    De storage.sync API heeft geen quotum meer voor doorlopende schrijfbewerkingen.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    Het maximale aantal set-, remove- of clear-bewerkingen dat per uur kan worden uitgevoerd. Dit is 1 per 2 seconden, een lagere limiet dan de hogere limiet voor schrijfbewerkingen per minuut op de korte termijn.

    Updates die ertoe leiden dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in als je een callback gebruikt of als een Promise wordt afgewezen.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Het maximale aantal set-, remove- of clear-bewerkingen dat per minuut kan worden uitgevoerd. Dit is 2 per seconde, wat een hogere doorvoer biedt dan schrijfbewerkingen per uur over een kortere periode.

    Updates die ertoe leiden dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in als je een callback gebruikt of als een Promise wordt afgewezen.

  • QUOTA_BYTES

    102400

    De maximale totale hoeveelheid (in bytes) aan gegevens die kan worden opgeslagen in de synchronisatieopslag, gemeten aan de hand van de JSON-stringificatie van elke waarde plus de lengte van elke sleutel. Updates die ertoe leiden dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in als je een callback gebruikt of als een Promise wordt afgewezen.

  • QUOTA_BYTES_PER_ITEM

    8192

    De maximale grootte (in bytes) van elk afzonderlijk item in de synchronisatieopslag, gemeten aan de hand van de JSON-tekenreeks van de waarde plus de sleutellengte. Updates met items die groter zijn dan deze limiet, mislukken onmiddellijk en stellen runtime.lastError in als je een callback gebruikt of als een Promise wordt geweigerd.

Evenementen

onChanged

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

Wordt geactiveerd als een of meer items worden gewijzigd.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

    (changes: object, areaName: string) => void

    • veranderingen

      object

    • areaName

      tekenreeks