Beschreibung
Mit der chrome.storage
API können Sie Nutzerdaten speichern, abrufen und Änderungen an ihnen verfolgen.
Berechtigungen
storage
Überblick
Die Storage API bietet eine erweiterungsspezifische Möglichkeit, Nutzerdaten und -status zu speichern. Sie ähnelt den Speicher-APIs der Webplattform (IndexedDB und Storage), wurde aber für die Speicheranforderungen von Erweiterungen entwickelt. Hier einige wichtige Funktionen:
- Alle Erweiterungskontexte, einschließlich Extension Service Worker und Inhaltsskripts, haben Zugriff auf die Storage API.
- Die seriellen JSON-Werte werden als Objekteigenschaften gespeichert.
- Die Storage API ist asynchron mit Bulk-Lese- und Schreibvorgängen.
- Auch wenn der Nutzer den Cache löscht und den Browserverlauf löscht, bleiben die Daten erhalten.
- Gespeicherte Einstellungen bleiben auch bei Verwendung des aufgeteilten Inkognitomodus erhalten.
- Enthält einen exklusiven schreibgeschützten verwalteten Speicherbereich für Unternehmensrichtlinien.
Obwohl Erweiterungen die [Storage
][mdn-storage]-Oberfläche (Zugriff über window.localStorage
) in einigen Kontexten (Pop-up- und andere HTML-Seiten) verwenden können, wird sie aus den folgenden Gründen nicht empfohlen:
- Der Service Worker der Erweiterung kann nicht auf
Storage
zugreifen. - Inhaltsscripts teilen den Speicherplatz mit der Hostseite.
- Daten, die über die
Storage
-Benutzeroberfläche gespeichert werden, gehen verloren, wenn der Nutzer seinen Browserverlauf löscht.
So verschieben Sie Daten von einem Service Worker aus Web Storage APIs in Erweiterungsspeicher-APIs:
- Erstellen Sie ein nicht sichtbares Dokument mit einer Konvertierungsroutine und einem [
onMessage
][on-message]-Handler. - Einem nicht sichtbaren Dokument einen Konvertierungsablauf hinzufügen
- Prüfen Sie im Erweiterungs-Service-Worker
chrome.storage
auf Ihre Daten. - Wenn Ihre Daten nicht gefunden werden, [erstellen][create-offscreen] ein nicht sichtbares Dokument und rufen Sie [
sendMessage()
][send-message] an, um die Konvertierungsroutine zu starten. - Rufen Sie im Handler
onMessage
des nicht sichtbaren Dokuments die Konvertierungsroutine auf.
Es gibt auch einige Besonderheiten bei der Funktionsweise von Web Storage-APIs in Erweiterungen. Weitere Informationen finden Sie im Artikel [Storage und Cookies][storage-and-cookies].
Lagerbereiche
Die Storage API ist in die folgenden vier Kategorien („Speicherbereiche“) unterteilt:
storage.local
- Die Daten werden lokal gespeichert und beim Entfernen der Erweiterung gelöscht. Die Kontingentbeschränkung beträgt ungefähr 10 MB, kann aber durch Anfordern der Berechtigung
"unlimitedStorage"
erhöht werden. Erwägen Sie die Verwendung 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. Die Kontingentbeschränkung beträgt ungefähr 100 KB, 8 KB pro Element. Sie können damit die Nutzereinstellungen in allen synchronisierten Browsern beibehalten.
- storage.session
- Speichert Daten für die Dauer einer Browsersitzung im Arbeitsspeicher. Standardmäßig ist sie nicht für Inhaltsskripte verfügbar. Sie können dieses Verhalten jedoch ändern, indem Sie
chrome.storage.session.setAccessLevel()
festlegen. Die Kontingentbeschränkung beträgt ungefähr 10 MB. Erwägen Sie, damit globale Variablen über alle 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
Damit Sie die Storage API verwenden können, müssen Sie die Berechtigung "storage"
im Manifest der Erweiterung deklarieren. Beispiel:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Nutzung
In den folgenden Beispielen werden die Speicherbereiche local
, sync
und session
veranschaulicht:
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 nicht vor, die Storage API zu erweitern, als wäre alles in einem riesigen Truck. Stellen Sie sich das Hinzufügen von Speicher wie in einer Pipe vor. Das Rohr enthält möglicherweise bereits Material, das möglicherweise sogar gefüllt wird. Es sollte immer von einer Verzögerung zwischen dem Hinzufügen zum Speicher und der eigentlichen Aufzeichnung ausgehen.
Weitere Informationen zu Speicherbeschränkungen und was bei deren Überschreitung passiert, finden Sie in den Kontingentinformationen für sync
, local
und session
.
Anwendungsfälle
In den folgenden Abschnitten werden häufige Anwendungsfälle für die Storage API beschrieben.
Synchrone Antwort auf Speicherupdates
Sie können dem onChanged
-Ereignis einen Listener hinzufügen, um Änderungen am Speicher zu verfolgen. Wenn sich der 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}".`
);
}
});
Mit dieser Idee können wir noch einen Schritt weitergehen. In diesem Beispiel haben wir eine Seite mit Optionen, auf der der Nutzer in den Debug-Modus umschalten kann. Die Implementierung ist hier nicht aufgeführt. Auf der Seite „Optionen“ werden die neuen Einstellungen 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 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 verwendet das folgende Snippet einen asynchronen Event-Handler action.onClicked
, der auf das Ausfüllen des globalen storageCache
-Elements wartet, bevor seine 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:
Typen
AccessLevel
Die Zugriffsebene des Speicherbereichs.
Enum
"TRUSTED_CONTEXTS"
Gibt Kontexte an, die aus der Erweiterung selbst stammen.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Gibt Kontexte an, die von außerhalb der Erweiterung stammen.
StorageArea
Attribute
-
onChanged
Ereignis<functionvoidvoid>
Chrome 73 und höherWird ausgelöst, wenn sich mindestens ein Element ändert
Die Funktion
onChanged.addListener
sieht so aus:(callback: function) => {...}
-
callback
Funktion
Der Parameter
callback
sieht so aus:(changes: object) => void
-
Änderungen
Objekt
-
-
-
löschen
void
VersprechenEntfernt alle Elemente aus dem Speicher.
Die Funktion
clear
sieht so aus:(callback?: function) => {...}
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
-
Gibt zurück
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
-
-
get
void
VersprechenRuft ein oder mehrere Elemente aus dem Speicher ab.
Die Funktion
get
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 mit Standardwerten (siehe Beschreibung des Objekts). Bei einer leeren Liste oder einem leeren Objekt wird ein leeres Ergebnisobjekt zurückgegeben. Übergeben Sie
null
für den gesamten Speicherinhalt. -
callback
Funktion optional
Der Parameter
callback
sieht so aus:(items: object) => void
-
items
Objekt
Objekt mit Elementen in den zugehörigen Schlüssel/Wert-Paar-Zuordnungen.
-
-
Gibt zurück
Promise<object>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
-
-
getBytesInUse
void
VersprechenRuft den Speicherplatz (in Byte) ab, der von einem oder mehreren Elementen verwendet 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. Wenn Sie
null
übergeben, erhalten Sie die Gesamtnutzung des gesamten Speicherplatzes. -
callback
Funktion optional
Der Parameter
callback
sieht so aus:(bytesInUse: number) => void
-
bytesInUse
Zahl
Im Speicher verwendeter Speicherplatz in Byte.
-
-
Gibt zurück
Versprechen<Zahl>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
-
-
entfernen
void
VersprechenEntfernt mindestens ein Element aus dem Speicher.
Die Funktion
remove
sieht so aus:(keys: string | string[], callback?: function) => {...}
-
Schlüssel
Zeichenfolge | Zeichenfolge[]
Ein einzelner Schlüssel oder eine Liste von Schlüsseln für Elemente, die entfernt werden sollen.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
-
Gibt zurück
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
-
-
festgelegt
void
VersprechenLegt mehrere Elemente fest.
Die Funktion
set
sieht so aus:(items: object, callback?: function) => {...}
-
items
Objekt
Ein Objekt, das jedem Schlüssel/Wert-Paar für die Speicheraktualisierung zuweist. Andere Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.
Primitive Werte wie Zahlen werden wie erwartet priorisiert. Werte mit einem
typeof
-"object"
und einem"function"
-Wert werden in der Regel als{}
mit Ausnahme vonArray
(erwartet) undRegex
(serialisiert mit derString
-Darstellung) verwendet.Date
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
-
Gibt zurück
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
-
-
setAccessLevel
void
Versprechen Chrome 102 oder höherLegt die gewünschte Zugriffsebene für den Speicherbereich fest. Standardmäßig sind nur vertrauenswürdige Kontexte ausgewählt.
Die Funktion
setAccessLevel
sieht so aus:(accessOptions: object, callback?: function) => {...}
-
accessOptions
Objekt
-
accessLevel
Die Zugriffsebene des Speicherbereichs.
-
-
callback
Funktion 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. Andere Plattformen müssen Callbacks verwenden.
-
StorageChange
Attribute
-
newValue
Beliebig optional
Der neue Wert des Elements, falls ein neuer Wert vorhanden ist.
-
oldValue
Beliebig optional
Der alte Wert des Elements, wenn ein alter Wert vorhanden war.
Attribute
local
Inhalte im Speicherbereich „local
“ sind auf jedem Computer lokal gespeichert.
Typ
StorageArea und Objekt
Attribute
-
QUOTA_BYTES
10485760
Die maximale Menge (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. Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legenruntime.lastError
fest, wenn Sie einen Callback verwenden, oder ein abgelehntes Promise, wenn Sie „async/await“ verwenden.
managed
Elemente im Speicherbereich „managed
“ werden durch eine vom Domainadministrator konfigurierte Unternehmensrichtlinie festgelegt und sind für die Erweiterung schreibgeschützt. Der Versuch, diesen Namespace zu ändern, führt zu einem Fehler. Informationen zum Konfigurieren einer Richtlinie finden Sie unter Manifest für Speicherbereiche.
Typ
session
Elemente im Speicherbereich „session
“ werden im Arbeitsspeicher gespeichert und nicht auf dem Laufwerk gespeichert.
Typ
StorageArea und Objekt
Attribute
-
QUOTA_BYTES
10485760
Die maximale Menge (in Byte) an Daten, die im Speicher gespeichert werden können, gemessen durch Schätzung der dynamisch zugewiesenen Speichernutzung jedes Werts und Schlüssels. Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird.
sync
Elemente im Speicherbereich „sync
“ werden über die Chrome-Synchronisierung synchronisiert.
Typ
StorageArea und Objekt
Attribute
-
MAX_ITEMS
512
Die maximale Anzahl der Elemente, die im Synchronisierungsspeicher gespeichert werden können. Aktualisierungen, die zu einer Überschreitung dieses Limits führen würden, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird. -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1.000.000
EingestelltDie Storage.sync API hat kein Kontingent für kontinuierliche Schreibvorgänge mehr.
-
MAX_WRITE_OPERATIONS_PER_HOUR
1.800
Die maximale Anzahl von
set
-,remove
- oderclear
-Vorgängen, die pro Stunde ausgeführt werden können. Dies ist ein Wert von „1“ alle 2 Sekunden, eine Untergrenze als das kurzzeitig höhere Limit für Schreibvorgänge pro Minute.Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird. -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
Die maximale Anzahl von
set
-,remove
- oderclear
-Vorgängen, die pro Minute ausgeführt werden können. Dies entspricht 2 pro Sekunde und bietet einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum.Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird. -
QUOTA_BYTES
102.400
Die maximale Gesamtmenge (in Byte) an Daten, die im Synchronisierungsspeicher gespeichert werden kann, gemessen durch die JSON-Stringifizierung jedes Werts plus der Länge jedes Schlüssels. Aktualisierungen, die zu einer Überschreitung dieses Limits führen, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird. -
QUOTA_BYTES_PER_ITEM
8.192
Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronisierungsspeicher, gemessen anhand der JSON-Stringisierung seines Werts plus seiner Schlüssellänge. Updates mit Artikeln, die dieses Limit überschreiten, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet wird oder ein Promise-Objekt abgelehnt wird.
Veranstaltungen
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
Wird ausgelöst, wenn sich mindestens ein Element ändert
Parameter
-
callback
Funktion
Der Parameter
callback
sieht so aus:(changes: object, areaName: string) => void
-
Änderungen
Objekt
-
areaName
String
-