chrome.storage

Beschreibung

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

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

Konzepte und Verwendung

Die Storage API bietet eine Erweiterungsspezifische Möglichkeit, Nutzerdaten und den Status zu speichern. Sie ähnelt den Speicher-APIs der Webplattform (IndexedDB und Storage), wurde jedoch entwickelt, um die Speicheranforderungen von Erweiterungen zu erfüllen. Hier sind einige wichtige Funktionen:

  • Alle Erweiterungskontexte, einschließlich des Erweiterungs-Dienstarbeiters und Inhaltsscripts, 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.
  • Auch wenn der Nutzer den Cache und den Browserverlauf löscht, bleiben die Daten erhalten.
  • Gespeicherte Einstellungen bleiben auch bei Verwendung des geteilten Inkognitomodus erhalten.
  • Enthält einen exklusiven schreibgeschützten verwalteten Speicherbereich für Unternehmensrichtlinien.

Können Erweiterungen Webspeicher-APIs verwenden?

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

  • Erweiterungs-Service Worker können die Web Storage API nicht verwenden.
  • Inhaltsscripts teilen sich den Speicherplatz 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 aus einem Service Worker von Webspeicher-APIs zu Erweiterungsspeicher-APIs:

  1. Bereiten Sie eine HTML-Seite und eine Scriptdatei für das Offscreen-Dokument vor. Die Scriptdatei sollte eine Konvertierungsroutine und einen onMessage-Handler enthalten.
  2. Prüfen Sie im Erweiterungs-Dienst-Worker, ob Ihre Daten unter chrome.storage aufgeführt sind.
  3. Wenn Ihre Daten nicht gefunden werden, rufen Sie createDocument() an.
  4. Rufe nach der Auflösung des zurückgegebenen Promise sendMessage() auf, um die Conversion-Routine zu starten.
  5. Rufen Sie die Conversion-Routine im onMessage-Handler des Offscreen-Dokuments auf.

Außerdem gibt es einige Nuancen bei der Funktionsweise von Webspeicher-APIs in Erweiterungen. Weitere Informationen finden Sie im Artikel Speicher und Cookies.

Lagerflächen

Die Storage API ist in die folgenden Speicherbereiche unterteilt:

storage.local
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 niedriger), kann aber durch Anfordern der Berechtigung "unlimitedStorage" erhöht werden. Wir empfehlen die Verwendung von storage.local, um größere Datenmengen zu speichern.
storage.managed
Verwalteter Speicher ist ein schreibgeschützter Speicher für Richtlinien installierte Erweiterungen, der von Systemadministratoren mithilfe eines von Entwicklern definierten Schemas und Unternehmensrichtlinien verwaltet wird. Richtlinien sind Optionen ähnlich, werden aber von einem Systemadministrator anstelle des Nutzers konfiguriert. So kann die Erweiterung für alle Nutzer einer Organisation vorab konfiguriert werden. Informationen zu Richtlinien finden Sie in der Dokumentation für Administratoren. Weitere Informationen zum Speicherbereich managed finden Sie unter Manifest für Speicherbereiche.
storage.session
Speichert Daten während einer Browsersitzung im Arbeitsspeicher. Standardmäßig ist es nicht für Inhaltsscripts sichtbar. Dieses Verhalten kann jedoch durch Festlegen von chrome.storage.session.setAccessLevel() geändert werden. Das Speicherlimit beträgt 10 MB (1 MB in Chrome 111 und niedriger). Diestorage.session-Benutzeroberfläche ist eine von mehreren, die wir für Service Worker empfehlen.
storage.sync
Wenn die Synchronisierung aktiviert ist, werden die Daten mit jedem Chrome-Browser synchronisiert, in dem der Nutzer 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 Kontingent ist auf etwa 100 KB begrenzt, also 8 KB pro Artikel. Wir empfehlen, storage.sync zu verwenden, um Nutzereinstellungen in synchronisierten Browsern beizubehalten. Wenn Sie mit vertraulichen Nutzerdaten arbeiten, verwenden Sie stattdessen storage.session.

