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. 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 Dienst-Workers und der Inhaltsscripts 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.
  • Auch wenn der Nutzer den Cache 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.

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

  • Der Dienst-Worker der Erweiterung kann nicht auf Storage zugreifen.
  • Inhaltsskripte teilen sich den Speicherplatz mit der Hostseite.
  • Daten, die über die Storage-Oberfläche gespeichert wurden, gehen verloren, wenn der Nutzer seinen Browserverlauf löscht.

So verschieben Sie Daten von einem Service Worker aus Web Storage APIs in Erweiterungsspeicher-APIs:

  1. Erstellen Sie ein nicht sichtbares Dokument mit einer Konvertierungsroutine und einem [onMessage][on-message]-Handler.
  2. Fügen Sie einem nicht sichtbaren Dokument eine Conversion-Routine hinzu.
  3. Prüfen Sie im Erweiterungs-Dienst-Worker, ob chrome.storage Ihre Daten enthält.
  4. 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.
  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][storage-and-cookies].

Speicherbereiche

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

storage.local
Die 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. Sie eignet sich zum Speichern größerer Datenmengen.
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, wenn er wieder online ist. Das Kontingent ist auf etwa 100 KB begrenzt, also 8 KB pro Artikel. Sie können sie verwenden, um Nutzereinstellungen in synchronisierten Browsern beizubehalten.
storage.session
Speichert Daten für die Dauer einer Browsersitzung. Standardmäßig ist es nicht für Inhaltsscripts sichtbar. Dieses Verhalten kann jedoch durch Festlegen von chrome.storage.session.setAccessLevel() geändert werden. Das Kontingent ist auf etwa 10 MB begrenzt. Sie können sie verwenden, um globale Variablen über mehrere Service Worker-Ausführungen hinweg zu speichern.
storage.managed
Administratoren können mithilfe eines Schemas und Unternehmensrichtlinien die Einstellungen einer unterstützenden Erweiterung in einer verwalteten Umgebung 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 angeben. 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. Stellen Sie sich das Hinzufügen von Speicherplatz wie das Einfüllen von etwas in eine Leitung vor. Möglicherweise befindet sich bereits Material in der Leitung und sie ist sogar voll. Rechnen Sie immer mit einer Verzögerung zwischen dem Hinzufügen von Daten zum Speicher und dem tatsächlichen Aufzeichnen.

Ausführliche Informationen zu Einschränkungen für Speicherbereiche und zu 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 erfassen möchten, können Sie dem Ereignis onChanged einen Listener hinzufügen. Wenn sich etwas im Speicher ä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, auf der der Nutzer den „Debug-Modus“ aktivieren kann (Implementierung 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.

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
Gibt Kontexte an, die nicht von der Erweiterung stammen.

StorageArea

Attribute

  • onChanged

    Event<functionvoidvoid>

    Chrome 73 und höher

    Wird ausgelöst, wenn sich mindestens ein Element ändert

    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 Funktion clear sieht so aus: 

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

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => 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

    void

    Versprechen

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

      function optional

      Der Parameter callback sieht so aus: 

      (items: object) => void

      • Elemente

        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

    void

    Promise

    Gibt den Speicherplatz (in Byte) an, der von einem oder mehreren Elementen belegt wird.

    Die Funktion getBytesInUse 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 Speicherplatzes zu erhalten.

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      (bytesInUse: number) => void

      • bytesInUse

        Zahl

        Menge des im Speicher verwendeten Speicherplatzes in Byte.

    • Gibt zurück

      Versprechen<number>

      Chrome (ab Version 88)

      Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

  • getKeys

    voidm

    Versprechen Chrome 130 oder höher

    Ruft alle Schlüssel aus dem Speicher ab.

    Die Funktion getKeys 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

      Versprechen<string[]>

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

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Chrome (ab Version 88)

      Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

  • set

    void

    Versprechen

    Legt mehrere Elemente fest.

    Die set-Funktion sieht so aus: 

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

    • Elemente

      Objekt

      Ein Objekt, das jedem Schlüssel/Wert-Paar zum Aktualisieren des Speichers zugeordnet ist. Andere Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.

      Primäre 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

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Chrome 88 und höher

      Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

  • setAccessLevel

    void

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

      Promise-Objekte 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 ein neuer Wert vorhanden ist.

  • oldValue

    beliebig optional

    Der alte Wert des Artikels, falls vorhanden.

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

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), die im Arbeitsspeicher gespeichert werden kann, gemessen anhand der geschätzten dynamisch zugewiesenen Arbeitsspeichernutzung jedes Werts und 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.

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

    Eingestellt

    Für die storage.sync API gibt es kein Kontingent für fortlaufende 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.

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

    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