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. Es ähnelt den Speicher-APIs der Webplattform (IndexedDB und Storage), wurde jedoch für die Speicheranforderungen von Erweiterungen entwickelt. Dies sind einige der wichtigsten Funktionen:
- Alle Erweiterungskontexte, einschließlich des Erweiterungs-Service-Workers und der Inhaltsskripte, haben Zugriff auf die Storage API.
- Die serialisierbaren JSON-Werte werden als Objektattribute gespeichert.
- Die Storage API ist mit Lese- und Schreibvorgängen im Bulk asynchron.
- Auch wenn der Nutzer den Cache leert 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.
Obwohl Erweiterungen die [Storage
][mdn-storage]-Oberfläche (über window.localStorage
zugänglich) 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. - Inhaltsskripte teilen sich den Speicherplatz mit der Hostseite.
- Über die
Storage
-Oberfläche gespeicherte Daten 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 eine Konvertierungsroutine 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] auf, um den Conversion-Ablauf zu starten. - Rufen Sie im
onMessage
-Handler des nicht sichtbaren Dokuments die Konvertierungsroutine auf.
Es gibt auch einige Unterschiede bei der Funktionsweise von Web Storage APIs in Erweiterungen. Weitere Informationen finden Sie in der [Speicher und Cookies][storage-and-cookies]
Lagerflächen
Die Storage API ist in die folgenden vier Bereiche („Speicherbereiche“) unterteilt:
storage.local
- Die Daten werden lokal gespeichert und gelöscht, wenn die Erweiterung entfernt wird. Die Kontingentbeschränkung beträgt ungefähr 10 MB, kann aber durch Anfordern der Berechtigung
"unlimitedStorage"
erhöht werden. Erwägen Sie, sie zum Speichern größerer Datenmengen zu verwenden.
storage.sync
- Wenn die Synchronisierung aktiviert ist, werden die Daten mit jedem Chrome-Browser synchronisiert, in dem der Nutzer angemeldet ist. Wenn die Richtlinie 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 sie verwenden, um die Nutzereinstellungen für alle synchronisierten Browser beizubehalten.
- storage.session
- Speichert Daten für die Dauer einer Browsersitzung. Standardmäßig ist sie nicht für Inhaltsskripte sichtbar. Dies kann jedoch durch Festlegen von
chrome.storage.session.setAccessLevel()
geändert werden. Die Kontingentbeschränkung beträgt ungefähr 10 MB. Erwägen Sie, sie zum Speichern globaler Variablen in verschiedenen Service Worker-Ausführungen zu verwenden.
- 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
Deklariere die Berechtigung "storage"
in der Erweiterung, um die Storage API zu verwenden
manifest. 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. Denken Sie darüber nach, quasi wie etwas in eine Rohre stellen. Das Rohr enthält vielleicht bereits Material, möglicherweise sogar gefüllt. Gehen Sie immer von einer Verzögerung zwischen dem Hinzufügen von Speicherplatz und dem tatsächlichen aufgezeichnet.
Weitere Informationen zu Einschränkungen von Speicherbereichen und dazu, was passiert, wenn sie überschritten werden, 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 Speicherplatz ä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,
ermöglicht es dem Nutzer, in einen „Debug-Modus“ Die Implementierung ist 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
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 von 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: <ph type="x-smartling-placeholder"></ph>(callback: function) => {...}
-
callback
Funktion
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>(changes: object) => void
-
Änderungen
Objekt
-
-
-
löschen
voidm
<ph type="x-smartling-placeholder"></ph> VersprechenEntfernt alle Elemente aus dem Speicher.
Die Funktion
clear
sieht so aus: <ph type="x-smartling-placeholder"></ph>(callback?: function) => {...}
-
callback
Funktion optional
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>() => 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
voidm
<ph type="x-smartling-placeholder"></ph> VersprechenRuft ein oder mehrere Elemente aus dem Speicher ab.
Die Funktion
get
sieht so aus: <ph type="x-smartling-placeholder"></ph>(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
Funktion optional
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>(items: object) => void
-
Artikel
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
voidm
<ph type="x-smartling-placeholder"></ph> VersprechenRuft den Speicherplatz (in Byte) ab, der von einem oder mehreren Elementen verwendet wird.
Die Funktion
getBytesInUse
sieht so aus: <ph type="x-smartling-placeholder"></ph>(keys?: string | string[], callback?: function) => {...}
-
Schlüssel
string | string[] optional
Ein einzelner Schlüssel oder eine Liste von Schlüsseln zum Abrufen der Gesamtnutzung. Bei einer leeren Liste wird „0“ zurückgegeben. Übergeben Sie
null
, um die Gesamtnutzung des Speicherplatzes zu erhalten. -
callback
Funktion optional
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>(bytesInUse: number) => void
-
bytesInUse
Zahl
Menge des im Speicher verwendeten Speicherplatzes in Byte.
-
-
Gibt zurück
Promise<number>
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.
-
-
getKeys
voidm
<ph type="x-smartling-placeholder"></ph> Versprechen AusstehendRuft alle Schlüssel aus dem Speicher ab.
Die Funktion
getKeys
sieht so aus: <ph type="x-smartling-placeholder"></ph>(callback?: function) => {...}
-
callback
Funktion optional
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>(keys: string[]) => void
-
Schlüssel
String[]
Array mit Schlüsseln, die aus dem Speicher gelesen werden.
-
-
Gibt zurück
Promise<string[]>
Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.
-
-
Entfernen
voidm
<ph type="x-smartling-placeholder"></ph> VersprechenEntfernt ein oder mehrere Elemente aus dem Speicher.
Die Funktion
remove
sieht so aus: <ph type="x-smartling-placeholder"></ph>(keys: string | string[], callback?: function) => {...}
-
Schlüssel
string | String[]
Ein einzelner Schlüssel oder eine Liste von Schlüsseln für zu entfernende Elemente.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>() => 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.
-
-
set
voidm
<ph type="x-smartling-placeholder"></ph> VersprechenLegt mehrere Elemente fest.
Die Funktion
set
sieht so aus: <ph type="x-smartling-placeholder"></ph>(items: object, callback?: function) => {...}
-
Artikel
Objekt
Ein Objekt, das jedem Schlüssel/Wert-Paar zum Aktualisieren des Speichers zugeordnet ist. Alle anderen Schlüssel/Wert-Paare im Speicher sind davon nicht betroffen.
Einfache Werte wie Zahlen werden wie erwartet serialisiert. Werte mit einem
typeof
"object"
und"function"
werden normalerweise in{}
serialisiert, mit Ausnahme vonArray
(serialisiert wie erwartet),Date
undRegex
(Serialisierung mit ihrerString
-Darstellung). -
callback
Funktion optional
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>() => 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.
-
-
setAccessLevel
voidm
<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 102 und höherHier legen Sie die gewünschte Zugriffsebene für den Speicherbereich fest. Die Standardeinstellung sind nur vertrauenswürdige Kontexte.
Die Funktion
setAccessLevel
sieht so aus: <ph type="x-smartling-placeholder"></ph>(accessOptions: object, callback?: function) => {...}
-
accessOptions
Objekt
-
accessLevel
Die Zugriffsebene des Speicherbereichs.
-
-
callback
Funktion optional
Der Parameter
callback
sieht so aus: <ph type="x-smartling-placeholder"></ph>() => void
-
Gibt zurück
Versprechen<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
Beliebige optionale
Der neue Wert des Elements, falls ein neuer Wert vorhanden ist.
-
oldValue
Beliebige optionale
Der alte Wert des Elements, falls ein alter Wert vorhanden war.
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 dazu führen, dass dieses Limit überschritten wird, schlagen sofort fehl und legenruntime.lastError
fest, wenn ein Callback verwendet wird, oder ein abgelehntes Promise, wenn ein async- oder await-Tag verwendet wird.
managed
Die Elemente im Speicherbereich „managed
“ werden durch eine vom Domainadministrator konfigurierte Unternehmensrichtlinie festgelegt und sind für die Erweiterung schreibgeschützt. wenn Sie versuchen, diesen Namespace zu ändern, führt dies 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 Datenmenge (in Byte) an Daten, die im Arbeitsspeicher gespeichert werden können, gemessen durch Schätzung der dynamisch zugewiesenen Arbeitsspeichernutzung jedes Werts und Schlüssels. Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet oder ein Promise 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 Synchronisierungsspeicher 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
<ph type="x-smartling-placeholder"></ph> EingestelltFür die storage.sync API gilt kein anhaltendes Kontingent für 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 1 alle 2 Sekunden, ein niedrigerer Höchstwert als der kurzfristig höhere Grenzwert für Schreibvorgänge pro Minute.Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet oder ein Promise 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 sind 2 pro Sekunde, was einen höheren Durchsatz als Schreibvorgänge pro Stunde über einen kürzeren Zeitraum bietet.Aktualisierungen, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet oder ein Promise 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, durch die dieses Limit überschritten wird, schlagen sofort fehl und legen
runtime.lastError
fest, wenn ein Callback verwendet oder ein Promise abgelehnt wird. -
QUOTA_BYTES_PER_ITEM
8192
Die maximale Größe (in Byte) jedes einzelnen Elements im Synchronisierungsspeicher, gemessen durch die JSON-Stringifizierung seines Werts plus seiner Schlüssellänge. Aktualisierungen mit Elementen, die dieses Limit überschreiten, schlagen sofort fehl und es wird
runtime.lastError
festgelegt, wenn ein Callback verwendet oder ein Promise abgelehnt wird.
Ereignisse
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: <ph type="x-smartling-placeholder"></ph>(changes: object, areaName: string) => void
-
Änderungen
Objekt
-
areaName
String
-