Speicher- und Drosselungslimits

Die Storage API unterliegt den folgenden Nutzungsbeschränkungen:

  • Das Speichern von Daten geht oft mit Leistungseinbußen einher. Außerdem gibt es Speicherkontingente für die API. Wir empfehlen Ihnen, mit Bedacht zu entscheiden, welche Daten Sie speichern, damit Sie weiterhin Daten speichern können.
  • Das Speichern kann einige Zeit dauern. Strukturieren Sie Ihren Code so, dass diese Zeit berücksichtigt wird.

Details zu Speicherplatzbeschränkungen und den Folgen einer Überschreitung 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 veranschaulicht.

Synchrone Reaktion auf Speicherupdates

Wenn Sie Änderungen am Speicherplatz im Blick behalten möchten, fügen Sie dem Ereignis onChanged einen Listener hinzu. Wenn sich etwas im Speicher ändert, wird dieses Ereignis ausgelöst. 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 weiterführen. In diesem Beispiel haben wir eine Optionsseite, auf der der Nutzer den „Debug-Modus“ aktivieren kann (Implementierung hier nicht zu sehen). Die neuen Einstellungen werden auf der Seite mit den Optionen 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;
  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 Vorladen 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 wird im folgenden Snippet ein asynchroner action.onClicked-Ereignishandler verwendet, der darauf wartet, dass die globale Variable storageCache ausgefü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);
});

Beispiele

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

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

Synchronisieren

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

Sitzung

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was 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:

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 aus der Erweiterung stammen.

StorageArea

Attribute

  • onChanged

    Ereignis<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

    Alle Elemente werden aus dem Speicher entfernt.

    Die clear-Funktion sieht so aus: 

    (callback?: function) => {...}

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Promise<void>

      Chrome 88 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • 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 Wörterbuch mit Standardwerten (siehe Beschreibung des Objekts). Eine leere Liste oder ein leeres Objekt gibt ein leeres Ergebnisobjekt zurück. Geben Sie null ein, um den gesamten Inhalt des Speichers abzurufen.

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      (items: object) => void

      • Elemente

        Objekt

        Objekt mit Elementen in den Schlüssel/Wert-Zuordnungen.

    • Gibt zurück

      Promise<object>

      Chrome 88 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • getBytesInUse

    void

    Promise

    Gibt den Speicherplatz (in Byte) an, der von einem oder mehreren Elementen belegt 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. Für eine leere Liste wird 0 zurückgegeben. Geben Sie null ein, um die Gesamtnutzung des gesamten Speicherplatzes zu erhalten.

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      (bytesInUse: number) => void

      • bytesInUse

        Zahl

        Der im Speicher belegte Speicherplatz in Byte.

    • Gibt zurück

      Promise<number>

      Chrome 88 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • getKeys

    void

    Versprechen Chrome 130 und höher

    Ruft alle Schlüssel aus dem Speicher ab.

    Die getKeys-Funktion sieht so aus: 

    (callback?: function) => {...}

    • callback

      function 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[]>

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • 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 Elemente, die entfernt werden sollen.

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Promise<void>

      Chrome 88 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • set

    void

    Promise

    Hiermit werden mehrere Elemente festgelegt.

    Die set-Funktion sieht so aus: 

    (items: object, callback?: function) => {...}

    • Elemente

      Objekt

      Ein Objekt, das für jedes Schlüssel/Wert-Paar einen Wert zum Aktualisieren des Speichers angibt. Andere Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.

      Primäre Werte wie Zahlen werden wie erwartet serialisiert. Werte mit typeof, "object" und "function" werden in der Regel als {} serialisiert, mit Ausnahme von Array (wie erwartet serialisiert), Date und Regex (werden mit ihrer String-Darstellung serialisiert).

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Promise<void>

      Chrome 88 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • setAccessLevel

    void

    Promise Chrome 102 und höher

    Hier legen Sie die gewünschte Zugriffsebene für den Speicherbereich fest. Standardmäßig werden nur vertrauenswürdige Kontexte berücksichtigt.

    Die setAccessLevel-Funktion sieht so aus: 

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      Objekt

      • accessLevel

        AccessLevel

        Die Zugriffsebene des Speicherbereichs.

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Promise<void>

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

