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:

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

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.

Let op: vóór Chrome 114 bedroeg het quotum ongeveer 5 MB.

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.

Waarschuwing: vóór Chrome 112 bedroeg het quotum ongeveer 1 MB.

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:

• Globale zoekextensie .
• Uitbreiding wateralarm .

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