chroom.opslag

Beschrijving

Toestemmingen

Overzicht

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.

Hoewel extensies in sommige contexten (pop-ups en andere HTML-pagina's) gebruik kunnen maken van de [ Storage ][mdn-storage]-interface (toegankelijk via window.localStorage ), wordt dit om de volgende redenen afgeraden:

• De service worker van de extensie heeft geen toegang tot Storage .
• Contentscripts delen opslagruimte met de hostpagina.
• Gegevens die via de Storage zijn opgeslagen, gaan verloren wanneer de gebruiker zijn browsegeschiedenis wist.

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

1. Maak een offscreen-document met een conversieroutine en een [ onMessage ][on-message]-handler.
2. Voeg een conversieroutine toe aan een document dat niet op het scherm wordt weergegeven.
3. Controleer in de service worker van de extensie de map chrome.storage voor uw gegevens.
4. Als uw gegevens niet worden gevonden, maak dan een offscreen-document aan en roep [ 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 [Opslag en cookies][storage-and-cookies].

Opslagruimtes

De Storage API is onderverdeeld in de volgende vier categorieën ("opslaggebieden"):

storage.local

De gegevens worden lokaal opgeslagen en gewist wanneer de extensie wordt verwijderd. De opslaglimiet is ongeveer 10 MB, maar kan worden verhoogd door de machtiging "unlimitedStorage" aan te vragen. Overweeg deze te gebruiken voor het opslaan van grotere hoeveelheden gegevens.

storage.sync

Als synchronisatie is ingeschakeld, worden de gegevens gesynchroniseerd met elke Chrome-browser waarin de gebruiker is ingelogd. Als synchronisatie is uitgeschakeld, werkt het net 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. Overweeg deze optie te gebruiken om gebruikersinstellingen te behouden in gesynchroniseerde browsers.

opslag.sessie

Bewaart gegevens in het geheugen gedurende de duur van een browsersessie. Standaard is het niet toegankelijk voor scripts, maar dit gedrag kan worden gewijzigd door chrome.storage.session.setAccessLevel() in te stellen. De quotumlimiet is ongeveer 10 MB. Overweeg het te gebruiken om globale variabelen op te slaan die meerdere keren achter elkaar in een service worker worden uitgevoerd.

opslag.beheerd

Beheerders kunnen een schema en bedrijfsbeleid gebruiken om de instellingen van een ondersteunende extensie in een beheerde omgeving te configureren. Dit opslaggebied is alleen-lezen.

Manifest

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

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

Gebruik

De volgende voorbeelden illustreren de local , sync en session :

opslag.lokaal

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

opslag.synchronisatie

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

opslag.sessie

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

Zie het manifest voor opslaggebieden voor meer informatie over het managed opslaggebied.

Opslag- en beperkingslimieten

Zie het toevoegen aan de Storage API niet als het laden van spullen in een grote vrachtwagen. Zie het toevoegen aan de opslag als het plaatsen van iets in een pijp. De pijp kan al materiaal bevatten en zelfs helemaal vol zijn. Ga er altijd vanuit dat er een vertraging is tussen het moment dat je iets toevoegt aan de opslag en het moment dat het daadwerkelijk wordt geregistreerd.

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 .

Gebruiksvoorbeelden

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

Synchrone reactie op updates van de opslag

Om wijzigingen in de opslag bij te houden, kunt u een listener toevoegen 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 altijd 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 is gevuld 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);
});

Uitbreidingsvoorbeelden

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

• Globale zoekextensie .
• Wateralarmverlenging .

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