chroom.opslag (original) (raw)

Beschrijving

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

Machtigingen

storage

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

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 :

Lokaal

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

Synchroniseren

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

Sessie

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 .

Typen

AccessLevel

Het toegangsniveau van de opslagruimte.

Enum

"VERTROUWDE_CONTEXTEN"
Geeft contexten op die afkomstig zijn van de extensie zelf.

"VERTROUWDE_EN_ONVERTROUWDE_CONTEXT"
Geeft contexten op die van buiten de extensie komen.

StorageArea

Eigenschappen

• onChanged
  Gebeurtenis
  Wordt geactiveerd wanneer een of meer items veranderen.
  De functie onChanged.addListener ziet er als volgt uit:
  (callback: function) => {...}
  • De callback ziet er als volgt uit:
    (changes: object) => void
• Verwijdert alle items uit de opslag.
  De clear -functie ziet er als volgt uit:
  () => {...}
• Haalt één of meer items uit de opslag.
  De get -functie ziet er als volgt uit:
  (keys?: string | string[] | object) => {...}
  • sleutels
    string | string[] | object optioneel
    Eén sleutel om op te halen, een lijst met op te halen sleutels, of een woordenboek met standaardwaarden (zie de beschrijving van het object). Een lege lijst of een leeg object retourneert een leeg resultaatobject. Geef null op om de volledige inhoud van de opslag op te halen.
• Geeft de hoeveelheid ruimte (in bytes) aan die door een of meer items wordt gebruikt.
  De functie getBytesInUse ziet er als volgt uit:
  (keys?: string | string[]) => {...}
  • sleutels
    string | string[] optioneel
    Eén sleutel of een lijst met sleutels om het totale gebruik te berekenen. Een lege lijst retourneert 0. Geef null op om het totale gebruik van alle opslagruimte te berekenen.
• Haalt alle sleutels uit de opslag.
  De getKeys -functie ziet er als volgt uit:
  () => {...}
  • retouren
    Belofte<string[]>
• Verwijdert één of meer items uit de opslag.
  De remove ziet er als volgt uit:
  (keys: string | string[]) => {...}
  • sleutels
    tekenreeks | tekenreeks[]
    Een enkele sleutel of een lijst met sleutels voor de items die verwijderd moeten worden.
• Stelt meerdere items in.
  De set ziet er als volgt uit:
  (items: object) => {...}
  • Een object dat elk sleutel/waardepaar geeft om de opslag mee bij te werken. Andere sleutel/waardeparen in de opslag worden niet beïnvloed.
    Primitieve waarden zoals getallen worden zoals verwacht geserialiseerd. Waarden met een typeof "object" en "function" worden doorgaans geserialiseerd naar {} , met uitzondering van Array (serialiseert zoals verwacht), Date en Regex (serialiseren met behulp van hun String representatie).
• Stelt het gewenste toegangsniveau voor de opslagruimte in. Standaard is session beperkt tot vertrouwde contexten (extensiepagina's en serviceworkers), terwijl managed , local en sync toegang toestaan vanuit zowel vertrouwde als niet-vertrouwde contexten.
  De functie setAccessLevel ziet er als volgt uit:
  (accessOptions: object) => {...}
  • • Het toegangsniveau van het opslagruimte.

StorageChange

Eigenschappen

• nieuweWaarde
  elke optionele
  De nieuwe waarde van het item, indien er een nieuwe waarde is.
• De oude waarde van het item, indien er een oude waarde was.

Eigenschappen

local

Items in het local opslaggebied zijn lokaal op elke machine.

Type

Opslaggebied en object

Eigenschappen

• De maximale hoeveelheid (in bytes) gegevens die in de lokale opslag kan worden opgeslagen, gemeten aan de hand van de JSON-stringificatie van elke waarde plus de lengte van elke sleutel. Deze waarde wordt genegeerd als de extensie de rechten unlimitedStorage heeft. Updates die ertoe zouden leiden dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback, of een afgewezen Promise bij gebruik van async/await.

managed

Items in het managed opslaggebied worden ingesteld door een bedrijfsbeleid dat is geconfigureerd door de domeinbeheerder en zijn alleen-lezen voor de extensie. Pogingen om deze naamruimte te wijzigen, resulteren in een fout. Zie Manifest voor opslaggebieden voor informatie over het configureren van een beleid.

Type

session

Items in het session worden in het geheugen opgeslagen en worden niet op schijf bewaard.

Type

Opslaggebied en object

Eigenschappen

• De maximale hoeveelheid (in bytes) gegevens die in het geheugen kan worden opgeslagen, gemeten door het dynamisch toegewezen geheugengebruik van elke waarde en sleutel te schatten. Updates die deze limiet zouden overschrijden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer een Promise wordt afgewezen.

sync

Items in het sync worden gesynchroniseerd via Chrome Sync.

Type

Opslaggebied en object

Eigenschappen

• Het maximale aantal items dat in de synchronisatieopslag kan worden opgeslagen. Updates die deze limiet overschrijden, mislukken direct en stellen runtime.lastError in bij gebruik van een callback of wanneer een Promise wordt afgewezen.
• MAXIMUM_DUURZAME_SCHRIJFBEWERKINGEN_PER_MINUUT
  1000000
  De storage.sync API heeft geen aanhoudende quota voor schrijfbewerkingen meer.
• MAXIMALE SCHRIJFBEWERKINGEN PER UUR
  1800
  Het maximale aantal set , remove of clear dat per uur kan worden uitgevoerd. Dit is 1 per 2 seconden, een lagere limiet dan de kortetermijnlimiet voor hogere schrijfbewerkingen per minuut.
  Updates die ervoor zorgen dat deze limiet wordt overschreden, mislukken direct en stellen runtime.lastError in wanneer er een callback wordt gebruikt of wanneer een Promise wordt afgewezen.
• MAXIMUM SCHRIJFBEWERKINGEN PER MINUUT
  120
  Het maximale aantal set , remove of clear -bewerkingen dat per minuut kan worden uitgevoerd. Dit is 2 per seconde, wat een hogere doorvoersnelheid oplevert dan schrijfbewerkingen per uur over een kortere periode.
  Updates die ervoor zorgen dat deze limiet wordt overschreden, mislukken direct en stellen runtime.lastError in wanneer er een callback wordt gebruikt of wanneer een Promise wordt afgewezen.
• De maximale totale hoeveelheid (in bytes) gegevens die in de synchronisatieopslag kan worden opgeslagen, gemeten aan de hand van de JSON-stringificatie van elke waarde plus de lengte van elke sleutel. Updates die ertoe zouden leiden dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer 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-stringificatie van de waarde plus de sleutellengte. Updates met items die groter zijn dan deze limiet mislukken direct en stellen runtime.lastError in bij gebruik van een callback of wanneer een Promise wordt afgewezen.

Evenementen

onChanged

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

Wordt geactiveerd wanneer een of meer items veranderen.

Parameters

• De callback ziet er als volgt uit:
  (changes: object, areaName: string) => void