chrome.storage

refresh date: 2026-09-25 robots: noindex

Beschreibung

Verwenden Sie die chrome.storage API, um Änderungen an Nutzerdaten zu speichern, abzurufen und zu verfolgen.

Berechtigungen

storage

Übersicht

Die Storage API bietet eine erweiterungsspezifische Möglichkeit, Nutzerdaten und ‑status beizubehalten. Sie ähnelt den Storage APIs der Webplattform (IndexedDB und Storage), wurde aber speziell für die Speicheranforderungen von Erweiterungen entwickelt. Hier sind einige der wichtigsten Funktionen:

  • Alle Erweiterungskontexte, einschließlich des Service Workers der Erweiterung und der Inhaltsskripts, haben Zugriff auf die Storage API.
  • Die JSON-serialisierbaren Werte werden als Objekteigenschaften gespeichert.
  • Die Storage API ist asynchron und unterstützt Bulk-Lese- und Schreibvorgänge.
  • Die Daten bleiben auch dann erhalten, wenn der Nutzer den Cache und den Browserverlauf leert.
  • Gespeicherte Einstellungen bleiben auch bei Verwendung des geteilten Inkognitomodus erhalten.
  • Enthält einen exklusiven verwalteten Speicherbereich mit Lesezugriff für Unternehmensrichtlinien.

Erweiterungen können zwar in einigen Kontexten (Pop-up- und andere HTML-Seiten) die Schnittstelle [Storage][mdn-storage] (zugänglich über window.localStorage) verwenden, dies wird jedoch aus folgenden Gründen nicht empfohlen:

  • Der Service Worker der Erweiterung kann nicht auf Storage zugreifen.
  • Inhaltsskripts teilen sich den Speicher mit der Hostseite.
  • Daten, die über die Storage-Schnittstelle gespeichert wurden, gehen verloren, wenn der Nutzer seinen Browserverlauf löscht.

So verschieben Sie Daten von Web Storage APIs zu Erweiterungs-Storage APIs über einen Service Worker:

  1. Erstellen Sie ein Offscreen-Dokument mit einer Konvertierungsroutine und einem [onMessage][on-message]-Handler.
  2. Fügen Sie einem Offscreen-Dokument eine Konvertierungsroutine hinzu.
  3. Prüfen Sie im Service Worker der Erweiterung, ob Ihre Daten unter chrome.storage vorhanden sind.
  4. Wenn Ihre Daten nicht gefunden werden, [erstellen Sie ein Offscreen-Dokument][create-offscreen] und rufen Sie [sendMessage()][send-message] auf, um die Konvertierungsroutine zu starten.
  5. Rufen Sie im onMessage-Handler des Offscreen-Dokuments die Konvertierungsroutine auf.

Es gibt auch einige Besonderheiten bei der Funktionsweise von Web Storage APIs in Erweiterungen. Weitere Informationen finden Sie im Artikel [Speicher und Cookies][storage-and-cookies].

Lagerbereiche

Die Storage API ist in die folgenden vier Buckets („Speicherbereiche“) unterteilt:

storage.local
Die Daten werden lokal gespeichert und gelöscht, wenn die Erweiterung entfernt wird. Das Kontingentlimit liegt bei etwa 10 MB, kann aber durch Anfordern der Berechtigung "unlimitedStorage" erhöht werden. Sie können damit größere Datenmengen speichern.
storage.sync
Wenn die Synchronisierung aktiviert ist, werden die Daten mit allen Chrome-Browsern synchronisiert, in denen 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, sobald er wieder online ist. Das Kontingentlimit beträgt etwa 100 KB, 8 KB pro Element. Sie können damit Nutzereinstellungen in synchronisierten Browsern beibehalten.
storage.session
Speichert Daten für die Dauer einer Browsersitzung im Arbeitsspeicher. Standardmäßig wird sie nicht für Inhaltsskripts freigegeben. Dieses Verhalten kann jedoch durch Festlegen von chrome.storage.session.setAccessLevel() geändert werden. Das Kontingentlimit beträgt etwa 10 MB. Sie können damit globale Variablen über Service Worker-Ausführungen hinweg speichern.
storage.managed
Administratoren können ein Schema und Unternehmensrichtlinien verwenden, um die Einstellungen einer unterstützenden Erweiterung in einer verwalteten Umgebung zu konfigurieren. Dieser Speicherbereich ist schreibgeschützt.

Manifest

Wenn Sie die Storage API verwenden möchten, deklarieren Sie die Berechtigung "storage" im Manifest der Erweiterung. Beispiel:

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

Nutzung

Die folgenden Beispiele zeigen die Speicherbereiche local, sync und session:

