Diese Seite wurde von der Cloud Translation API übersetzt.

chrome.storage

Beschreibung

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

Berechtigungen

storage

Übersicht

Die Storage API bietet eine extensionspezifische Möglichkeit, Nutzerdaten und den Status beizubehalten. Sie ähnelt den Speicher-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 Service Workers und der Inhaltskripte der Erweiterung, 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 löscht.
Gespeicherte Einstellungen bleiben auch bei Verwendung von geteiltem Inkognito erhalten.
Enthält einen exklusiven schreibgeschützten verwalteten Speicherbereich für Unternehmensrichtlinien.

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

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

So übertragen Sie Daten aus Web Storage APIs in Erweiterungsspeicher-APIs über einen Service Worker:

Erstellen Sie ein Offscreen-Dokument mit einer Conversion-Routine und einem [onMessage][on-message]-Handler.
Einem Offscreen-Dokument eine Conversion-Routine hinzufügen
Suchen Sie im Service Worker der Erweiterung nach chrome.storage, um Ihre Daten zu finden.
Wenn Ihre Daten nicht gefunden werden, [erstellen Sie][create-offscreen] ein Offscreen-Dokument und rufen Sie [sendMessage()][send-message] auf, um die Konvertierungsroutine zu starten.
Rufen Sie die Conversion-Routine im onMessage-Handler des Offscreen-Dokuments 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 Bereiche unterteilt:

storage.local: Daten werden lokal gespeichert und gelöscht, wenn die Erweiterung entfernt wird. Das Kontingentlimit beträgt etwa 10 MB, kann aber durch Anfordern der Berechtigung "unlimitedStorage" erhöht werden. Erwägen Sie die Verwendung zum Speichern größerer Datenmengen.

storage.sync: Wenn die Synchronisierung aktiviert ist, werden die Daten mit allen Chrome-Browsern synchronisiert, in denen der Nutzer angemeldet ist. Wenn die Funktion 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. Die Kontingentbeschränkung beträgt etwa 100 KB, also 8 KB pro Element. Sie können damit Nutzereinstellungen in synchronisierten Browsern beibehalten.

Warnung:Lokale und synchronisierte Speicherbereiche sollten keine vertraulichen Nutzerdaten enthalten, da sie nicht verschlüsselt sind. Wenn Sie mit sensiblen Daten arbeiten, sollten Sie den Speicherbereich session verwenden, um Werte im Arbeitsspeicher zu speichern, bis der Browser geschlossen wird.

storage.session: Speichert Daten für die Dauer einer Browsersitzung im Arbeitsspeicher. Standardmäßig ist sie für Inhaltsskripts nicht verfügbar. Dieses Verhalten kann jedoch durch Festlegen von chrome.storage.session.setAccessLevel() geändert werden. Die Kontingentbeschränkung beträgt etwa 10 MB. Sie können damit globale Variablen über mehrere 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, müssen Sie die Berechtigung "storage" im Manifest der Erweiterung deklarieren. 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 managed-Speicherbereich finden Sie unter Manifest für Speicherbereiche.

Speicher- und Drosselungslimits

Stellen Sie sich das Hinzufügen zur Storage API nicht so vor, als würden Sie Dinge in einen großen LKW packen. Stellen Sie sich das Hinzufügen von Daten zum Speicher wie das Einfüllen von etwas in ein Rohr vor. Das Rohr kann bereits Material enthalten und sogar gefüllt sein. Gehen Sie immer davon aus, dass es eine Verzögerung zwischen dem Hinzufügen von Daten zum Speicher und der tatsächlichen Aufzeichnung gibt.

Details zu Einschränkungen des Speicherbereichs und dazu, was passiert, wenn diese ü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 Reaktion auf Speicheraktualisierungen

Wenn Sie Änderungen am Speicher erfassen 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 reagiert auf 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 kann (Implementierung hier nicht gezeigt). Auf der Seite mit den Optionen 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 immer 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-Ereignishandler verwendet, 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);
});

Beispiele für Erweiterungen

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.

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

StorageArea

Attribute

onChanged

Event<functionvoidvoid>

Chrome 73 und höher

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

Die onChanged.addListener-Funktion sieht so aus:
```
(callback: function) => {...}
```
- callback
  
  Funktion
  
  Der Parameter callback sieht so aus:
```
(changes: object) => void
```
  - Änderungen
    
    Objekt
löschen

void

Promise

Entfernt alle Elemente aus dem Speicher.

Die clear-Funktion sieht so aus:
```
(callback?: function) => {...}
```
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus:
```
() => void
```
- Gibt zurück
  Promise<void>
  
  Chrome 95 und höher
  
  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
get

void

Promise

Ruft ein oder mehrere Elemente aus dem Speicher ab.

