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

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"
  ],
  ...
}

Beispiele

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

Beispiel (lokal)

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Beispiel (Synchronisierung)

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Beispiel (Sitzung)

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  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 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.

Dürfen Erweiterungen Web Storage APIs verwenden?

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

Extension Service Worker können die Web Storage API nicht verwenden.
Inhaltsskripte nutzen den Speicher der Hostseite gemeinsam.
Daten, die mit der Web Storage API gespeichert wurden, gehen verloren, wenn der Nutzer seinen Browserverlauf löscht.

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

Bereiten Sie eine HTML-Seite und eine Skriptdatei für das Offscreen-Dokument vor. Die Skriptdatei sollte eine Konvertierungsroutine und einen onMessage-Handler enthalten.
Prüfen Sie im Service Worker der Erweiterung chrome.storage auf Ihre Daten.
Wenn Ihre Daten nicht gefunden werden, rufen Sie createDocument() an.
Rufen Sie nach dem Auflösen des zurückgegebenen Promise sendMessage() 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.

Speicher- und Drosselungslimits

Für die Storage API gelten Nutzungseinschränkungen:

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

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.

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ü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 sie für Inhaltsscripts verfügbar, dieses Verhalten kann jedoch durch Aufrufen von chrome.storage.local.setAccessLevel() geändert werden.

Verwaltet

Verwalteter Speicher ist für durch Richtlinien installierte Erweiterungen schreibgeschützt. Sie wird von Systemadministratoren mithilfe eines vom Entwickler definierten Schemas 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 wird storage.managed für Inhaltsscripts bereitgestellt. 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 geleert, wenn die Erweiterung deaktiviert, neu geladen oder aktualisiert wird und wenn der Browser neu gestartet wird. Standardmäßig ist sie für Content-Scripts 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 jedem Chrome-Browser synchronisiert, in dem er angemeldet ist. Wenn diese Option 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, also 8 KB pro Element.

Wir empfehlen, storage.sync zu verwenden, damit die Nutzereinstellungen in allen synchronisierten Browsern beibehalten werden. Wenn Sie mit vertraulichen Nutzerdaten arbeiten, verwenden Sie stattdessen storage.session. Standardmäßig wird storage.sync für Inhaltsscripts bereitgestellt. 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 Methode get() können Sie einen oder mehrere Schlüssel aus einem 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 beobachten.

Anwendungsfälle

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

Auf Speicherplatz-Updates reagieren

Wenn Sie Änderungen am Speicher verfolgen möchten, fügen Sie einen Listener für das onChanged-Ereignis hinzu. 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 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-Event-Handler verwendet, der darauf wartet, dass die globale Variable storageCache gefüllt wird, 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);
});

Entwicklertools

Sie können mit der API gespeicherte Daten in den DevTools ansehen und bearbeiten. Weitere Informationen finden Sie in der DevTools-Dokumentation auf der Seite View and edit extension storage (Speicher von Erweiterungen ansehen und bearbeiten).

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.

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 schreibgeschützt für die Erweiterung. 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

session

Chrome 102+ MV3+

Elemente im Speicherbereich session werden im Arbeitsspeicher gespeichert und nicht auf der Festplatte gesichert.

Typ

StorageArea und Objekt

Attribute

QUOTA_BYTES

10485760

Die maximale Menge an Daten (in Byte), die im Arbeitsspeicher gespeichert werden kann. Sie wird geschätzt, indem die dynamisch zugewiesene Arbeitsspeichernutzung jedes Werts und Schlüssels gemessen wird. Updates, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl und runtime.lastError wird festgelegt, wenn ein Callback verwendet wird 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. 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 fortlaufende 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 runtime.lastError wird festgelegt, 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 runtime.lastError wird festgelegt, 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 runtime.lastError wird festgelegt, 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

Beispiele

Beispiel (lokal)

Beispiel (Synchronisierung)

Beispiel (Sitzung)

Konzepte und Verwendung

Dürfen Erweiterungen Web Storage APIs verwenden?

Speicher- und Drosselungslimits

Lagerbereiche

Lokal

Verwaltet

Sitzung

Synchronisieren

Methoden und Ereignisse

get()

getBytesInUse()

getKeys()

remove()

set()

setAccessLevel()

clear()

onChanged

Anwendungsfälle

Auf Speicherplatz-Updates reagieren

Asynchrones Vorabladen aus dem Speicher

Entwicklertools

Typen

AccessLevel

Enum

StorageChange

Attribute

Attribute

local

Typ

Attribute

managed

Typ

session

Typ

Attribute

sync

Typ

Attribute

Ereignisse

onChanged

Parameter

chrome.storage