chrome.storage

Beschreibung

Berechtigungen

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:

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

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

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:

• Globale Sucherweiterung:
• Erweiterung für Wassermelder

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:

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

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

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