StorageChange

Attribute

  • newValue

    beliebig optional

    Der neue Wert des Artikels, falls vorhanden.

  • oldValue

    beliebig optional

    Der alte Wert des Artikels, falls vorhanden.

Attribute

local

Elemente im Speicherbereich local sind lokal auf jedem Computer.

Typ

StorageArea und Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Datenmenge (in Byte), die im lokalen Speicher gespeichert werden kann, gemessen an der JSON-Stringifizierung jedes Werts und der Länge jedes Schlüssels. Dieser Wert wird ignoriert, wenn die Erweiterung die Berechtigung unlimitedStorage hat. Updates, die dieses Limit überschreiten würden, schlagen sofort fehl und setzen runtime.lastError, wenn ein Callback verwendet wird, oder ein abgelehntes Promise, wenn async/await verwendet wird.

managed

Elemente im Speicherbereich managed werden durch eine vom Domainadministrator konfigurierte Unternehmensrichtlinie festgelegt und sind für die Erweiterung nur lesbar. Versuche, diesen Namespace zu ändern, führen zu einem Fehler. Informationen zum Konfigurieren einer Richtlinie finden Sie unter Manifest für Speicherbereiche.

Typ

StorageArea

session

Chrome 102 und höher MV3 und höher

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

Typ

StorageArea und Objekt

Attribute

  • QUOTA_BYTES

    10485760

    Die maximale Datenmenge (in Byte), die im Arbeitsspeicher gespeichert werden kann, gemessen anhand der geschätzten dynamisch zugewiesenen Arbeitsspeichernutzung jedes Werts und Schlüssels. Updates, die dazu führen würden, dass dieses Limit überschritten wird, schlagen sofort fehl und setzen runtime.lastError, wenn ein Rückruf verwendet oder ein Versprechen abgelehnt wird.

sync

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

Typ

StorageArea und Objekt

Attribute

  • MAX_ITEMS

    512

    Die maximale Anzahl von Elementen, die im Synchronspeicher gespeichert werden können. Updates, die dieses Limit überschreiten würden, schlagen sofort fehl und runtime.lastError wird festgelegt, wenn ein Rückruf verwendet oder ein Versprechen abgelehnt wird.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Eingestellt

    Für die storage.sync API gibt es 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 einer Schreibrate von einer Schreiboperation alle zwei Sekunden. Das ist ein niedrigerer Grenzwert als das kurzfristig höhere Limit für Schreibvorgänge pro Minute.

    Updates, die dieses Limit überschreiten würden, schlagen sofort fehl und setzen runtime.lastError, wenn ein Rückruf verwendet oder ein Versprechen 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 2 pro Sekunde und bietet einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum.

    Updates, die dieses Limit überschreiten würden, schlagen sofort fehl und setzen runtime.lastError, wenn ein Rückruf verwendet oder ein Versprechen abgelehnt wird.

  • QUOTA_BYTES

    102400

    Die maximale Gesamtmenge (in Byte) an Daten, die im Synchronspeicher gespeichert werden können, gemessen an der JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels. Updates, die dieses Limit überschreiten würden, schlagen sofort fehl und setzen runtime.lastError, wenn ein Rückruf verwendet oder ein Versprechen abgelehnt wird.

  • QUOTA_BYTES_PER_ITEM

    8192

    Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronspeicher, gemessen an der JSON-Stringifizierung des Werts plus der Schlüssellänge. Updates, die Elemente enthalten, die größer als dieses Limit sind, schlagen sofort fehl und runtime.lastError wird festgelegt, wenn ein Rückruf verwendet oder ein Versprechen 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