Deze pagina is vertaald door de Cloud Translation API.

chroom.opslag

Beschrijving

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

Machtigingen

storage

Overzicht

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.

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

De service worker van de extensie heeft geen toegang tot Storage .
Inhoudsscripts delen opslag met de hostpagina.
Gegevens die via de Storage zijn opgeslagen, 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:

Maak een offscreen-document met een conversieroutine en een [ onMessage ][on-message]-handler.
Voeg een conversieroutine toe aan een offscreen-document.
Controleer in de extensie service worker chrome.storage op uw gegevens.
Als uw gegevens niet worden gevonden, [creëer][creëer-offscreen] dan een offscreen-document en roep [ sendMessage() ][send-message] aan om de conversieroutine te starten.
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][opslag-en-cookies].

Opslagruimtes

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

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

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. Overweeg dit te gebruiken om gebruikersinstellingen te behouden in gesynchroniseerde browsers.

Waarschuwing: Lokale en gesynchroniseerde opslaglocaties mogen geen vertrouwelijke gebruikersgegevens opslaan, omdat ze niet versleuteld zijn. Overweeg bij het werken met gevoelige gegevens de session te gebruiken om waarden in het geheugen te bewaren totdat de browser wordt afgesloten.

opslag.sessie: Bewaart gegevens in het geheugen gedurende een browsersessie. Standaard worden deze niet blootgesteld aan inhoudsscripts, maar dit gedrag kan worden gewijzigd door chrome.storage.session.setAccessLevel() in te stellen. De quotumlimiet is ongeveer 10 MB. Overweeg om deze te gebruiken voor het opslaan van globale variabelen tijdens 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. Deze opslaglocatie is alleen-lezen.

Manifest

Om de opslag-API te gebruiken, declareert u de machtiging "storage" 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 opslagruimtegebied.

Opslag- en throttlinglimieten

Beschouw het toevoegen aan de Storage API niet als het laden van spullen in een grote vrachtwagen. Zie het toevoegen aan de opslag als het laden van iets in een pijpleiding. De pijpleiding kan al materiaal bevatten en kan zelfs gevuld zijn. Houd altijd rekening met een vertraging tussen het toevoegen aan de opslag en het moment waarop het daadwerkelijk wordt geregistreerd.

Voor meer informatie over de beperkingen van opslagruimte 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.

Synchrone reactie op opslagupdates

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

Voorbeelden van uitbreidingen

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

Typen

AccessLevel

Chroom 102+

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<functievoidvoid>
Chroom 73+
Wordt geactiveerd wanneer een of meer items veranderen.
De functie onChanged.addListener ziet er als volgt uit:
```
(callback: function) => {...}
```
- terugbellen
  functie
  De callback ziet er als volgt uit:
```
(changes: object) => void
```
  - veranderingen
    voorwerp
duidelijk
leegte
Belofte
Verwijdert alle items uit de opslag.
De clear -functie ziet er als volgt uit:
```
(callback?: function) => {...}
```
- terugbellen
  functie optioneel
  De callback ziet er als volgt uit:
```
() => void
```
- retouren
  Belofte<leegte>
  Chroom 95+
  Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.
krijgen
leegte
Belofte
Haalt één of meer items uit de opslag.
De get -functie ziet er als volgt uit:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- 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.
- terugbellen
  functie optioneel
  De callback ziet er als volgt uit:
```
(items: object) => void
```
  - artikelen
    voorwerp
    Object met items in hun sleutel-waardetoewijzingen.
- retouren
  Belofte<object>
  Chroom 95+
  Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.
getBytesInUse
leegte
Belofte
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[], callback?: function) => {...}
```
- 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.
- terugbellen
  functie optioneel
  De callback ziet er als volgt uit:
```
(bytesInUse: number) => void
```
  - bytesInGebruik
    nummer
    De hoeveelheid ruimte die wordt gebruikt in opslag, in bytes.
- retouren
  Belofte<nummer>
  Chroom 95+
  Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.
sleutels ophalen
leegte
BelofteChrome 130+
Haalt alle sleutels uit de opslag.
De getKeys -functie ziet er als volgt uit:
```
(callback?: function) => {...}
```
- terugbellen
  functie optioneel
  De callback ziet er als volgt uit:
```
(keys: string[]) => void
```
  - sleutels
    snaar[]
    Array met sleutels gelezen uit de opslag.
- retouren
  Belofte<string[]>
  Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.
verwijderen
leegte
Belofte
Verwijdert één of meer items uit de opslag.
De remove ziet er als volgt uit:
```
(keys: string | string[], callback?: function) => {...}
```
- sleutels
  tekenreeks | tekenreeks[]
  Een enkele sleutel of een lijst met sleutels voor de items die verwijderd moeten worden.
- terugbellen
  functie optioneel
  De callback ziet er als volgt uit:
```
() => void
```
- retouren
  Belofte<leegte>
  Chroom 95+
  Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.
set
leegte
Belofte
Stelt meerdere items in.
De set ziet er als volgt uit:
```
(items: object, callback?: function) => {...}
```
- artikelen
  voorwerp
  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).
- terugbellen
  functie optioneel
  De callback ziet er als volgt uit:
```
() => void
```
- retouren
  Belofte<leegte>
  Chroom 95+
  Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.
setToegangsniveau
leegte
PromiseChrome 102+
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, callback?: function) => {...}
```
- toegangsopties
  voorwerp
  - toegangsniveau
    Toegangsniveau
    Het toegangsniveau van het opslagruimte.
- terugbellen
  functie optioneel
  De callback ziet er als volgt uit:
```
() => void
```
- retouren
  Belofte<leegte>
  Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

StorageChange

Eigenschappen

nieuweWaarde
elke optionele
De nieuwe waarde van het item, indien er een nieuwe waarde is.
oudeWaarde
elke optionele
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

QUOTA_BYTES
10485760
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

Opslaggebied

sync

Items in het sync worden gesynchroniseerd via Chrome Sync.

Type

Opslaggebied en object

Eigenschappen

MAX_ITEMS
512
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
Verouderd
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.
QUOTA_BYTES
102400
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

terugbellen
functie
De callback ziet er als volgt uit:
```
(changes: object, areaName: string) => void
```
- veranderingen
  voorwerp
- gebiedsnaam
  snaar

chroom.opslag Stay organized with collections Save and categorize content based on your preferences.

Beschrijving

Machtigingen

Overzicht

Opslagruimtes

Manifest

Gebruik

opslag.lokaal

opslag.synchronisatie

opslag.sessie

Opslag- en throttlinglimieten

Gebruiksscenario's

Synchrone reactie op opslagupdates

Asynchrone preload vanuit opslag

Voorbeelden van uitbreidingen

Typen

AccessLevel

Enum

StorageArea

Eigenschappen

StorageChange

Eigenschappen

Eigenschappen

local

Type

Eigenschappen

managed

Type

sync

Type

Eigenschappen

Evenementen

onChanged

Parameters

chroom.opslag