Opis
Przechowuj, pobieraj i śledź zmiany danych użytkownika za pomocą interfejsu chrome.storage
API.
Uprawnienia
storage
Przegląd
Interfejs Storage API umożliwia zachowywanie danych i stanu użytkownika zależnie od rozszerzenia. Jest on podobny do interfejsów API pamięci masowej dostępnych na platformie internetowej (IndexedDB i Storage), ale został zaprojektowany tak, aby zaspokajać potrzeby rozszerzeń w zakresie miejsca na dane. Oto kilka najważniejszych funkcji:
- Wszystkie konteksty rozszerzeń, w tym skrypt service worker rozszerzenia i skrypty treści, mają dostęp do interfejsu Storage API.
- Wartości, które można serializować, w formacie JSON są przechowywane jako właściwości obiektów.
- Interfejs Storage API jest asynchroniczny podczas operacji zbiorczego odczytu i zapisu.
- Nawet jeśli użytkownik wyczyści pamięć podręczną i historię przeglądania, dane pozostaną.
- Zapisane ustawienia pozostają zachowane nawet w przypadku podziału incognito.
- Dostęp do zarządzanego miejsca na dane przeznaczonego tylko do odczytu na potrzeby zasad przedsiębiorstwa.
Mimo że rozszerzenia mogą korzystać z interfejsu [Storage
][mdn-storage] (dostępnego z window.localStorage
) w niektórych kontekstach (wyskakujące okienko i na innych stronach HTML), nie jest to zalecane z tych powodów:
- Skrypt service worker rozszerzenia nie ma dostępu do:
Storage
. - Skrypty treści współdzielą pamięć ze stroną hosta.
- Dane zapisane za pomocą interfejsu
Storage
zostają utracone, gdy użytkownik wyczyści historię przeglądania.
Aby przenieść dane z interfejsów Web Storage API do interfejsów API pamięci masowej rozszerzeń z poziomu skryptu service worker:
- Utwórz dokument poza ekranem z procedurą konwersji i modułem obsługi [
onMessage
][on-message]. - Dodaj rutynę konwersji do dokumentu poza ekranem.
- W skrypcie service worker rozszerzenia sprawdź dane pod adresem
chrome.storage
. - Jeśli Twoje dane nie zostaną znalezione, [create][create-offscreen] użyj funkcji poza ekranem i wywołaj metodę [
sendMessage()
][send-message], aby rozpocząć procedurę konwersji. - W module obsługi
onMessage
dokumentu poza ekranem wywołaj rutynę konwersji.
Obowiązują też pewne niuanse dotyczące działania interfejsów Web Storage API w rozszerzeniach. Więcej informacji znajdziesz w artykule [Miejsce na dane i pliki cookie][miejsce na dane i pliki cookie].
Powierzchnie magazynowe
Interfejs Storage API jest podzielony na następujące 4 zasobniki („obszary pamięci”):
storage.local
- Dane są przechowywane lokalnie i usuwane po usunięciu rozszerzenia. Ograniczenie limitu to około 10 MB, ale można go zwiększyć, prosząc o uprawnienie
"unlimitedStorage"
. Rozważ użycie go do przechowywania większych ilości danych.
storage.sync
- Jeśli synchronizacja jest włączona, dane są synchronizowane z każdą przeglądarką Chrome, w której użytkownik jest zalogowany. Gdy ta opcja jest wyłączona, funkcja działa tak jak
storage.local
. Chrome zapisuje dane lokalnie, gdy przeglądarka jest offline, i wznawia synchronizację, gdy znów połączy się z siecią. Ograniczenie limitu to około 100 KB, czyli 8 KB na element. Rozważ użycie tej opcji, aby zachować ustawienia użytkowników w zsynchronizowanych przeglądarkach.
- storage.session
- Przechowuje dane w pamięci na czas sesji przeglądarki. Domyślnie nie jest ono dostępne dla skryptów treści, ale można to zmienić, ustawiając wartość
chrome.storage.session.setAccessLevel()
. Ograniczenie limitu to około 10 MB. Rozważ użycie jej do przechowywania zmiennych globalnych w uruchomieniach skryptu service worker.
- storage.managed
- Administratorzy mogą konfigurować ustawienia rozszerzenia pomocniczego w środowisku zarządzanym za pomocą schematu i zasad przedsiębiorstwa. Ten obszar pamięci masowej jest tylko do odczytu.
Plik manifestu
Aby używać interfejsu Storage API, zadeklaruj uprawnienie "storage"
w pliku manifestu rozszerzenia. Na przykład:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Wykorzystanie
Poniższe przykłady pokazują obszary magazynowe local
, sync
i 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);
});
Aby dowiedzieć się więcej o obszarze pamięci masowej managed
, zapoznaj się z plikiem manifestu dotyczącym obszarów przechowywania.
Limity miejsca na dane i ograniczania
Nie traktuj dodawania funkcji do interfejsu Storage API jak umieszczania elementów w dużej ciężarówce. Ilość miejsca na dane to jak wkładanie czegoś do rurki. Rura może już zawierać materiał, a może być nawet wypełniona. Pamiętaj o opóźnieniu między dodaniem miejsca na dane a rzeczywistym nagraniem.
Aby uzyskać szczegółowe informacje na temat ograniczeń miejsca na dane i skutków ich przekroczenia, zapoznaj się z informacjami o limitach dotyczących sync
, local
i session
.
Przypadki użycia
W poniższych sekcjach podano typowe przypadki użycia interfejsu Storage API.
Synchroniczna odpowiedź na aktualizacje dotyczące miejsca na dane
Aby śledzić zmiany wprowadzone w pamięci, dodaj detektor do zdarzenia onChanged
. Zdarzenie to jest uruchamiane, gdy cokolwiek zmieni się w pamięci masowej. Przykładowy kod wykrywa te zmiany:
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}".`
);
}
});
Możemy pójść o krok dalej. W tym przykładzie mamy stronę opcji, która pozwala użytkownikowi przełączyć „tryb debugowania” (implementacja nie jest tu widoczna). Na stronie opcji nowe ustawienia są natychmiast zapisywane w storage.sync
, a skrypt service worker korzysta z metody storage.onChanged
, aby jak najszybciej je zastosować.
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);
}
});
Wstępne wczytywanie asynchroniczne z pamięci masowej
Ponieważ mechanizmy Service Worker nie zawsze działają, rozszerzenia na platformie Manifest V3 muszą czasami asynchronicznie wczytywać dane z pamięci, zanim wykonają moduły obsługi zdarzeń. Aby to zrobić, ten fragment kodu korzysta z asynchronicznego modułu obsługi zdarzeń action.onClicked
, który czeka na wypełnienie globalnego storageCache
przed wykonaniem jego logiki.
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);
});
Przykłady rozszerzeń
Aby zobaczyć inne wersje demonstracyjne interfejsu Storage API, zapoznaj się z tymi przykładami:
Typy
AccessLevel
Poziom dostępu do miejsca na dane.
Typ wyliczeniowy
"TRUSTED_CONTEXTS"
Określa konteksty pochodzące z samego rozszerzenia.
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Określa konteksty pochodzące spoza rozszerzenia.
StorageArea
Właściwości
-
onChanged
Zdarzenie<functionvoidvoid>
Chrome w wersji 73 i nowszychUruchamiane po zmianie co najmniej jednego elementu.
Funkcja
onChanged.addListener
wygląda tak:(callback: function) => {...}
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(changes: object) => void
-
Zmiany
obiekt
-
-
-
wyczyść
void
ObietnicaPowoduje usunięcie wszystkich elementów z pamięci masowej.
Funkcja
clear
wygląda tak:(callback?: function) => {...}
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
-
returns
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
-
-
get
void
ObietnicaPobiera co najmniej 1 element z miejsca na dane.
Funkcja
get
wygląda tak:(keys?: string | string[] | object, callback?: function) => {...}
-
klucze
ciąg | ciąg[] | obiekt opcjonalny
Pojedynczy klucz do pobrania, lista kluczy do pobrania lub słownik z wartościami domyślnymi (patrz opis obiektu). Pusta lista lub obiekt zwróci pusty obiekt wyniku. Przekaż
null
, aby pobrać całą zawartość pamięci. -
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(items: object) => void
-
items
obiekt
Obiekt z elementami w mapowaniach par klucz-wartość.
-
-
returns
Promise<object>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
-
-
getBytesInUse
void
ObietnicaPobiera ilość miejsca (w bajtach) używaną przez co najmniej 1 element.
Funkcja
getBytesInUse
wygląda tak:(keys?: string | string[], callback?: function) => {...}
-
klucze
string | string[] opcjonalny
Pojedynczy klucz lub lista kluczy, dla których można sprawdzić całkowite wykorzystanie. Jeśli lista jest pusta, zwracana jest wartość 0. Przekaż
null
, aby poznać łączne wykorzystanie miejsca na dane. -
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(bytesInUse: number) => void
-
bytesInUse
Liczba
Ilość miejsca w pamięci (w bajtach).
-
-
returns
Obietnica<number>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
-
-
usuwania
void
ObietnicaUsuwa co najmniej 1 element z pamięci.
Funkcja
remove
wygląda tak:(keys: string | string[], callback?: function) => {...}
-
klucze
string | string[]
Pojedynczy klucz lub lista kluczy do usunięcia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
-
returns
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
-
-
zestaw
void
ObietnicaUstawia wiele elementów.
Funkcja
set
wygląda tak:(items: object, callback?: function) => {...}
-
items
obiekt
Obiekt, który przypisuje każdej parze klucz/wartość do aktualizacji miejsca na dane. Nie będzie to miało wpływu na inne pary klucz-wartość przechowywane w pamięci masowej.
Wartości podstawowe, takie jak liczby, zostaną zserializowane zgodnie z oczekiwaniami. Wartości z
typeof
"object"
i"function"
są zwykle serializowane do{}
z wyjątkiemArray
(serializowany zgodnie z oczekiwaniami),Date
iRegex
(serial z użyciem ich reprezentacjiString
). -
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
-
returns
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
-
-
setAccessLevel
void
Obietnica Chrome w wersji 102 lub nowszejUstawia odpowiedni poziom dostępu do miejsca na dane. Wartość domyślna to tylko zaufane konteksty.
Funkcja
setAccessLevel
wygląda tak:(accessOptions: object, callback?: function) => {...}
-
accessOptions
obiekt
-
accessLevel
Poziom dostępu do miejsca na dane.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
-
returns
Promise<void>
Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
-
StorageChange
Właściwości
-
newValue
dowolne opcjonalne
Nowa wartość elementu, jeśli pojawiła się nowa wartość.
-
oldValue
dowolne opcjonalne
Stara wartość elementu, jeśli istniała ona wcześniej.
Właściwości
local
Elementy w obszarze pamięci local
są lokalne dla każdego komputera.
Typ
StorageArea i obiekt
Właściwości
-
QUOTA_BYTES
10485760
Maksymalna ilość (w bajtach) danych, które mogą być przechowywane w pamięci lokalnej, mierzona przez ciąg tekstowy JSON zawierający każdą wartość plus długość każdego klucza. Ta wartość zostanie zignorowana, jeśli rozszerzenie ma uprawnienie
unlimitedStorage
. Aktualizacje, które spowodowałyby przekroczenie tego limitu, nie powiodą się natychmiast i ustawiąruntime.lastError
w przypadku korzystania z wywołania zwrotnego lub odrzucone obietnice w przypadku korzystania z metody asynchronicznej/oczekującej.
managed
Elementy w obszarze pamięci masowej managed
są ustawiane przez zasadę przedsiębiorstwa skonfigurowane przez administratora domeny i są dostępne tylko do odczytu dla rozszerzenia. Próba modyfikacji tej przestrzeni nazw kończy się błędem. Informacje o konfigurowaniu zasad znajdziesz w artykule Plik manifestu dotyczący obszarów przechowywania.
Typ
session
Elementy w obszarze pamięci session
są przechowywane w pamięci i nie zostaną zachowane na dysku.
Typ
StorageArea i obiekt
Właściwości
-
QUOTA_BYTES
10485760
Maksymalna ilość (w bajtach) danych, która może być przechowywana w pamięci, zmierzona przez oszacowanie dynamicznie alokowanego wykorzystania pamięci dla każdej wartości i każdego klucza. Aktualizacje, które spowodowałyby przekroczenie tego limitu, nie powiodą się natychmiast i ustawią
runtime.lastError
w przypadku korzystania z wywołania zwrotnego lub odrzucenia obietnicy.
sync
Elementy w obszarze pamięci sync
są synchronizowane przy użyciu Synchronizacji Chrome.
Typ
StorageArea i obiekt
Właściwości
-
MAX_ITEMS
512
Maksymalna liczba elementów, które mogą być przechowywane w pamięci synchronizowanej. Aktualizacje, które spowodowałyby przekroczenie tego limitu, będą natychmiast kończyć się niepowodzeniem i ustawią
runtime.lastError
w przypadku korzystania z wywołania zwrotnego lub odrzucenia obietnicy. -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
WycofanoInterfejs Storage.sync API nie ma już limitu długotrwałych operacji zapisu.
-
MAX_WRITE_OPERATIONS_PER_HOUR
1800
Maksymalna liczba operacji
set
,remove
lubclear
, które można wykonać w każdej godzinie. Jest to 1 co 2 sekundy, czyli niższy limit niż krótkoterminowy wyższy limit zapisów na minutę.Aktualizacje, które spowodowałyby przekroczenie tego limitu, nie powiodą się natychmiast i ustawią
runtime.lastError
w przypadku korzystania z wywołania zwrotnego lub odrzucenia obietnicy. -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
Maksymalna liczba operacji
set
,remove
lubclear
, które mogą być wykonywane w każdej minucie. Jest to 2 na sekundę, co daje większą przepustowość niż zapisy na godzinę w krótszym okresie.Aktualizacje, które spowodowałyby przekroczenie tego limitu, nie powiodą się natychmiast i ustawią
runtime.lastError
w przypadku korzystania z wywołania zwrotnego lub odrzucenia obietnicy. -
QUOTA_BYTES
102400
Maksymalna łączna ilość (w bajtach) danych, które mogą być przechowywane w pamięci synchronizacji, mierzona przez ciąg tekstowy JSON dla każdej wartości plus długość każdego klucza. Aktualizacje, które spowodowałyby przekroczenie tego limitu, nie powiodą się natychmiast i ustawią
runtime.lastError
w przypadku korzystania z wywołania zwrotnego lub odrzucenia obietnicy. -
QUOTA_BYTES_PER_ITEM
8192
Maksymalny rozmiar (w bajtach) każdego elementu w pamięci synchronizacji mierzony za pomocą ciągu tekstowego JSON zawierającego jego wartość plus długość klucza. Aktualizacje zawierające elementy powyżej tego limitu zakończą się niepowodzeniem i ustawią
runtime.lastError
w przypadku korzystania z wywołania zwrotnego lub odrzucenia obietnicy.
Wydarzenia
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
Uruchamiane po zmianie co najmniej jednego elementu.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(changes: object, areaName: string) => void
-
Zmiany
obiekt
-
areaName
string,
-