Die get-Funktion sieht so aus:
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- Schlüssel
  
  string | string[] | object optional
  
  Ein einzelner Schlüssel, eine Liste von Schlüsseln oder ein Dictionary mit 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 Inhalt des Speichers abzurufen.
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus:
```
(items: object) => void
```
  - Elemente
    
    Objekt
    
    Objekt mit Elementen in den zugehörigen Schlüssel/Wert-Zuordnungen.
- Gibt zurück
  Promise<object>
  
  Chrome 95 und höher
  
  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
getBytesInUse

void

Promise

Ruft die Menge an Speicherplatz (in Byte) ab, die von einem oder mehreren Elementen verwendet wird.

Die getBytesInUse-Funktion 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. Übergeben Sie null, um die Gesamtnutzung des gesamten Speichers zu erhalten.
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus:
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    Zahl
    
    Die Menge des verwendeten Speichers in Byte.
- Gibt zurück
  Promise<number>
  
  Chrome 95 und höher
  
  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
getKeys

void

Promise Chrome 130 und höher

Ruft alle Schlüssel aus dem Speicher ab.

Die getKeys-Funktion 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 wurden.
- Gibt zurück
  Promise<string[]>
  
  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
Entfernen

void

Promise

Entfernt ein oder mehrere Elemente aus dem Speicher.

Die remove-Funktion sieht so aus:
```
(keys: string | string[], callback?: function) => {...}
```
- Schlüssel
  
  String | String[]
  
  Ein einzelner Schlüssel oder eine Liste von Schlüsseln für die zu entfernenden Elemente.
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus:
```
() => void
```
- Gibt zurück
  Promise<void>
  
  Chrome 95 und höher
  
  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
set

void

Promise

Legt mehrere Elemente fest.

Die set-Funktion sieht so aus:
```
(items: object, callback?: function) => {...}
```
- Elemente
  
  Objekt
  
  Ein Objekt, das jedes Schlüssel/Wert-Paar enthält, mit dem der Speicher aktualisiert werden soll. Andere Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.
  
  Primitive Werte wie Zahlen werden wie erwartet serialisiert. Werte mit typeof, "object" und "function" werden in der Regel als {} serialisiert, mit Ausnahme von Array (wird wie erwartet serialisiert), Date und Regex (werden mit ihrer String-Darstellung serialisiert).
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus:
```
() => void
```
- Gibt zurück
  Promise<void>
  
  Chrome 95 und höher
  
  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
setAccessLevel

void

Promise Chrome 102+

Legt die gewünschte Zugriffsebene für den Speicherbereich fest. Standardmäßig ist der session-Speicher auf vertrauenswürdige Kontexte (Erweiterungsseiten und Service Worker) beschränkt, während der managed-, local- und sync-Speicher Zugriff sowohl von vertrauenswürdigen als auch von nicht vertrauenswürdigen Kontexten ermöglicht.

Die setAccessLevel-Funktion 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>
  
  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

StorageChange

Attribute

newValue

Beliebig optional

Der neue Wert des Elements, falls vorhanden.
oldValue

Beliebig optional

Der alte Wert des Elements, falls vorhanden.

Attribute

local

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

Typ

StorageArea und Objekt

Attribute

QUOTA_BYTES

10485760

Die maximale Menge an Daten (in Byte), die im lokalen Speicher gespeichert werden kann, gemessen an der 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 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. Sie sind für die Erweiterung schreibgeschützt. Wenn Sie versuchen, diesen Namespace zu ändern, führt das 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. Updates, 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 Promise abgelehnt wird.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1000000

Eingestellt

Für die storage.sync API gilt kein Kontingent für kontinuierliche 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 ein niedrigeres Limit als das kurzfristige höhere Limit für Schreibvorgänge pro Minute.

Updates, 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 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 sind 2 Schreibvorgänge pro Sekunde, was einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum ermöglicht.

Updates, 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 Promise abgelehnt wird.
QUOTA_BYTES

102400

Die maximale Gesamtmenge (in Byte) an Daten, die im Synchronisierungsspeicher gespeichert werden können, gemessen an der JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels. Updates, 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 Promise abgelehnt wird.
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. Updates mit Elementen, die größer als dieses Limit sind, schlagen sofort fehl und runtime.lastError wird festgelegt, wenn ein Callback verwendet wird oder 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

Übersicht

Lagerbereiche

Manifest

Nutzung

storage.local

storage.sync

storage.session

Speicher- und Drosselungslimits

Anwendungsfälle

Synchrone Reaktion auf Speicheraktualisierungen

Asynchrones Vorabladen aus dem Speicher

Beispiele für Erweiterungen

Typen

AccessLevel

Enum

StorageArea

Attribute

StorageChange

Attribute

Attribute

local

Typ

Attribute

managed

Typ

sync

Typ

Attribute

Ereignisse

onChanged

Parameter

chrome.storage