Diese Seite wurde von der Cloud Translation API übersetzt.

chrome.storage

Beschreibung

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

Berechtigungen

storage

Übersicht

Die Storage API bietet eine erweiterungsspezifische Möglichkeit, Nutzerdaten und den Status zu speichern. Es ähnelt den Speicher-APIs der Webplattform (IndexedDB und Storage), wurde jedoch für die Speicheranforderungen von Erweiterungen entwickelt. Dies sind einige der wichtigsten Funktionen:

Alle Erweiterungskontexte, einschließlich des Erweiterungs-Service-Workers und der Inhaltsskripte, haben Zugriff auf die Storage API.
Die serialisierbaren JSON-Werte werden als Objektattribute gespeichert.
Die Storage API ist mit Lese- und Schreibvorgängen im Bulk asynchron.
Auch wenn der Nutzer den Cache leert und den Browserverlauf löscht, bleiben die Daten erhalten.
Gespeicherte Einstellungen bleiben auch dann erhalten, wenn Sie den Split-Inkognitomodus verwenden.
Enthält einen exklusiven schreibgeschützten verwalteten Speicherbereich für Unternehmensrichtlinien.

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

Der Service Worker der Erweiterung kann nicht auf Storage zugreifen.
Inhaltsskripte teilen sich den Speicherplatz mit der Hostseite.
Über die Storage-Oberfläche 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:

Erstellen Sie ein nicht sichtbares Dokument mit einer Konvertierungsroutine und einem [onMessage][on-message]-Handler.
Einem nicht sichtbaren Dokument eine Konvertierungsroutine hinzufügen
Prüfen Sie im Erweiterungs-Service-Worker chrome.storage auf Ihre Daten.
Wenn Ihre Daten nicht gefunden werden, [erstellen][create-offscreen] ein nicht sichtbares Dokument und rufen Sie [sendMessage()][send-message] auf, um den Conversion-Ablauf zu starten.
Rufen Sie im onMessage-Handler des nicht sichtbaren Dokuments die Konvertierungsroutine auf.

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

Lagerflächen

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

storage.local: Die Daten werden lokal gespeichert und gelöscht, wenn die Erweiterung entfernt wird. Die Kontingentbeschränkung beträgt ungefähr 10 MB, kann aber durch Anfordern der Berechtigung "unlimitedStorage" erhöht werden. Erwägen Sie, sie zum Speichern größerer Datenmengen zu verwenden.

storage.sync: Wenn die Synchronisierung aktiviert ist, werden die Daten mit jedem Chrome-Browser synchronisiert, in dem der Nutzer angemeldet ist. Wenn die Richtlinie 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. Sie können sie verwenden, um die Nutzereinstellungen für alle synchronisierten Browser beizubehalten.

Warnung: In lokalen und synchronisierten Speicherbereichen sollten keine vertraulichen Nutzerdaten gespeichert werden, da sie nicht verschlüsselt sind. Wenn Sie mit sensiblen Daten arbeiten, sollten Sie den Speicherbereich session verwenden, um Werte so lange im Arbeitsspeicher zu speichern, bis der Browser heruntergefahren wird.

storage.session: Speichert Daten für die Dauer einer Browsersitzung. Standardmäßig ist sie nicht für Inhaltsskripte sichtbar. Dies kann jedoch durch Festlegen von chrome.storage.session.setAccessLevel() geändert werden. Die Kontingentbeschränkung beträgt ungefähr 10 MB. Erwägen Sie, sie zum Speichern globaler Variablen in verschiedenen Service Worker-Ausführungen zu verwenden.

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

Deklariere die Berechtigung "storage" in der Erweiterung, um die Storage API zu verwenden manifest. Beispiel:

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

Nutzung

In den folgenden Beispielen werden local, sync und session Speicherplatz:

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 zur Storage API nicht als das Hin- und Herschieben von Dingen vor. Denken Sie darüber nach, quasi wie etwas in eine Rohre stellen. Das Rohr enthält vielleicht bereits Material, möglicherweise sogar gefüllt. Gehen Sie immer von einer Verzögerung zwischen dem Hinzufügen von Speicherplatz und dem tatsächlichen aufgezeichnet.

Weitere Informationen zu Einschränkungen von Speicherbereichen 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 häufige Anwendungsfälle für die Storage API beschrieben.

Synchrone Antwort auf Speicherupdates

Sie können dem onChanged-Ereignis einen Listener hinzufügen, um Änderungen am Speicher zu verfolgen. Wenn sich der Speicherplatz ändert, wird dieses Ereignis ausgelöst. Der Beispielcode erfasst 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 weiterführen. In diesem Beispiel haben wir eine Optionsseite, ermöglicht es dem Nutzer, in einen „Debug-Modus“ Die Implementierung ist hier nicht zu sehen. Auf der Optionsseite werden die neuen Einstellungen sofort unter 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 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. Zu diesem Zweck folgendes Snippet verwendet einen asynchronen action.onClicked-Event-Handler, der auf den storageCache wartet global verwendet werden soll, 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

Die folgenden Beispiele zeigen weitere Demos der Storage API:

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 nicht von 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: <ph type="x-smartling-placeholder"></ph>
```
(callback: function) => {...}
```
- callback
  
  Funktion
  
  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(changes: object) => void