storage.local

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

storage.sync

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

storage.session

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

Weitere Informationen zum Speicherbereich managed finden Sie unter Manifest für Speicherbereiche.

Speicher- und Drosselungslimits

Stellen Sie sich das Hinzufügen von Daten zur Storage API nicht so vor, als würden Sie Dinge in einen großen Lkw laden. Stellen Sie sich das Hinzufügen von Daten zum Speicher so vor, als würden Sie etwas in ein Rohr legen. Das Rohr enthält möglicherweise bereits Material und ist vielleicht sogar gefüllt. Gehen Sie immer davon aus, dass zwischen dem Hinzufügen zum Speicher und der tatsächlichen Aufzeichnung eine Verzögerung auftritt.

Details zu den Einschränkungen für Speicherbereiche 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 gängige Anwendungsfälle für die Storage API beschrieben.

Synchrone Antwort auf Speicheraktualisierungen

Wenn Sie Änderungen am Speicher verfolgen möchten, können Sie einen Listener für das onChanged-Ereignis hinzufügen. Wenn sich etwas im Speicher ändert, wird dieses Ereignis ausgelöst. Der Beispielcode wartet auf die folgenden Ä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 weiter ausbauen. In diesem Beispiel haben wir eine Optionsseite, auf der der Nutzer einen „Debug-Modus“ aktivieren kann (Implementierung hier nicht gezeigt). Auf der Optionsseite 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 asynchron Daten aus dem Speicher laden, bevor sie ihre Event-Handler ausführen. Dazu wird im folgenden Snippet ein asynchroner action.onClicked-Ereignis-Handler verwendet, der wartet, bis die globale storageCache-Variable ausgefüllt ist, 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 für Erweiterungen

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

Typen

AccessLevel

Chrome 102 oder höher

Die Zugriffsebene des Speicherbereichs.

Enum

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

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Gibt Kontexte an, die von außerhalb der Erweiterung stammen.

StorageChange

Attribute

  • newValue

    any optional

    Der neue Wert des Elements, falls vorhanden.

  • oldValue

    any optional

    Der alte Wert des Elements, falls vorhanden.

Attribute

local

Elemente im Speicherbereich local sind lokal auf jedem Computer gespeichert.

Typ

StorageArea und Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Datenmenge (in Byte), die im lokalen Speicher gespeichert werden kann, gemessen anhand der JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels. Dieser Wert wird ignoriert, wenn die Erweiterung die Berechtigung unlimitedStorage hat. Aktualisierungen, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl. Bei Verwendung eines Callbacks wird runtime.lastError festgelegt, bei Verwendung von async/await wird ein abgelehnter Promise zurückgegeben.

managed

Elemente im Speicherbereich managed werden durch eine vom Domainadministrator konfigurierte Unternehmensrichtlinie festgelegt und haben für die Erweiterung Lesezugriff. 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

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 würden, dass dieses Limit überschritten wird, schlagen sofort fehl. Wenn ein Callback verwendet wird oder ein Promise abgelehnt wird, wird runtime.lastError festgelegt.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Eingestellt

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

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    Die maximale Anzahl von set-, remove- oder clear-Vorgängen, die pro Stunde ausgeführt werden können. Das entspricht einer Anfrage alle 2 Sekunden und ist ein niedrigerer Grenzwert als das kurzfristige höhere Limit für Schreibvorgänge pro Minute.

    Aktualisierungen, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl. Wenn ein Callback verwendet wird oder ein Promise abgelehnt wird, wird runtime.lastError festgelegt.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

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

    Aktualisierungen, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl. Wenn ein Callback verwendet wird oder ein Promise abgelehnt wird, wird runtime.lastError festgelegt.

  • QUOTA_BYTES

    102400

    Die maximale Gesamtmenge (in Byte) an Daten, die im synchronisierten Speicher gespeichert werden können, gemessen anhand der JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels. Aktualisierungen, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl. Wenn ein Callback verwendet wird oder ein Promise abgelehnt wird, wird runtime.lastError festgelegt.

  • QUOTA_BYTES_PER_ITEM

    8192

    Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronisierungsspeicher, gemessen an der JSON-Stringifizierung seines Werts plus seiner Schlüssellänge. Aktualisierungen, die Elemente enthalten, die dieses Limit überschreiten, schlagen sofort fehl. Bei Verwendung eines Callbacks wird runtime.lastError festgelegt oder ein Promise wird abgelehnt.

Ereignisse

onChanged

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

Wird ausgelöst, wenn sich ein oder mehrere Elemente ändern.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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

    • Änderungen

      Objekt

    • areaName

      String