chrome.storage

Beschreibung

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

Berechtigungen

storage

Damit Sie die Storage API verwenden können, müssen Sie die Berechtigung "storage" im Manifest der Erweiterung deklarieren. Beispiel:

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

Konzepte und Nutzung

Die Storage API bietet eine erweiterungsspezifische Möglichkeit, Nutzerdaten und -status zu speichern. Sie ähnelt den Speicher-APIs der Webplattform (IndexedDB und Storage), wurde aber für die Speicheranforderungen von Erweiterungen entwickelt. Hier einige wichtige Funktionen:

  • Alle Erweiterungskontexte, einschließlich Extension Service Worker und Inhaltsskripts, haben Zugriff auf die Storage API.
  • Die seriellen JSON-Werte werden als Objekteigenschaften gespeichert.
  • Die Storage API ist asynchron mit Bulk-Lese- und Schreibvorgängen.
  • Auch wenn der Nutzer den Cache löscht und den Browserverlauf löscht, bleiben die Daten erhalten.
  • Gespeicherte Einstellungen bleiben auch bei Verwendung des aufgeteilten Inkognitomodus erhalten.
  • Enthält einen exklusiven schreibgeschützten verwalteten Speicherbereich für Unternehmensrichtlinien.

Können Erweiterungen Webspeicher-APIs verwenden?

Erweiterungen können die Storage-Oberfläche verwenden, auf die über window.localStorage zugegriffen werden kann. In einigen Kontexten (Pop-ups und andere HTML-Seiten) wird sie jedoch aus folgenden Gründen nicht empfohlen:

  • Erweiterungsdienst-Worker können die Web Storage API nicht verwenden.
  • Inhaltsscripts teilen 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 HTML-Seite und eine Skriptdatei für ein nicht sichtbares Dokument vor. Die Skriptdatei sollte eine Konvertierungsroutine und einen onMessage-Handler enthalten.
  2. Prüfen Sie im Service Worker der Erweiterung chrome.storage auf Ihre Daten.
  3. Wenn Ihre Daten nicht gefunden werden, rufen Sie createDocument() an.
  4. Nachdem das zurückgegebene Versprechen aufgelöst wurde, rufen Sie sendMessage() auf, um die Conversion-Routine zu starten.
  5. Rufen Sie im Handler onMessage des nicht sichtbaren Dokuments die Konvertierungsroutine auf.

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

Lagerbereiche

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). Sie können es aber erhöhen, indem Sie die Berechtigung "unlimitedStorage" anfordern. Zum Speichern größerer Datenmengen empfehlen wir die Verwendung von storage.local.
storage.managed
Verwalteter Speicher ist ein schreibgeschützter Speicher für Erweiterungen, die nach Richtlinien installiert sind. Er wird von Systemadministratoren mithilfe eines vom Entwickler definierten Schemas und von Unternehmensrichtlinien verwaltet. Richtlinien entsprechen den Optionen, werden aber nicht vom Nutzer, sondern von einem Systemadministrator 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 im Arbeitsspeicher. Standardmäßig ist sie nicht für Inhaltsskripte verfügbar. Sie können dieses Verhalten jedoch ändern, indem Sie chrome.storage.session.setAccessLevel() festlegen. Das Speicherlimit beträgt 10 MB (1 MB in Chrome 111 und niedriger). Die Schnittstelle storage.session ist eine von mehreren, die wir für Service Worker empfehlen.
storage.sync
Wenn die Synchronisierung aktiviert ist, werden die Daten mit jedem Chrome-Browser synchronisiert, in dem der Nutzer angemeldet ist. Wenn sie 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 die Verwendung von storage.sync, damit die Nutzereinstellungen in allen synchronisierten Browsern erhalten bleiben. 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 ist häufig mit Leistungskosten verbunden und die API beinhaltet Speicherkontingente. Wir empfehlen Ihnen, bei der Speicherung Ihrer Daten vorsichtig zu sein, damit Sie nicht die Möglichkeit verlieren, Daten zu speichern.
  • Der Speicher kann einige Zeit in Anspruch nehmen. Strukturieren Sie Ihren Code so, dass diese Zeit berücksichtigt wird.

Weitere Informationen zu Speicherbeschränkungen und was bei deren Überschreitung passiert, 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

Fügen Sie dem onChanged-Ereignis einen Listener hinzu, um Änderungen am Speicher zu verfolgen. Wenn sich der Speicher ändert, wird dieses Ereignis ausgelöst. Der Beispielcode überwacht 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}".`
    );
  }
});

Mit dieser Idee können wir noch einen Schritt weitergehen. In diesem Beispiel haben wir eine Seite mit Optionen, auf der der Nutzer in den Debug-Modus umschalten kann. Die Implementierung ist hier nicht aufgeführt. Auf der Seite „Optionen“ werden die neuen Einstellungen sofort in storage.sync gespeichert. 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 dem Speicher

