Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

chrome.storage

Beschreibung

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

Berechtigungen

storage

Wenn Sie die Storage API verwenden möchten, deklarieren Sie die "storage" Berechtigung im Erweiterungs manifest. Beispiel:

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

Beispiele

In den folgenden Beispielen werden die Speicherbereiche local, sync und session veranschaulicht:

Beispiel (lokal)

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

Beispiel (Synchronisierung)

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

Beispiel (Sitzung)

await chrome.storage.session.set({ key: value });
console.log("Value is set");
const result = await chrome.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 für die Speicheranforderungen von Erweiterungen entwickelt. Hier sind einige wichtige Funktionen:

Alle Erweiterungskontexte, einschließlich des Erweiterungs-Service-Workers und der Inhaltsskripts, haben Zugriff auf die Storage API.
Die JSON-serialisierbaren Werte werden als Objekteigenschaften gespeichert.
Die Storage API ist asynchron und bietet Bulk-Lese- und ‑Schreibvorgänge.
Die Daten bleiben auch dann erhalten, wenn der Nutzer den Cache und den Browserverlauf löscht.
Gespeicherte Einstellungen bleiben auch bei der geteilten Inkognitonutzung erhalten.
Enthält einen exklusiven schreibgeschützten verwalteten Speicherbereich für Unternehmensrichtlinien.

Können Erweiterungen Web Storage APIs verwenden?

Erweiterungen können die Storage-Schnittstelle (über window.localStorage zugänglich) in einigen Kontexten (Pop-up-Fenster und andere HTML-Seiten) 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 den Browserverlauf löscht.

So verschieben Sie Daten von Web Storage APIs zu Erweiterungs-Storage APIs aus einem Service-Worker:

Bereiten Sie eine HTML-Seite und eine Skriptdatei für ein Offscreen-Dokument vor. Die Skriptdatei sollte eine Konvertierungsroutine und einen onMessage-Handler enthalten.
Prüfen Sie im Erweiterungs-Service-Worker, ob Ihre Daten in chrome.storage vorhanden sind.
Wenn Ihre Daten nicht gefunden werden, rufen Sie createDocument() auf.
Nachdem das zurückgegebene Promise aufgelöst wurde, rufen Sie sendMessage() auf, um die Konvertierungsroutine zu starten.
Rufen Sie im onMessage-Handler des Offscreen-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.

Speicher- und Drosselungslimits

Für die Storage API gelten Nutzungsbeschränkungen:

Das Speichern von Daten verursacht Leistungskosten und die API umfasst Speicherkontingente. Planen Sie die Daten, die Sie speichern möchten, damit Sie Speicherplatz freihalten.
Das Speichern kann einige Zeit dauern. Strukturieren Sie Ihren Code so, dass diese Zeit berücksichtigt wird.

Details zu den Einschränkungen des Speicherbereichs und den Folgen bei Überschreitung finden Sie in den Kontingentinformationen für sync, local und session.

Speicherbereiche

Die Storage API ist in die folgenden Speicherbereiche unterteilt:

Lokal

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üher), kann aber durch Anfordern der Berechtigung "unlimitedStorage" erhöht werden. Wir empfehlen, storage.local zum Speichern größerer Datenmengen zu verwenden. Standardmäßig ist es für Inhaltsskripts verfügbar. Dieses Verhalten kann jedoch durch Aufrufen von chrome.storage.local.setAccessLevel() geändert werden.

Verwaltet

Verwalteter Speicher ist für über Richtlinien installierte Erweiterungen schreibgeschützt. Er wird von Systemadministratoren mit einem vom Entwickler definierten Schema und 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 verfügbar. Dieses Verhalten kann jedoch durch Aufrufen von chrome.storage.managed.setAccessLevel() geändert werden. Informationen zu Richtlinien finden Sie in der Dokumentation für Administratoren. Weitere Informationen zum managed Speicherbereich 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 ist er für Inhaltsskripts nicht verfügbar. Dieses Verhalten kann jedoch durch Aufrufen von chrome.storage.session.setAccessLevel() geändert werden. Das Speicherlimit beträgt 10 MB (1 MB in Chrome 111 und früher).

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 allen Chrome-Browsern synchronisiert, in denen er angemeldet ist. Wenn die Synchronisierung 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. Das Kontingentlimit beträgt etwa 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. Standardmäßig ist storage.sync für Inhaltsskripts verfügbar. Dieses Verhalten kann jedoch durch Aufrufen von chrome.storage.sync.setAccessLevel() geändert werden.

Methoden und Ereignisse

