chrome.storage

Beschreibung

Mit der chrome.storage API können Sie Änderungen an Nutzerdaten speichern, abrufen und verfolgen.

Berechtigungen

storage

Deklariere die Berechtigung "storage" in der Erweiterung, um die Storage API zu verwenden manifest. Beispiel:

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

Konzepte und Verwendung

Die Storage API bietet eine erweiterungsspezifische Möglichkeit, Nutzerdaten und den Status zu speichern. Es ähnelt den Speicher-APIs der Webplattform (IndexedDB und Storage), wurde jedoch für die Speicheranforderungen von Erweiterungen entwickelt. Dies sind einige der wichtigsten Funktionen:

  • Alle Erweiterungskontexte, einschließlich des Erweiterungs-Service-Workers und der Inhaltsskripte, haben Zugriff auf die Storage API.
  • Die serialisierbaren JSON-Werte werden als Objektattribute gespeichert.
  • Die Storage API ist mit Lese- und Schreibvorgängen im Bulk asynchron.
  • Auch wenn der Nutzer den Cache leert und den Browserverlauf löscht, bleiben die Daten erhalten.
  • Gespeicherte Einstellungen bleiben auch dann erhalten, wenn Sie den Split-Inkognitomodus verwenden.
  • Enthält einen exklusiven schreibgeschützten verwalteten Speicherbereich für Unternehmensrichtlinien.

Können Erweiterungen Web Storage APIs verwenden?

Erweiterungen können zwar in einigen Kontexten (Pop-up- und andere HTML-Seiten) die Storage-Oberfläche (aufrufbar über window.localStorage) verwenden. Aus folgenden Gründen wird sie jedoch nicht empfohlen:

  • Erweiterungs-Service-Worker können die Web Storage API nicht verwenden.
  • Inhaltsskripte teilen sich den Speicherplatz mit der Hostseite.
  • Mit der Web Storage API gespeicherte Daten gehen verloren, wenn der Nutzer seinen Browserverlauf löscht.

So verschieben Sie Daten von einem Service Worker aus Web Storage APIs in Erweiterungsspeicher-APIs:

  1. Bereiten Sie eine nicht sichtbare HTML-Seite und eine Skriptdatei für das Dokument vor. Die Skriptdatei sollte eine Konvertierungsroutine und einen onMessage-Handler enthalten.
  2. Prüfen Sie im Erweiterungs-Service-Worker chrome.storage auf Ihre Daten.
  3. Wenn Ihre Daten nicht gefunden werden, rufen Sie createDocument() auf.
  4. Nachdem das zurückgegebene Promise aufgelöst wurde, rufen Sie sendMessage() auf, um den Conversion-Ablauf zu starten.
  5. Rufen Sie im onMessage-Handler des nicht sichtbaren Dokuments die Konvertierungsroutine auf.

Es gibt auch einige Unterschiede bei der Funktionsweise von Web Storage APIs in Erweiterungen. Weitere Informationen finden Sie in der Speicher und Cookies.

Lagerflächen

Die Storage API ist in folgende Speicherbereiche unterteilt:

storage.local
Die Daten werden lokal gespeichert und gelöscht, wenn die Erweiterung entfernt wird. Das Speicherlimit beträgt 10 MB (5 MB in Chrome 113 und niedriger), kann aber durch Anfordern der Berechtigung "unlimitedStorage" erhöht werden. Wir empfehlen die Verwendung von storage.local, um größere Datenmengen zu speichern.
storage.managed
Verwalteter Speicher ist schreibgeschützter Speicher für durch Richtlinien installierte Erweiterungen. Er wird von Systemadministratoren mithilfe eines vom Entwickler definierten Schemas und Unternehmensrichtlinien verwaltet. Richtlinien entsprechen den Optionen, werden jedoch von einem Systemadministrator und nicht vom Nutzer konfiguriert. Dadurch kann die Erweiterung für alle Nutzer einer Organisation vorkonfiguriert werden. Informationen zu Richtlinien finden Sie in der Dokumentation für Administratoren. Weitere Informationen zum Speicherbereich managed finden Sie unter Manifest für Speicherbereiche.
storage.session
Speichert Daten für die Dauer einer Browsersitzung. Standardmäßig ist sie nicht für Inhaltsskripte sichtbar. Dies kann jedoch durch Festlegen von chrome.storage.session.setAccessLevel() geändert werden. Das Speicherlimit beträgt 10 MB (1 MB in Chrome 111 und früheren Versionen). Die storage.session-Schnittstelle ist eine von mehreren, die wir Service Workern empfehlen.
storage.sync
Wenn die Synchronisierung aktiviert ist, werden die Daten mit jedem Chrome-Browser synchronisiert, in dem der Nutzer angemeldet ist. Wenn die Richtlinie deaktiviert ist, verhält sie sich wie storage.local. Chrome speichert die Daten lokal, wenn der Browser offline ist, und setzt die Synchronisierung fort, wenn er wieder online ist. Die Kontingentbeschränkung beträgt ungefähr 100 KB, 8 KB pro Element. Wir empfehlen, storage.sync zu verwenden, um die Nutzereinstellungen in allen synchronisierten Browsern beizubehalten. Wenn Sie mit vertraulichen Nutzerdaten arbeiten, verwenden Sie stattdessen storage.session.

Speicher- und Drosselungslimits

Für die Storage API gelten die folgenden Nutzungsbeschränkungen:

  • Das Speichern von Daten geht häufig mit Leistungskosten einher und die API umfasst Speicherkontingente. Wir empfehlen, darauf zu achten, welche Daten Sie speichern, damit Sie nicht den Zugriff darauf verlieren.
  • Der Speicher kann einige Zeit in Anspruch nehmen. Strukturieren Sie Ihren Code unbedingt entsprechend.

Weitere Informationen zu Einschränkungen von Speicherbereichen und dazu, was passiert, wenn sie überschritten werden, finden Sie in den Kontingentinformationen für sync, local und session.

Anwendungsfälle

In den folgenden Abschnitten werden häufige Anwendungsfälle für die Storage API beschrieben.

Synchrone Antwort auf Speicherupdates

Wenn Sie Änderungen am Speicher verfolgen möchten, fügen Sie dem zugehörigen onChanged-Ereignis einen Listener hinzu. Wenn sich der Speicherplatz ändert, wird dieses Ereignis ausgelöst. Der Beispielcode erfasst diese Änderungen:

background.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}".`
    );
  }
});

Wir können diese Idee noch weiterführen. In diesem Beispiel haben wir eine Optionsseite, ermöglicht es dem Nutzer, in einen „Debug-Modus“ Die Implementierung ist hier nicht zu sehen. Auf der Optionsseite werden die neuen Einstellungen sofort unter storage.sync gespeichert und der Service Worker verwendet storage.onChanged, um die Einstellung so schnell wie möglich anzuwenden.

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

options.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);

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

Asynchrones Vorabladen aus Speicher

Da Service Worker nicht immer ausgeführt werden, müssen Manifest V3-Erweiterungen manchmal asynchron Daten aus dem Speicher laden, bevor sie ihre Event-Handler ausführen. Zu diesem Zweck folgendes Snippet verwendet einen asynchronen action.onClicked-Event-Handler, der auf den storageCache wartet global verwendet werden soll, bevor die Logik ausgeführt wird.

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

Beispiele

In den folgenden Beispielen werden local, sync und session Speicherplatz:

Lokal

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

Synchronisieren

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

Sitzung

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

Weitere Demos der Storage API finden Sie in den folgenden Beispielen:

Typen

AccessLevel

Chrome 102 und höher

Die Zugriffsebene des Speicherbereichs.

Enum

"TRUSTED_CONTEXTS"
Gibt Kontexte an, die von der Erweiterung selbst stammen.

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
Gibt Kontexte an, die nicht von der Erweiterung stammen.

StorageArea