```
  - Änderungen
    
    Objekt
löschen

voidm

<ph type="x-smartling-placeholder"></ph> Versprechen

Entfernt alle Elemente aus dem Speicher.

Die Funktion clear sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(callback?: function) => {...}
```
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
() => void
```
- Gibt zurück
  Versprechen<void>
  
  Chrome (ab Version 88)
  
  Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
get

voidm

<ph type="x-smartling-placeholder"></ph> Versprechen

Ruft ein oder mehrere Elemente aus dem Speicher ab.

Die Funktion get sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- Schlüssel
  
  string | string[] | Objekt optional
  
  Ein einzelner abzurufender Schlüssel, eine Liste der abzurufenden Schlüssel oder ein Wörterbuch zum Festlegen von 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 Speicherplatz zu nutzen.
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(items: object) => void
```
  - Artikel
    
    Objekt
    
    Objekt mit Elementen in ihren Schlüssel/Wert-Zuordnungen.
- Gibt zurück
  Promise<object>
  
  Chrome (ab Version 88)
  
  Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
getBytesInUse

voidm

<ph type="x-smartling-placeholder"></ph> Versprechen

Ruft den Speicherplatz (in Byte) ab, der von einem oder mehreren Elementen verwendet wird.

Die Funktion getBytesInUse sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(keys?: string | string[], callback?: function) => {...}
```
- Schlüssel
  
  string | string[] optional
  
  Ein einzelner Schlüssel oder eine Liste von Schlüsseln zum Abrufen der Gesamtnutzung. Bei einer leeren Liste wird „0“ zurückgegeben. Übergeben Sie null, um die Gesamtnutzung des Speicherplatzes zu erhalten.
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    Zahl
    
    Menge des im Speicher verwendeten Speicherplatzes in Byte.
- Gibt zurück
  Promise<number>
  
  Chrome (ab Version 88)
  
  Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
getKeys

voidm

<ph type="x-smartling-placeholder"></ph> Versprechen Ausstehend

Ruft alle Schlüssel aus dem Speicher ab.

Die Funktion getKeys sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(callback?: function) => {...}
```
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(keys: string[]) => void
```
  - Schlüssel
    
    String[]
    
    Array mit Schlüsseln, die aus dem Speicher gelesen werden.
- Gibt zurück
  Promise<string[]>
  
  Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
Entfernen

voidm

<ph type="x-smartling-placeholder"></ph> Versprechen

Entfernt ein oder mehrere Elemente aus dem Speicher.

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

voidm

<ph type="x-smartling-placeholder"></ph> Versprechen

Legt mehrere Elemente fest.

Die Funktion set sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(items: object, callback?: function) => {...}
```
- Artikel
  
  Objekt
  
  Ein Objekt, das jedem Schlüssel/Wert-Paar zum Aktualisieren des Speichers zugeordnet ist. Alle anderen Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.
  
  Einfache Werte wie Zahlen werden wie erwartet serialisiert. Werte mit einem typeof "object" und "function" werden normalerweise in {} serialisiert, mit Ausnahme von Array (serialisiert wie erwartet), Date und Regex (Serialisierung mit ihrer String-Darstellung).
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
() => void
```
- Gibt zurück
  Versprechen<void>
  
  Chrome (ab Version 88)
  
  Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
setAccessLevel

voidm

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 102 und höher

Hier legen Sie die gewünschte Zugriffsebene für den Speicherbereich fest. Die Standardeinstellung sind nur vertrauenswürdige Kontexte.

Die Funktion setAccessLevel sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
(accessOptions: object, callback?: function) => {...}
```
- accessOptions
  
  Objekt
  - accessLevel
    
    AccessLevel
    
    Die Zugriffsebene des Speicherbereichs.
- callback
  
  Funktion optional
  
  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>
```
() => void
```
- Gibt zurück
  Versprechen<void>
  
  Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

StorageChange

Attribute

newValue

Beliebige optionale

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

Beliebige optionale

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

Attribute

local

Elemente im Speicherbereich „local“ werden auf jedem Computer lokal gespeichert.

Typ

StorageArea und Objekt

Attribute

QUOTA_BYTES

10485760

Die maximale Datenmenge (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. Updates, die dazu führen, dass dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet wird, oder ein abgelehntes Promise, wenn ein async- oder await-Tag verwendet wird.

managed

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

Typ

StorageArea

session

Chrome 102 und höher MV3+

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

Typ

StorageArea und Objekt

Attribute

QUOTA_BYTES

10485760

Die maximale Datenmenge (in Byte) an Daten, die im Arbeitsspeicher gespeichert werden können, gemessen durch Schätzung der dynamisch zugewiesenen Arbeitsspeichernutzung jedes Werts und Schlüssels. Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

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, dass dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1.000.000

<ph type="x-smartling-placeholder"></ph> Eingestellt

Für die storage.sync API gilt kein anhaltendes Kontingent für 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 1 alle 2 Sekunden, ein niedrigerer Höchstwert als der kurzfristig höhere Grenzwert für Schreibvorgänge pro Minute.

Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet 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. Dies sind 2 pro Sekunde, was einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum bietet.

Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise 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, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen runtime.lastError fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird.
QUOTA_BYTES_PER_ITEM

8192

Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronisierungsspeicher, gemessen durch die JSON-Stringifizierung seines Werts plus seiner Schlüssellänge. Aktualisierungen mit Elementen, die dieses Limit überschreiten, schlagen sofort fehl und es wird runtime.lastError festgelegt, wenn ein Callback verwendet oder ein Promise abgelehnt wird.

Ereignisse

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: <ph type="x-smartling-placeholder"></ph>
```
(changes: object, areaName: string) => void
```
- Änderungen
  
  Objekt
- areaName
  
  String