Da Service Worker nicht immer ausgeführt werden, müssen Manifest V3-Erweiterungen manchmal Daten asynchron aus dem Speicher laden, bevor sie ihre Event-Handler ausführen. Dazu verwendet das folgende Snippet einen asynchronen Event-Handler action.onClicked, der auf das Ausfüllen des globalen storageCache-Elements wartet, bevor seine 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 die Speicherbereiche local, sync und session veranschaulicht:

Lokale Kampagnen

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 aus der Erweiterung selbst stammen.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Gibt Kontexte an, die von außerhalb 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

    void

    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

      Promise<void>

      Chrome 88 und höher

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • get

    void

    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[]|object optional

      Ein einzelner abzurufender Schlüssel, eine Liste der abzurufenden Schlüssel oder ein Wörterbuch mit Standardwerten (siehe Beschreibung des Objekts). Bei einer leeren Liste oder einem leeren Objekt wird ein leeres Ergebnisobjekt zurückgegeben. Übergeben Sie null für den gesamten Speicherinhalt.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (items: object)=>void

      • items

        Objekt

        Objekt mit Elementen in den zugehörigen Schlüssel/Wert-Paar-Zuordnungen.

    • Gibt zurück

      Promise<object>

      Chrome 88 und höher

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • getBytesInUse

    void

    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, für die die Gesamtnutzung abgerufen werden soll. Bei einer leeren Liste wird 0 zurückgegeben. Wenn Sie null übergeben, erhalten Sie die Gesamtnutzung des gesamten Speicherplatzes.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (bytesInUse: number)=>void

      • bytesInUse

        Zahl

        Im Speicher verwendeter Speicherplatz in Byte.

    • Gibt zurück

      Versprechen<Zahl>

      Chrome 88 und höher

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • entfernen

    void

    Versprechen

    Entfernt mindestens ein Element aus dem Speicher.

    Die Funktion remove sieht so aus: 

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

    • Schlüssel

      Zeichenfolge|Zeichenfolge[]

      Ein einzelner Schlüssel oder eine Liste von Schlüsseln für Elemente, die entfernt werden sollen.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      ()=>void

    • Gibt zurück

      Promise<void>

      Chrome 88 und höher

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • set

    void

    Versprechen

    Legt mehrere Elemente fest.

    Die Funktion set sieht so aus: 

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

    • items

      Objekt

      Ein Objekt, das jedem Schlüssel/Wert-Paar für die Speicheraktualisierung zuweist. Andere Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.

      Primitive Werte wie Zahlen werden wie erwartet priorisiert. Werte mit einem typeof-"object" und einem "function"-Wert werden in der Regel als {} mit Ausnahme von Array (erwartet) und Regex (serialisiert mit der String-Darstellung) verwendet.Date

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      ()=>void

    • Gibt zurück

      Promise<void>

      Chrome 88 und höher

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • setAccessLevel

    void

    Versprechen Chrome 102 oder höher

    Legt die gewünschte Zugriffsebene für den Speicherbereich fest. Standardmäßig sind nur vertrauenswürdige Kontexte ausgewählt.

    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

      Promise<void>

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

StorageChange

Attribute

  • newValue

    Beliebig optional

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

  • oldValue

    Beliebig optional

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

Attribute

local

Inhalte im Speicherbereich „local“ sind auf jedem Computer lokal gespeichert.

Typ

StorageArea&Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Menge (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. Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen runtime.lastError fest, wenn Sie einen Callback verwenden, oder ein abgelehntes Promise, wenn Sie „async/await“ verwenden.

managed

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

Typ

StorageArea

session

Chrome 102+ MV3+

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

Typ

StorageArea&Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Menge (in Byte) an Daten, die im Speicher gespeichert werden können, gemessen durch Schätzung der dynamisch zugewiesenen Speichernutzung jedes Werts und Schlüssels. Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird.

sync

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

Typ

StorageArea&Objekt

Attribute

  • MAX_ITEMS

    512

    Die maximale Anzahl der Elemente, die im Synchronisierungsspeicher gespeichert werden können. Aktualisierungen, die zu einer Überschreitung dieses Limits führen würden, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1.000.000

    Eingestellt

    Die Storage.sync API hat kein Kontingent für kontinuierliche 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 ein Wert von „1“ alle 2 Sekunden, eine Untergrenze als das kurzzeitig höhere Limit für Schreibvorgänge pro Minute.

    Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder ein Promise-Objekt 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 entspricht 2 pro Sekunde und bietet einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum.

    Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder ein Promise-Objekt 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, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird.

  • QUOTA_BYTES_PER_ITEM

    8.192

    Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronisierungsspeicher, gemessen anhand der JSON-Stringisierung seines Werts plus seiner Schlüssellänge. Updates mit Artikeln, die dieses Limit überschreiten, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird.

Veranstaltungen

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