Attribute

  • onChanged

    Ereignis<functionvoidvoid>

    Chrome 73 und höher

    Wird ausgelöst, wenn sich mindestens ein Element ändert

    Die Funktion onChanged.addListener sieht so aus: 

    (callback: function) => {...}

    • callback

      Funktion

      Der Parameter callback sieht so aus: 

      (changes: object) => void

      • Änderungen

        Objekt

  • löschen

    voidm

    <ph type="x-smartling-placeholder"></ph> Versprechen

    Entfernt alle Elemente aus dem Speicher.

    Die Funktion clear sieht so aus: 

    (callback?: function) => {...}

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Chrome (ab Version 88)

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

  • get

    voidm

    <ph type="x-smartling-placeholder"></ph> Versprechen

    Ruft ein oder mehrere Elemente aus dem Speicher ab.

    Die Funktion get sieht so aus: 

    (keys?: string | string[] | object, callback?: function) => {...}

    • Schlüssel

      string | string[] | Objekt optional

      Ein einzelner abzurufender Schlüssel, eine Liste der abzurufenden Schlüssel oder ein Wörterbuch zum Festlegen von Standardwerten (siehe Beschreibung des Objekts). Bei einer leeren Liste oder einem leeren Objekt wird ein leeres Ergebnisobjekt zurückgegeben. Übergeben Sie null, um den gesamten Speicherplatz zu nutzen.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (items: object) => void

      • Artikel

        Objekt

        Objekt mit Elementen in ihren Schlüssel/Wert-Zuordnungen.

    • Gibt zurück

      Promise&lt;object&gt;

      Chrome (ab Version 88)

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

  • getBytesInUse

    voidm

    <ph type="x-smartling-placeholder"></ph> Versprechen

    Ruft den Speicherplatz (in Byte) ab, der von einem oder mehreren Elementen verwendet wird.

    Die Funktion getBytesInUse sieht so aus: 

    (keys?: string | string[], callback?: function) => {...}

    • Schlüssel

      string | string[] optional

      Ein einzelner Schlüssel oder eine Liste von Schlüsseln zum Abrufen der Gesamtnutzung. Bei einer leeren Liste wird „0“ zurückgegeben. Übergeben Sie null, um die Gesamtnutzung des Speicherplatzes zu erhalten.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (bytesInUse: number) => void

      • bytesInUse

        Zahl

        Menge des im Speicher verwendeten Speicherplatzes in Byte.

    • Gibt zurück

      Promise&lt;number&gt;

      Chrome (ab Version 88)

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

  • getKeys

    voidm

    <ph type="x-smartling-placeholder"></ph> Versprechen Ausstehend

    Ruft alle Schlüssel aus dem Speicher ab.

    Die Funktion getKeys sieht so aus: 

    (callback?: function) => {...}

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (keys: string[]) => void

      • Schlüssel

        String[]

        Array mit Schlüsseln, die aus dem Speicher gelesen werden.

    • Gibt zurück

      Promise&lt;string[]&gt;

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

  • Entfernen

    voidm

    <ph type="x-smartling-placeholder"></ph> Versprechen

    Entfernt ein oder mehrere Elemente aus dem Speicher.

    Die Funktion remove sieht so aus: 

    (keys: string | string[], callback?: function) => {...}

    • Schlüssel

      string | String[]

      Ein einzelner Schlüssel oder eine Liste von Schlüsseln für zu entfernende Elemente.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Chrome (ab Version 88)

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

  • set

    voidm

    <ph type="x-smartling-placeholder"></ph> Versprechen

    Legt mehrere Elemente fest.

    Die Funktion set sieht so aus: 

    (items: object, callback?: function) => {...}

    • Artikel

      Objekt

      Ein Objekt, das jedem Schlüssel/Wert-Paar zum Aktualisieren des Speichers zugeordnet ist. Alle anderen Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.

      Einfache Werte wie Zahlen werden wie erwartet serialisiert. Werte mit einem typeof "object" und "function" werden normalerweise in {} serialisiert, mit Ausnahme von Array (serialisiert wie erwartet), Date und Regex (Serialisierung mit ihrer String-Darstellung).

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Chrome (ab Version 88)

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

  • setAccessLevel

    voidm

    <ph type="x-smartling-placeholder"></ph> Versprechen Chrome 102 und höher

    Hier legen Sie die gewünschte Zugriffsebene für den Speicherbereich fest. Die Standardeinstellung sind nur vertrauenswürdige Kontexte.

    Die Funktion setAccessLevel sieht so aus: 

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      Objekt

      • accessLevel

        AccessLevel

        Die Zugriffsebene des Speicherbereichs.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

