chroom.opslag

Beschrijving

Rechten

Overzicht

De Storage API biedt een extensiespecifieke manier om gebruikersgegevens en -status te behouden. Het 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 kenmerken:

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

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

• De servicemedewerker van het toestel heeft geen toegang tot Storage .
• Inhoudsscripts delen opslag met de hostpagina.
• Gegevens die zijn opgeslagen met behulp van de Storage gaan verloren wanneer de gebruiker zijn browsegeschiedenis wist.

Gegevens verplaatsen van webopslag-API's naar uitbreidingsopslag-API's van een servicemedewerker:

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 in de extensieservicemedewerker chrome.storage op uw gegevens.
4. Als uw gegevens niet worden gevonden, [maak][create-offscreen] dan een offscreen document en roep [ 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 webopslag-API's in extensies werken. Lees meer in het artikel [Opslag en cookies][opslag-en-cookies].

Opslagplaatsen

De Storage API is onderverdeeld in de volgende vier buckets ("opslaggebieden"):

storage.local

Gegevens worden lokaal opgeslagen, wat wordt gewist wanneer de extensie wordt verwijderd. De quotumbeperking bedraagt ​​ongeveer 10 MB, maar kan worden verhoogd door de machtiging "unlimitedStorage" aan te vragen. Overweeg het te gebruiken om grotere hoeveelheden gegevens op te slaan.

storage.sync

Als synchronisatie is ingeschakeld, worden de gegevens gesynchroniseerd met elke Chrome-browser waarbij de gebruiker is ingelogd. Indien 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 quotumbeperking is ongeveer 100 KB, 8 KB per item. Overweeg het te gebruiken om gebruikersinstellingen in gesynchroniseerde browsers te behouden.

opslag.sessie

Houdt gegevens in het geheugen vast voor de duur van een browsersessie. Standaard wordt het niet blootgesteld aan inhoudsscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.session.setAccessLevel() in te stellen. De quotumbeperking bedraagt ​​ongeveer 10 MB. Overweeg het te gebruiken om globale variabelen op te slaan voor alle service worker-runs.

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

Als u de opslag-API wilt gebruiken, geeft u de machtiging "storage" op in het extensiemanifest . Bijvoorbeeld:

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

Gebruik

De volgende voorbeelden demonstreren 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 Manifest voor opslagruimten voor meer informatie over het managed opslaggebied.

Opslag- en beperkingslimieten

Beschouw het toevoegen aan de Storage API niet als iets in een grote vrachtwagen stoppen. Beschouw het toevoegen aan opslagruimte alsof je iets in een pijp stopt. Het kan zijn dat er al materiaal in de pijp zit en dat deze zelfs gevuld is. Ga altijd uit van een vertraging tussen het moment waarop u opslagruimte toevoegt en het moment waarop deze daadwerkelijk wordt opgenomen.

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

Gebruiksgevallen

In de volgende secties worden algemene gebruiksscenario's voor de Storage API gedemonstreerd.

Synchrone reactie op opslagupdates

Als u wijzigingen in de opslag wilt bijhouden, kunt u een luisteraar toevoegen aan de onChanged gebeurtenis. Wanneer er iets verandert in de opslag, wordt die gebeurtenis geactiveerd. De voorbeeldcode luistert naar deze 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 doorvoeren. In dit voorbeeld hebben we een optiepagina waarmee de gebruiker een "foutopsporingsmodus" kan inschakelen (implementatie wordt hier niet weergegeven). 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.

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 servicemedewerkers niet altijd actief zijn, moeten Manifest V3-extensies soms asynchroon gegevens uit de opslag laden voordat ze hun gebeurtenishandlers uitvoeren. Om dit te doen, gebruikt het volgende fragment een asynchrone gebeurtenishandler action.onClicked die wacht tot de storageCache global 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);
});

Voorbeelden van uitbreidingen

Bekijk een van de volgende voorbeelden om andere demo's van de Storage API te bekijken:

• Globale zoekextensie .
• Uitbreiding wateralarm .

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