Alle Speicherbereiche implementieren die StorageArea-Schnittstelle.

get()

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

getBytesInUse()

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

getKeys()

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

remove()

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

set()

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

setAccessLevel()

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

clear()

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

onChanged

Mit dem onChanged-Ereignis können Sie Änderungen an einem StorageArea-Objekt verfolgen.

Anwendungsfälle

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

Auf Speicheraktualisierungen reagieren

Wenn Sie Änderungen am Speicher verfolgen möchten, fügen Sie dem Ereignis onChanged einen Listener hinzu. Dieses Ereignis wird ausgelöst, wenn sich etwas im Speicher ändert. 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}".`
    );
  }
});

Wir können diese Idee noch weiter ausbauen. In diesem Beispiel haben wir eine Optionsseite, auf der der Nutzer einen Debug-Modus aktivieren oder deaktivieren kann (Implementierung hier nicht gezeigt). Auf der Optionsseite werden die neuen Einstellungen sofort in 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 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 Ereignishandler ausführen. Dazu verwendet der folgende Code-Snippet einen asynchronen action.onClicked-Event-Handler, der wartet, bis die globale Variable storageCache gefüllt ist, bevor er seine Logik ausführt.

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

DevTools

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

Typen

AccessLevel

Chrome 102+

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

Properties

newValue

Optional

Der neue Wert des Elements, falls vorhanden.
oldValue

Optional

Der alte Wert des Elements, falls vorhanden.

Properties

local

Elemente im Speicherbereich local sind lokal für jeden Computer.

Typ

StorageArea & object

Properties

QUOTA_BYTES

10485760

Die maximale Datenmenge (in Byte), die im lokalen Speicher gespeichert werden kann. Sie wird anhand der JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels gemessen. 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 und legen runtime.lastError fest, wenn ein Callback verwendet wird, oder ein abgelehntes Promise, wenn async/await verwendet wird.

managed

Elemente im Speicherbereich managed werden durch eine Unternehmensrichtlinie festgelegt, die vom Domainadministrator konfiguriert wird, und sind für die Erweiterung schreibgeschützt. Wenn Sie versuchen, diesen Namespace zu ändern, tritt ein Fehler auf. 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 beibehalten.

Typ

StorageArea & object

Properties

QUOTA_BYTES

10485760

Die maximale Datenmenge (in Byte), die im Arbeitsspeicher gespeichert werden kann. Sie wird geschätzt, indem die dynamisch zugewiesene Arbeitsspeichernutzung jedes Werts und Schlüssels gemessen wird. Aktualisierungen, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder wenn ein Promise abgelehnt wird.

sync

Elemente im Speicherbereich sync werden mit der Chrome-Synchronisierung synchronisiert.

Typ

StorageArea & object

Properties

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 und legen runtime.lastError fest, wenn ein Callback verwendet wird oder wenn ein Promise abgelehnt wird.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1000000

Eingestellt

Für die storage.sync API gilt kein Kontingent für anhaltende 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 einem Vorgang alle zwei Sekunden und ist damit niedriger als das kurzfristige Limit für Schreibvorgänge pro Minute.

Aktualisierungen, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder wenn 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. Das entspricht zwei Vorgängen pro Sekunde und bietet einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum.

Aktualisierungen, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder wenn ein Promise abgelehnt wird.
QUOTA_BYTES

102400

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

8192

Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronisierungsspeicher. Sie wird anhand der JSON-Stringifizierung des Werts plus der Länge des Schlüssels gemessen. Aktualisierungen, die Elemente enthalten, die größer als dieses Limit sind, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird oder wenn ein Promise abgelehnt wird.

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

chrome.storage Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Beschreibung

Berechtigungen

Beispiele

Beispiel (lokal)

Beispiel (Synchronisierung)

Beispiel (Sitzung)

Konzepte und Verwendung

Können Erweiterungen Web Storage APIs verwenden?

Speicher- und Drosselungslimits

Speicherbereiche

Lokal

Verwaltet

Sitzung

Synchronisieren

Methoden und Ereignisse

get()

getBytesInUse()

getKeys()

remove()

set()

setAccessLevel()

clear()

onChanged

Anwendungsfälle

Auf Speicheraktualisierungen reagieren

Asynchrones Vorabladen aus dem Speicher

DevTools

Typen

AccessLevel

Enum

StorageChange

Properties

Properties

local

Typ

Properties

managed

Typ

session

Typ

Properties

sync

Typ

Properties

Ereignisse

onChanged

Parameter

chrome.storage