StorageChange

Attribute

  • newValue

    Beliebige optionale

    Der neue Wert des Elements, falls ein neuer Wert vorhanden ist.

  • oldValue

    Beliebige optionale

    Der alte Wert des Elements, falls ein alter Wert vorhanden war.

Attribute

local

Elemente im Speicherbereich „local“ werden auf jedem Computer lokal gespeichert.

Typ

StorageArea und Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Datenmenge (in Byte) an Daten, die im lokalen Speicher gespeichert werden können, gemessen durch die JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels. Dieser Wert wird ignoriert, wenn die Erweiterung die Berechtigung „unlimitedStorage“ hat. Updates, die dazu führen, dass dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird, oder ein abgelehntes Promise, wenn ein async- oder await-Tag verwendet wird.

managed

Die Elemente im Speicherbereich „managed“ werden durch eine vom Domainadministrator konfigurierte Unternehmensrichtlinie festgelegt und sind für die Erweiterung schreibgeschützt. wenn Sie versuchen, diesen Namespace zu ändern, führt dies zu einem Fehler. Informationen zum Konfigurieren einer Richtlinie finden Sie unter Manifest für Speicherbereiche.

Typ

StorageArea

session

Chrome 102 und höher MV3+

Elemente im Speicherbereich session werden im Arbeitsspeicher gespeichert und nicht auf dem Laufwerk gespeichert.

Typ

StorageArea und Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Datenmenge (in Byte) an Daten, die im Arbeitsspeicher gespeichert werden können, gemessen durch Schätzung der dynamisch zugewiesenen Arbeitsspeichernutzung jedes Werts und Schlüssels. Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

sync

Elemente im Speicherbereich „sync“ werden über die Chrome-Synchronisierung synchronisiert.

Typ

StorageArea und Objekt

Attribute

  • MAX_ITEMS

    512

    Die maximale Anzahl von Elementen, die im Synchronisierungsspeicher gespeichert werden können. Aktualisierungen, die dazu führen, dass dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1.000.000

    <ph type="x-smartling-placeholder"></ph> Eingestellt

    Für die storage.sync API gilt kein anhaltendes Kontingent für Schreibvorgänge mehr.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1.800

    Die maximale Anzahl von set-, remove- oder clear-Vorgängen, die pro Stunde ausgeführt werden können. Dies ist 1 alle 2 Sekunden, ein niedrigerer Höchstwert als der kurzfristig höhere Grenzwert für Schreibvorgänge pro Minute.

    Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Die maximale Anzahl von set-, remove- oder clear-Vorgängen, die pro Minute ausgeführt werden können. Dies sind 2 pro Sekunde, was einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum bietet.

    Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

  • QUOTA_BYTES

    102.400

    Die maximale Gesamtmenge (in Byte) an Daten, die im Synchronisierungsspeicher gespeichert werden kann, gemessen durch die JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels. Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

  • QUOTA_BYTES_PER_ITEM

    8192

    Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronisierungsspeicher, gemessen durch die JSON-Stringifizierung seines Werts plus seiner Schlüssellänge. Aktualisierungen mit Elementen, die dieses Limit überschreiten, schlagen sofort fehl und es wird runtime.lastError festgelegt, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

Ereignisse

onChanged

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

Wird ausgelöst, wenn sich mindestens ein Element ändert

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (changes: object, areaName: string) => void

    • Änderungen

      Objekt

    • areaName

      String