browser.storage

Beschreibung

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

Berechtigungen

storage

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

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

Beispiele

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

Beispiel (lokal)

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

Beispiel (Synchronisierung)

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

Beispiel (Sitzung)

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

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

Konzepte und Verwendung

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.

Können Erweiterungen Web Storage APIs verwenden?

Erweiterungen können in einigen Kontexten (Pop-up- und andere HTML-Seiten) die Schnittstelle Storage (zugänglich über window.localStorage) verwenden. Wir empfehlen dies jedoch aus folgenden Gründen nicht:

  • Erweiterungs-Service-Worker können die Web Storage API nicht verwenden.
  • Inhaltsskripts teilen sich den Speicher mit der Hostseite.
  • Daten, die mit der Web Storage API 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. Bereiten Sie eine HTML-Seite und eine Skriptdatei für das Offscreen-Dokument vor. Die Skriptdatei sollte eine Konvertierungsroutine und einen onMessage-Handler enthalten.
  2. Prüfen Sie im Service Worker der Erweiterung browser.storage auf Ihre Daten.
  3. Wenn deine Daten nicht gefunden werden, rufe createDocument() an.
  4. Nachdem das zurückgegebene Promise aufgelöst wurde, rufen Sie sendMessage() 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.

Speicher- und Drosselungslimits

Für die Storage API gelten Nutzungslimits:

  • Das Speichern von Daten hat Auswirkungen auf die Leistung und die API umfasst Speicherkontingente. Planen Sie, welche Daten Sie speichern möchten, um Speicherplatz zu sparen.
  • Das Speichern kann einige Zeit dauern. Strukturieren Sie Ihren Code so, dass diese Zeit berücksichtigt wird.

Weitere Informationen 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.

Lagerbereiche

Die Storage API ist in die folgenden Speicherbereiche unterteilt:

Lokal

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 früheren Versionen), kann aber durch Anfordern der Berechtigung "unlimitedStorage" erhöht werden. Wir empfehlen, storage.local zum Speichern größerer Datenmengen zu verwenden. Standardmäßig ist sie für Inhaltsskripts sichtbar, aber dieses Verhalten kann durch Aufrufen von browser.storage.local.setAccessLevel() geändert werden.

Verwaltet

Der verwaltete Speicher ist für Erweiterungen, die über Richtlinien installiert wurden, schreibgeschützt. Sie wird von Systemadministratoren mithilfe eines von Entwicklern definierten Schemas und von Unternehmensrichtlinien verwaltet. Richtlinien ähneln Optionen, werden aber von einem Systemadministrator und nicht vom Nutzer konfiguriert. So kann die Erweiterung für alle Nutzer einer Organisation vorkonfiguriert werden.

Standardmäßig ist storage.managed für Inhaltsskripts sichtbar. Dieses Verhalten kann jedoch durch Aufrufen von browser.storage.managed.setAccessLevel() geändert werden. Informationen zu Richtlinien finden Sie in der Dokumentation für Administratoren. Weitere Informationen zum Speicherbereich managed finden Sie unter Manifest für Speicherbereiche.

Sitzung

Im Sitzungsspeicher werden Daten im Arbeitsspeicher gespeichert, während eine Erweiterung geladen wird. Der Speicher wird gelöscht, wenn die Erweiterung deaktiviert, neu geladen oder aktualisiert wird und wenn der Browser neu gestartet wird. Standardmäßig wird sie nicht für Inhaltsskripts freigegeben. Dieses Verhalten kann jedoch durch Aufrufen von browser.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 für Service Worker empfehlen.

Synchronisieren

Wenn der Nutzer die Synchronisierung aktiviert, werden die Daten mit jedem Chrome-Browser synchronisiert, in dem er 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.

Wir empfehlen, storage.sync zu verwenden, um die Nutzereinstellungen in synchronisierten Browsern beizubehalten. Wenn Sie mit sensiblen Nutzerdaten arbeiten, verwenden Sie stattdessen storage.session. Standardmäßig ist storage.sync für Inhaltsskripts sichtbar. Dieses Verhalten kann jedoch durch Aufrufen von browser.storage.sync.setAccessLevel() geändert werden.

Methoden und Ereignisse

Alle Speicherbereiche implementieren die StorageArea-Schnittstelle.

get()

Mit der Methode get() können Sie einen oder mehrere Schlüssel aus einer StorageArea lesen.

getBytesInUse()

Mit der Methode getBytesInUse() können Sie das von einem StorageArea verwendete Kontingent aufrufen.

getKeys()

Mit der Methode getKeys() können Sie alle in einem StorageArea gespeicherten Schlüssel abrufen.

remove()

Mit der Methode remove() können Sie ein Element aus einem StorageArea entfernen.

set()

Mit der Methode set() können Sie ein Element in einem StorageArea festlegen.

setAccessLevel()

Mit der Methode setAccessLevel() können Sie den Zugriff auf eine StorageArea steuern.

clear()

Mit der Methode clear() können Sie alle Daten aus einem StorageArea löschen.

onChanged

Mit dem Ereignis onChanged können Sie Änderungen an einem StorageArea überwachen.

Anwendungsfälle

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

Auf Speicherplatzänderungen reagieren

Wenn Sie Änderungen am Speicher verfolgen möchten, fügen Sie dem onChanged-Ereignis einen Listener hinzu. Wenn sich etwas im Speicher ändert, wird dieses Ereignis ausgelöst. Der Beispielcode wartet auf die folgenden Änderungen:

background.js:

browser.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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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 ständig ausgeführt werden, müssen Manifest V3-Erweiterungen manchmal Daten asynchron 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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.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;
  browser.storage.sync.set(storageCache);
});

Entwicklertools

In den Entwicklertools können Sie die mit der API gespeicherten Daten ansehen und bearbeiten. Weitere Informationen finden Sie in der DevTools-Dokumentation auf der Seite Erweiterungsspeicher ansehen und bearbeiten.

Typen

AccessLevel

Chrome 102 und höher browser.* seit Chrome 148

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

session

Chrome 102 und höher browser.* seit Chrome 148 MV3 und höher

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

Typ

StorageArea und Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Datenmenge (in Byte), die im Arbeitsspeicher gespeichert werden kann. Sie wird durch Schätzung der dynamisch zugewiesenen Speichernutzung jedes Werts und Schlüssels gemessen. 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.

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

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