chroom.opslag

Beschrijving

Toestemmingen

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

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

Voorbeelden

De volgende voorbeelden illustreren 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 is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Om andere demonstraties van de Storage API te bekijken, kunt u een van de volgende voorbeelden raadplegen:

• Globale zoekextensie .
• Wateralarmverlenging .

Concepten en gebruik

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

• Alle extensiecontexten, inclusief de extensieserviceworker en inhoudsscripts, hebben toegang tot de Storage API.
• De JSON-serialiseerbare waarden worden opgeslagen als objecteigenschappen.
• De Storage API is asynchroon en ondersteunt bulklees- en schrijfbewerkingen.
• Zelfs als de gebruiker de cache en browsegeschiedenis wist, blijven de gegevens bewaard.
• Opgeslagen instellingen blijven behouden, zelfs bij gebruik van de gesplitste incognitomodus .
• Inclusief een exclusieve, alleen-lezen beheerde opslagruimte voor bedrijfsbeleid.

Kunnen extensies gebruikmaken van webopslag-API's?

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

• Medewerkers van extensieservices kunnen de Web Storage API niet gebruiken.
• Contentscripts delen opslagruimte met de hostpagina.
• Gegevens die zijn opgeslagen met behulp van de Web Storage API gaan verloren wanneer de gebruiker zijn of haar browsegeschiedenis wist.

Om gegevens van webopslag-API's naar extensieopslag-API's te verplaatsen vanuit een service worker:

1. Maak een HTML-pagina voor een offscreen-document en een scriptbestand aan. Het scriptbestand moet een conversieroutine en een onMessage handler bevatten.
2. Controleer in de extension service worker de map chrome.storage voor uw gegevens.
3. Als uw gegevens niet worden gevonden, roep dan 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 met betrekking tot de werking van webopslag-API's in extensies. Lees meer in het artikel over opslag en cookies .

Opslag- en beperkingslimieten

De Storage API kent gebruiksbeperkingen:

• Het opslaan van data brengt prestatiekosten met zich mee, en de API hanteert opslagquota. Plan daarom zorgvuldig welke data u wilt opslaan, zodat u voldoende opslagruimte behoudt.
• Opslag kan enige tijd in beslag nemen. Houd bij het structureren van je code rekening met deze tijdsduur.

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

Opslagruimtes

De Storage API is onderverdeeld in de volgende opslaggebieden:

Lokaal

Gegevens worden lokaal opgeslagen en verwijderd 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 voor het opslaan van grotere hoeveelheden gegevens. Standaard is deze beschikbaar voor content scripts, maar dit gedrag kan worden gewijzigd door chrome.storage.local.setAccessLevel() aan te roepen.

Beheerd

Beheerde opslag is alleen-lezen voor via beleid geïnstalleerde extensies. Het 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 de gebruiker. Hierdoor kan de extensie vooraf worden geconfigureerd voor alle gebruikers van een organisatie.

Standaard is storage.managed toegankelijk voor contentscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.managed.setAccessLevel() aan te roepen. Zie de documentatie voor beheerders voor meer informatie over beleid. Zie het manifest voor opslaggebieden voor meer informatie over het managed opslaggebied.

Sessie

Sessieopslag bewaart gegevens in het geheugen zolang een extensie is geladen. De opslag wordt gewist als de extensie wordt uitgeschakeld, opnieuw geladen, bijgewerkt of wanneer de browser opnieuw wordt opgestart. Standaard is de opslag niet toegankelijk voor scripts, maar dit gedrag kan worden gewijzigd door de functie 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 .

Synchroniseren

Als de gebruiker synchronisatie inschakelt, worden de gegevens gesynchroniseerd met elke Chrome-browser waarin de gebruiker is ingelogd. Indien uitgeschakeld, werkt het 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 om storage.sync te gebruiken om gebruikersinstellingen te behouden tussen gesynchroniseerde browsers. Als u met gevoelige gebruikersgegevens werkt, gebruik dan in plaats daarvan storage.session . Standaard is storage.sync toegankelijk voor contentscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.sync.setAccessLevel() aan te roepen.

Methoden en gebeurtenissen

Alle opslaggebieden implementeren de StorageArea interface.

krijgen()

Met de get() methode kunt u een of meer sleutels uit een StorageArea lezen.

getBytesInUse()

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

getKeys()

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

verwijderen()

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

set()

Met de set() -methode kunt u een item in een StorageArea plaatsen.

setAccessLevel()

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

duidelijk()

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

gewijzigd

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

Gebruiksvoorbeelden

De volgende secties illustreren veelvoorkomende gebruiksscenario's voor de Storage API.

Reageer op updates voor de opslag.

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 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 "debugmodus" kan in- of uitschakelen (implementatie 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);

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 service workers niet continu actief zijn, moeten Manifest V3-extensies soms asynchroon gegevens uit de opslag laden voordat ze hun gebeurtenisafhandelaars uitvoeren. Om dit te doen, gebruikt het volgende codefragment een asynchrone action.onClicked -gebeurtenisafhandelaar die wacht tot de globale variabele storageCache gevuld is 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);
});

Ontwikkeltools

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

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