chroom.opslag

Beschrijving

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

Machtigingen

storage

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

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

Concepten en gebruik

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.

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 we dit om de volgende redenen niet aan:

  • Extensieservicemedewerkers kunnen de Web Storage API niet gebruiken.
  • Inhoudsscripts delen opslag met de hostpagina.
  • Gegevens die zijn opgeslagen met behulp van de Web Storage API gaan verloren wanneer de gebruiker zijn browsegeschiedenis wist.

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

  1. Bereid een html-pagina voor een offscreen document en een scriptbestand voor. Het scriptbestand moet een conversieroutine en een onMessage handler bevatten.
  2. Controleer in de extensieservicemedewerker chrome.storage op uw gegevens.
  3. Als uw gegevens niet worden gevonden, roept u createDocument() aan.
  4. Nadat de geretourneerde belofte is opgelost, roept u sendMessage() 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 .

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 eerder), maar kan worden verhoogd door de toestemming "unlimitedStorage" aan te vragen. We raden u aan storage.local te gebruiken om grotere hoeveelheden gegevens op te slaan.
storage.managed
Beheerde opslag is alleen-lezen opslag voor op beleid geïnstalleerde extensies en wordt beheerd door systeembeheerders met behulp van een door de ontwikkelaar gedefinieerd schema en bedrijfsbeleid. Beleid is analoog aan 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. Zie Documentatie voor beheerders voor informatie over beleid. Zie Manifest voor opslagruimten voor meer informatie over het managed opslaggebied.
storage.session
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 opslaglimiet is 10 MB (1 MB in Chrome 111 en eerder). De storage.session interface is een van de vele die we aanbevelen voor servicemedewerkers .
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. We raden u aan storage.sync te gebruiken om gebruikersinstellingen in gesynchroniseerde browsers te behouden. Als u met gevoelige gebruikersgegevens werkt, gebruikt u in plaats daarvan storage.session .

Opslag- en beperkingslimieten

De Storage API heeft de volgende gebruiksbeperkingen:

  • Het opslaan van gegevens gaat vaak gepaard met prestatiekosten, en de API omvat opslagquota. We raden u aan voorzichtig te zijn met de gegevens die u opslaat, zodat u de mogelijkheid om gegevens op te slaan niet verliest.
  • Het kan enige tijd duren voordat de opslag is voltooid. Zorg ervoor dat u uw code zo structureert dat u rekening houdt met die tijd.

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, voegt u een luisteraar toe 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 servicewerknemers niet de hele tijd 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

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

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 ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

  • 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 ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

  • 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 ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

  • krijg sleutels

    leegte

    BeloofChrome 130+

    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 ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

  • 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 ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

  • 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. 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 ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

  • 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 ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

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 tijdsperiode.

    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