chroom.opslag

Beschrijving

Machtigingen

Om de opslag-API te gebruiken, declareert u de machtiging "storage" in het extensiemanifest . Bijvoorbeeld:

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

Begrippen en gebruik

De Storage API biedt een extensiespecifieke manier om gebruikersgegevens en -status te bewaren. Deze is vergelijkbaar met de storage API's van het webplatform ( IndexedDB en Storage ), maar is ontworpen om te voldoen aan de opslagbehoeften van extensies. Hieronder volgen enkele belangrijke kenmerken:

• Alle extensiecontexten, inclusief de extensieserviceworker en inhoudsscripts, hebben toegang tot de Storage API.
• De serialiseerbare JSON-waarden worden opgeslagen als objecteigenschappen.
• De Storage API is asynchroon met bulk lees- en schrijfbewerkingen.
• Zelfs als de gebruiker de cache en de browsegeschiedenis wist, blijven de gegevens behouden.
• Opgeslagen instellingen blijven behouden, zelfs wanneer u de functie 'split incognito' gebruikt.
• Bevat een exclusief, alleen-lezen beheerd opslaggebied voor bedrijfsbeleid.

Kunnen extensies webopslag-API's gebruiken?

Hoewel extensies in sommige contexten (pop-up en andere HTML-pagina's) de Storage (toegankelijk via window.localStorage ) kunnen gebruiken, raden wij dit om de volgende redenen niet aan:

• Medewerkers van uitbreidingsdiensten kunnen de Web Storage API niet gebruiken.
• Inhoudsscripts delen opslag met de hostpagina.
• Gegevens die zijn opgeslagen met de Web Storage API gaan verloren wanneer de gebruiker zijn browsegeschiedenis wist.

Ga als volgt te werk om gegevens van webopslag-API's naar extensieopslag-API's van een service worker te verplaatsen:

1. Maak een offscreen document (html-pagina en scriptbestand). Het scriptbestand moet een conversieroutine en een onMessage handler bevatten.
2. Controleer in de extensieserviceworker of uw gegevens in chrome.storage staan.
3. Als uw gegevens niet worden gevonden, roept u createDocument() aan.
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 offscreen-document.

Er zijn ook enkele nuances in de manier waarop webopslag-API's in extensies werken. Lees meer in het artikel Opslag en cookies .

Opslagruimtes

De Storage API is onderverdeeld in de volgende opslaggebieden:

storage.local

Gegevens worden lokaal opgeslagen en gewist wanneer de extensie wordt verwijderd. De opslaglimiet is 10 MB (5 MB in Chrome 113 en ouder), maar kan worden verhoogd door de machtiging "unlimitedStorage" aan te vragen. We raden aan om storage.local te gebruiken om grotere hoeveelheden gegevens op te slaan. Standaard is storage.local toegankelijk voor contentscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.local.setAccessLevel() aan te roepen.

storage.managed

Beheerde opslag is alleen-lezen opslag voor extensies die via beleid zijn geïnstalleerd en wordt beheerd door systeembeheerders met behulp van een door de ontwikkelaar gedefinieerd schema en bedrijfsbeleid. Beleid is vergelijkbaar met opties, maar wordt geconfigureerd door een systeembeheerder in plaats van door de gebruiker, waardoor de extensie vooraf kan worden geconfigureerd voor alle gebruikers van een organisatie. Standaard is storage.managed beschikbaar voor inhoudsscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.managed.setAccessLevel() aan te roepen. Zie Documentatie voor beheerders voor informatie over beleid. Zie Manifest voor opslaggebieden voor meer informatie over het managed opslaggebied.

storage.session

Houdt gegevens in het geheugen vast terwijl een extensie wordt geladen. De opslag wordt gewist als de extensie wordt uitgeschakeld, opnieuw geladen of bijgewerkt, en wanneer de browser opnieuw wordt opgestart. Standaard is deze niet beschikbaar voor contentscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.session.setAccessLevel() aan te roepen. De opslaglimiet is 10 MB (1 MB in Chrome 111 en ouder). De storage.session interface is een van de interfaces die we aanbevelen voor service workers .

storage.sync

Als synchronisatie is ingeschakeld, worden de gegevens gesynchroniseerd met elke Chrome-browser waarop de gebruiker is ingelogd. Als synchronisatie is uitgeschakeld, gedraagt het zich als storage.local . Chrome slaat de gegevens lokaal op wanneer de browser offline is en hervat de synchronisatie wanneer deze weer online is. De quotumlimiet is ongeveer 100 KB, 8 KB per item. We raden aan storage.sync te gebruiken om gebruikersinstellingen in alle gesynchroniseerde browsers te behouden. Als u met gevoelige gebruikersgegevens werkt, gebruikt u in plaats daarvan storage.session . Standaard is storage.sync beschikbaar voor contentscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.sync.setAccessLevel() aan te roepen.

Opslag- en throttlinglimieten

De Storage API heeft de volgende gebruiksbeperkingen:

• Het opslaan van gegevens brengt vaak prestatiekosten met zich mee en de API kent opslagquota's. We raden u aan zorgvuldig te kiezen welke gegevens u opslaat, zodat u de mogelijkheid om gegevens op te slaan niet verliest.
• Het kan enige tijd duren om de opslag te voltooien. Zorg ervoor dat je code zo is gestructureerd dat je rekening houdt met die tijd.

Voor meer informatie over opslagruimtebeperkingen en wat er gebeurt als deze worden overschreden, raadpleegt u de quota-informatie voor sync , local en session .

Gebruiksscenario's

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

Reageren op opslagupdates

Om wijzigingen in de opslag bij te houden, voegt u een listener toe aan de onChanged -gebeurtenis. Wanneer er iets in de opslag verandert, wordt die gebeurtenis geactiveerd. De voorbeeldcode luistert naar de volgende wijzigingen:

achtergrond.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 doortrekken. In dit voorbeeld hebben we een optiepagina waarmee de gebruiker een "debugmodus" kan in- of uitschakelen (implementatie hier niet getoond). De optiepagina slaat de nieuwe instellingen direct op in storage.sync en de service worker gebruikt storage.onChanged om de instelling zo snel mogelijk toe te passen.

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

opties.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);

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

Asynchrone preload vanuit opslag

Omdat service workers niet continu actief zijn, moeten Manifest V3-extensies soms asynchroon gegevens uit de opslag laden voordat ze hun event handlers uitvoeren. Om dit te doen, gebruikt het volgende fragment een asynchrone event handler action.onClicked die wacht tot de globale storageCache is gevuld voordat de logica ervan wordt uitgevoerd.

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

Ontwikkelaarshulpmiddelen

U kunt gegevens bekijken en bewerken die zijn opgeslagen met de API in DevTools. Zie de pagina 'Extensieopslag bekijken en bewerken' in de DevTools-documentatie voor meer informatie.

Voorbeelden

De volgende voorbeelden demonstreren de local , sync en session :

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

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

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

Als u andere demo's van de Storage API wilt bekijken, kunt u de volgende voorbeelden bekijken:

• Wereldwijde zoekextensie .
• Uitbreiding wateralarm .

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