chrome.storage

Beschreibung

Berechtigungen

Ü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 Extension Storage APIs über einen Service Worker:

1. Erstellen Sie ein Offscreen-Dokument mit einer Conversion-Routine und einem [onMessage][on-message]-Handler.
2. Einem Offscreen-Dokument eine Conversion-Routine hinzufügen
3. Suchen Sie im Service Worker der Erweiterung nach chrome.storage für Ihre Daten.
4. 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.
5. 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, größere Datenmengen darin zu speichern.

storage.sync

Wenn die Synchronisierung aktiviert ist, werden die Daten mit allen Chrome-Browsern synchronisiert, in denen der Nutzer 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. Sie können damit Nutzereinstellungen in synchronisierten Browsern beibehalten.

storage.session

Speichert Daten für die Dauer einer Browsersitzung im Arbeitsspeicher. Standardmäßig ist sie für Inhaltsscripts 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-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);
});

Beispiele für Erweiterungen

Weitere Demos der Storage API finden Sie in den folgenden Beispielen:

• Globale Sucherweiterung:
• Erweiterung für Wassermelder

chrome.storage.onChanged.addListener(
  callback: function,
)