Deze pagina is vertaald door de Cloud Translation API.

chroom.opslag

Beschrijving

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

Machtigingen

storage

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:

Maak een document buiten het scherm met een conversieroutine en een [ onMessage ] [on-message] handler.
Voeg een conversieroutine toe aan een document buiten het scherm.
Controleer in de extensieservicemedewerker chrome.storage op uw gegevens.
Als uw gegevens niet worden gevonden, [maak][create-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 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].

Opslagruimtes

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.

Waarschuwing: Lokale en gesynchroniseerde opslaggebieden mogen geen vertrouwelijke gebruikersgegevens opslaan, omdat deze niet gecodeerd zijn. Wanneer u met gevoelige gegevens werkt, kunt u overwegen het session te gebruiken om waarden in het geheugen vast te houden totdat de browser wordt afgesloten.

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 opbergruimte 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 schakelen (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:

Soorten

AccessLevel

Chroom 102+

Het toegangsniveau van de opslagruimte.

Enum

"TRUSTED_CONTEXTS"
Specificeert contexten die afkomstig zijn van de extensie zelf.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Specificeert contexten die van buiten de extensie komen.

StorageArea

Eigenschappen

opGewijzigd
Gebeurtenis<functionvoidvoid>
Chroom 73+
Wordt geactiveerd wanneer een of meer items veranderen.
De onChanged.addListener -functie ziet er als volgt uit:
```
(callback: function) => {...}
```
- terugbellen
  functie
  De callback parameter 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 parameter ziet er als volgt uit:
```
() => void
```
- retourneert
  Beloof <nietig>
  Chroom 88+
  Beloften worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.
krijgen
leegte
Belofte
Haalt een of meer items uit de opslag.
De get functie ziet er als volgt uit:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- sleutels
  tekenreeks | tekenreeks[] | object optioneel
  Eén enkele sleutel om op te halen, een lijst met sleutels om op te halen, of een woordenboek met standaardwaarden (zie beschrijving van het object). Een lege lijst of object retourneert een leeg resultaatobject. Geef null door om de volledige inhoud van de opslag te krijgen.
- terugbellen
  functie optioneel
  De callback parameter ziet er als volgt uit:
```
(items: object) => void
```
  - artikelen
    voorwerp
    Object met items in hun sleutelwaardetoewijzingen.
- retourneert
  Beloof<object>
  Chroom 88+
  Beloften worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.
getBytesInUse
leegte
Belofte
Haalt de hoeveelheid ruimte (in bytes) op die door een of meer items wordt gebruikt.
De getBytesInUse functie ziet er als volgt uit:
```
(keys?: string | string[], callback?: function) => {...}
```
- sleutels
  tekenreeks | tekenreeks[] optioneel
  Eén enkele sleutel of een lijst met sleutels om het totale gebruik te verkrijgen. Een lege lijst retourneert 0. Geef null door om het totale gebruik van alle opslagruimte te krijgen.
- terugbellen
  functie optioneel
  De callback parameter ziet er als volgt uit:
```
(bytesInUse: number) => void
```
  - bytesInUse
    nummer
    Hoeveelheid ruimte die wordt gebruikt in de opslag, in bytes.
- retourneert
  Beloof<nummer>
  Chroom 88+
  Beloften worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.
krijg sleutels
leegte
Belofte in behandeling
Haalt alle sleutels uit de opslag.
De getKeys functie ziet er als volgt uit:
```
(callback?: function) => {...}
```
- terugbellen
  functie optioneel
  De callback parameter ziet er als volgt uit:
```
(keys: string[]) => void
```
  - sleutels
    snaar[]
    Array met sleutels die uit de opslag worden gelezen.
- retourneert
  Beloof<string[]>
  Beloften worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.
verwijderen
leegte
Belofte
Verwijdert een of meer items uit de opslag.
De remove ziet er als volgt uit:
```
(keys: string | string[], callback?: function) => {...}
```
- sleutels
  tekenreeks | snaar[]
  Eén enkele sleutel of een lijst met sleutels voor items die moeten worden verwijderd.
- terugbellen
  functie optioneel
  De callback parameter ziet er als volgt uit:
```
() => void
```
- retourneert
  Beloof <nietig>
  Chroom 88+
  Beloften worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.
set
leegte
Belofte
Stelt meerdere items in.
De set functie ziet er als volgt uit:
```
(items: object, callback?: function) => {...}
```
- artikelen
  voorwerp
  Een object dat elk sleutel/waarde-paar geeft om de opslag mee bij te werken. Eventuele andere sleutel/waarde-paren in de opslag worden niet beïnvloed.
  Primitieve waarden zoals getallen worden zoals verwacht geserialiseerd. Waarden met het 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 parameter ziet er als volgt uit:
```
() => void
```
- retourneert
  Beloof <nietig>
  Chroom 88+
  Beloften worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.
stelToegangsniveau in
leegte
BeloofChrome 102+
Stelt het gewenste toegangsniveau voor de opslagruimte in. De standaardinstelling zijn alleen vertrouwde contexten.
De setAccessLevel functie ziet er als volgt uit:
```
(accessOptions: object, callback?: function) => {...}
```
- toegangOpties
  voorwerp
  - toegangsniveau
    Toegangsniveau
    Het toegangsniveau van de opslagruimte.
- terugbellen
  functie optioneel
  De callback parameter ziet er als volgt uit:
```
() => void
```
- retourneert
  Beloof <nietig>
  Beloften worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

StorageChange

Eigenschappen

nieuweWaarde
eventueel optioneel
De nieuwe waarde van het item, als er een nieuwe waarde is.
oude waarde
eventueel optioneel
De oude waarde van het artikel, als er een oude waarde was.

Eigenschappen

local

Items in het local opslaggebied zijn lokaal voor elke machine.

Type

Opslagruimte en object

Eigenschappen

QUOTA_BYTES
10485760
De maximale hoeveelheid gegevens (in bytes) die kan worden opgeslagen in de lokale opslag, zoals 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 machtiging unlimitedStorage heeft. Updates die ervoor zorgen 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; Als u deze naamruimte probeert te wijzigen, resulteert dit in een fout. Zie Manifest voor opslaggebieden voor informatie over het configureren van beleid.

Type

Opslagruimte

session

Chroom 102+ MV3+

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

Type

Opslagruimte en object

Eigenschappen

QUOTA_BYTES
10485760
De maximale hoeveelheid gegevens (in bytes) die in het geheugen kan worden opgeslagen, zoals gemeten door het schatten van het dynamisch toegewezen geheugengebruik van elke waarde en sleutel. Updates die ervoor zorgen dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer een belofte wordt afgewezen.

sync

Items in het sync worden gesynchroniseerd met Chrome Sync.

Type

Opslagruimte en object

Eigenschappen

MAX_ITEMS
512
Het maximale aantal items dat kan worden opgeslagen in synchronisatieopslag. Updates die ervoor zorgen dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer een belofte wordt afgewezen.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
Afgekeurd
De storage.sync API heeft niet langer een quotum voor duurzame schrijfbewerkingen.
MAX_WRITE_OPERATIONS_PER_HOUR
1800
Het maximale aantal set , remove of clear dat per uur kan worden uitgevoerd. Dit is 1 elke 2 seconden, een lager plafond dan de hogere schrijflimiet op korte termijn per minuut.
Updates die ervoor zorgen dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer een belofte wordt afgewezen.
MAX_WRITE_OPERATIONS_PER_MINUTE
120
Het maximale aantal set , remove of clear dat per minuut kan worden uitgevoerd. Dit is 2 per seconde, wat een hogere doorvoer oplevert dan het aantal schrijfbewerkingen per uur over een kortere periode.
Updates die ervoor zorgen dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer een belofte wordt afgewezen.
QUOTA_BYTES
102400
De maximale totale hoeveelheid gegevens (in bytes) die kan worden opgeslagen in synchronisatieopslag, zoals gemeten aan de hand van de JSON-stringificatie van elke waarde plus de lengte van elke sleutel. Updates die ervoor zorgen dat deze limiet wordt overschreden, mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer een belofte wordt afgewezen.
QUOTA_BYTES_PER_ITEM
8192
De maximale grootte (in bytes) van elk afzonderlijk item in gesynchroniseerde opslag, zoals gemeten door de JSON-stringificatie van de waarde plus de sleutellengte. Updates die items bevatten die groter zijn dan deze limiet mislukken onmiddellijk en stellen runtime.lastError in bij gebruik van een callback of wanneer een belofte wordt afgewezen.

Evenementen

onChanged

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

Wordt geactiveerd wanneer een of meer items veranderen.

Parameters

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