Chrome obsługuje teraz standardową przestrzeń nazw browser.* (dostępną od Chrome 148). Stopniowo aktualizujemy dokumentację. Więcej informacji znajdziesz w naszym przewodniku dotyczącym przejścia.

Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

browser.storage

Opis

Używaj interfejsu API chrome.storage do przechowywania i pobierania danych użytkowników oraz śledzenia zmian w nich.

Uprawnienia

storage

Aby korzystać z interfejsu Storage API, zadeklaruj uprawnienie "storage" w pliku manifestu rozszerzenia. Na przykład:

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

Przykłady

Poniższe przykłady pokazują obszary pamięci local, sync i session:

Przykład (lokalny)

await browser.storage.local.set({ key: value });
console.log("Value is set");
const result = await browser.storage.local.get(["key"]);
console.log("Value is " + result.key);

Przykład (synchronizacja)

await browser.storage.sync.set({ key: value });
console.log("Value is set");
const result = await browser.storage.sync.get(["key"]);
console.log("Value is " + result.key);

Przykład (sesja)

await browser.storage.session.set({ key: value });
console.log("Value is set");
const result = await browser.storage.session.get(["key"]);
console.log("Value is " + result.key);

Aby zobaczyć inne wersje demonstracyjne interfejsu Storage API, zapoznaj się z tymi przykładami:

Pojęcia i użycie

Interfejs Storage API umożliwia zapisywanie danych i stanu użytkownika w sposób specyficzny dla rozszerzenia. Jest on podobny do interfejsów API pamięci masowej platformy internetowej (IndexedDB i Storage), ale został zaprojektowany z myślą o potrzebach rozszerzeń w zakresie pamięci masowej. 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 obiektu.
Interfejs Storage API jest asynchroniczny i obsługuje operacje zbiorczego odczytu i zapisu.
Dane są zachowywane nawet wtedy, gdy użytkownik wyczyści pamięć podręczną i historię przeglądania.
Zapisane ustawienia są zachowywane nawet podczas korzystania z podzielonego trybu incognito.
Zawiera przeznaczony tylko do odczytu zarządzany obszar pamięci na zasady przedsiębiorstwa.

Czy rozszerzenia mogą używać interfejsów API pamięci masowej w internecie?

Rozszerzenia mogą używać interfejsu Storage (dostępnego z window.localStorage) w niektórych kontekstach (wyskakujące okienka i inne strony HTML), ale nie zalecamy tego z tych powodów:

Skrypty service worker rozszerzeń nie mogą używać interfejsu Web Storage API.
Skrypty treści współdzielą pamięć ze stroną hosta.
Dane zapisane za pomocą interfejsu Web Storage API są tracone, gdy użytkownik wyczyści historię przeglądania.

Aby przenieść dane z interfejsów API pamięci masowej w internecie do interfejsów API pamięci masowej rozszerzeń z poziomu skryptu service worker:

Przygotuj stronę HTML i plik skryptu dokumentu poza ekranem. Plik skryptu powinien zawierać procedurę konwersji i moduł obsługi onMessage.
W skrypcie service worker rozszerzenia sprawdź, czy dane znajdują się w browser.storage.
Jeśli nie znajdziesz swoich danych, zadzwoń pod numer createDocument().
Po rozwiązaniu zwróconego obiektu Promise wywołaj funkcję sendMessage(), aby rozpocząć procedurę konwersji.
W procedurze obsługi onMessage dokumentu poza ekranem wywołaj procedurę konwersji.

Istnieją też pewne niuanse dotyczące działania interfejsów API pamięci masowej w rozszerzeniach. Więcej informacji znajdziesz w artykule Pamięć i pliki cookie.

Limity miejsca na dane i ograniczania przepustowości

Interfejs Storage API ma limity wykorzystania:

Przechowywanie danych wiąże się z kosztami wydajności, a interfejs API obejmuje limity miejsca na dane. Zaplanuj, jakie dane chcesz przechowywać, aby zachować miejsce na dane.
Zapisywanie może trochę potrwać. Struktura kodu powinna uwzględniać ten czas.

Szczegółowe informacje o ograniczeniach miejsca na dane i o tym, co się dzieje po ich przekroczeniu, znajdziesz w informacjach o limitach dotyczących sync, local i session.

Miejsca na dane

Interfejs Storage API jest podzielony na te obszary pamięci:

Lokalne

Dane są przechowywane lokalnie i usuwane po usunięciu rozszerzenia. Limit miejsca na dane wynosi 10 MB (5 MB w Chrome 113 i starszych wersjach), ale można go zwiększyć, prosząc o uprawnienie "unlimitedStorage". Do przechowywania większych ilości danych zalecamy używanie storage.local. Domyślnie jest on widoczny dla skryptów treści, ale można to zmienić, wywołując funkcję browser.storage.local.setAccessLevel().

Zarządzane

Zarządzana pamięć masowa jest przeznaczona tylko do odczytu w przypadku rozszerzeń zainstalowanych na podstawie zasad. Zarządzają nią administratorzy systemu, korzystając ze schematu zdefiniowanego przez dewelopera i zasad firmowych. Zasady są podobne do opcji, ale są konfigurowane przez administratora systemu, a nie przez użytkownika. Dzięki temu rozszerzenie może być wstępnie skonfigurowane dla wszystkich użytkowników w organizacji.

Domyślnie storage.managed jest widoczny dla skryptów treści, ale można to zmienić, wywołując browser.storage.managed.setAccessLevel(). Informacje o zasadach znajdziesz w dokumentacji dla administratorów. Więcej informacji o obszarze pamięci managed znajdziesz w artykule Manifest dla obszarów pamięci.

Sesja

Pamięć sesji przechowuje dane w pamięci, gdy rozszerzenie jest wczytane. Pamięć jest czyszczona, gdy rozszerzenie jest wyłączone, ponownie załadowane lub zaktualizowane, a także po ponownym uruchomieniu przeglądarki. Domyślnie nie jest on widoczny dla skryptów treści, ale można to zmienić, wywołując funkcję browser.storage.session.setAccessLevel(). Limit miejsca na dane to 10 MB (1 MB w Chrome 111 i starszych wersjach).

Interfejs storage.session jest jednym z kilku, które zalecamy w przypadku skryptów service worker.

Synchronizacja

Jeśli użytkownik włączy synchronizację, dane będą synchronizowane ze wszystkimi przeglądarkami Chrome, w których jest zalogowany. Jeśli zasada jest wyłączona, działa tak jak storage.local. Chrome przechowuje dane lokalnie, gdy przeglądarka jest offline, i wznawia synchronizację, gdy znów jest online. Limit wynosi około 100 KB, czyli 8 KB na element.

Zalecamy używanie storage.sync, aby zachować ustawienia użytkownika w zsynchronizowanych przeglądarkach. Jeśli pracujesz z danymi wrażliwymi użytkownika, użyj storage.session. Domyślnie storage.sync jest widoczny dla skryptów treści, ale można to zmienić, wywołując browser.storage.sync.setAccessLevel().

Metody i zdarzenia

Wszystkie obszary pamięci implementują interfejs StorageArea.

get()

Metoda get() umożliwia odczytanie co najmniej 1 klucza z zasobu StorageArea.

getBytesInUse()

Metoda getBytesInUse() pozwala sprawdzić limit wykorzystywany przez StorageArea.

getKeys()

Metoda getKeys() pozwala pobrać wszystkie klucze przechowywane w StorageArea.

remove()

Metoda remove() pozwala usunąć element z StorageArea.

set()

Metoda set() pozwala ustawić element w StorageArea.

setAccessLevel()

Metoda setAccessLevel() umożliwia kontrolowanie dostępu do zasobu StorageArea.

clear()

Metoda clear() pozwala wyczyścić wszystkie dane z obiektu StorageArea.

onChanged

Zdarzenie onChanged umożliwia monitorowanie zmian w StorageArea.

Przypadki użycia

W sekcjach poniżej przedstawiamy typowe przypadki użycia interfejsu Storage API.

Reagowanie na aktualizacje miejsca na dane

Aby śledzić zmiany wprowadzone w pamięci, dodaj detektor do zdarzenia onChanged. Gdy coś się zmieni w pamięci, to zdarzenie zostanie wywołane. Przykładowy kod nasłuchuje tych zmian:

background.js:

browser.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ść jeszcze dalej. W tym przykładzie mamy stronę opcji, która umożliwia użytkownikowi przełączanie „trybu debugowania” (implementacja nie jest tu pokazana). Strona opcji natychmiast zapisuje nowe ustawienia w storage.sync, a skrypt service worker używa storage.onChanged, aby jak najszybciej zastosować ustawienie.

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;
  browser.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await browser.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
browser.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);
  }
});

Asynchroniczne wstępne wczytywanie z pamięci masowej

Skrypty service worker nie działają przez cały czas, dlatego rozszerzenia Manifest V3 muszą czasami asynchronicznie wczytywać dane z pamięci, zanim uruchomią moduły obsługi zdarzeń. Aby to zrobić, poniższy fragment kodu używa asynchronicznego modułu obsługi zdarzeń action.onClicked, który czeka na wypełnienie zmiennej globalnej storageCache przed wykonaniem 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 = browser.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

browser.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;
  browser.storage.sync.set(storageCache);
});

Narzędzia deweloperskie

Dane przechowywane za pomocą interfejsu API możesz wyświetlać i edytować w Narzędziach deweloperskich. Więcej informacji znajdziesz na stronie Wyświetlanie i edytowanie pamięci rozszerzenia w dokumentacji Narzędzi deweloperskich.

Typy

AccessLevel

Chrome 102 lub nowsza browser.* od Chrome 148

Poziom dostępu do obszaru pamięci.

Typ wyliczeniowy

"TRUSTED_CONTEXTS"
Określa konteksty pochodzące z samego rozszerzenia.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Określa konteksty pochodzące spoza rozszerzenia.

StorageChange

Właściwości

newValue

any optional

Nowa wartość elementu, jeśli istnieje.
oldValue

any optional

Stara wartość elementu, jeśli istniała.

Właściwości

local

Elementy w obszarze pamięci local są przechowywane lokalnie na każdym komputerze.

Typ

StorageArea i obiekt

Właściwości

QUOTA_BYTES

10485760

Maksymalna ilość danych (w bajtach), które można przechowywać w pamięci lokalnej, mierzona jako ciąg znaków JSON każdej wartości plus długość każdego klucza. Ta wartość zostanie zignorowana, jeśli rozszerzenie ma uprawnienie unlimitedStorage. Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError, gdy używane jest wywołanie zwrotne, lub odrzuconą obietnicę, gdy używane jest async/await.

managed

Elementy w obszarze pamięci managed są ustawiane przez zasady przedsiębiorstwa skonfigurowane przez administratora domeny i są tylko do odczytu dla rozszerzenia. Próba zmodyfikowania tej przestrzeni nazw spowoduje błąd. Informacje o konfigurowaniu zasad znajdziesz w artykule Manifest dla obszarów pamięci.

Typ

StorageArea

session

Chrome 102 lub nowsza browser.* od Chrome 148 MV3 lub nowsza

Elementy w obszarze pamięci session są przechowywane w pamięci i nie będą zapisywane na dysku.

Typ

StorageArea i obiekt

Właściwości

QUOTA_BYTES

10485760

Maksymalna ilość danych (w bajtach), które mogą być przechowywane w pamięci, mierzona przez oszacowanie wykorzystania dynamicznie przydzielanej pamięci przez każdą wartość i klucz. Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError, gdy używane jest wywołanie zwrotne lub gdy obietnica zostanie odrzucona.

sync

Elementy w obszarze pamięci sync są synchronizowane za pomocą Synchronizacji Chrome.

Typ

StorageArea i obiekt

Właściwości

MAX_ITEMS

512

Maksymalna liczba elementów, które można przechowywać w pamięci synchronizacji. Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast zakończą się niepowodzeniem i ustawią runtime.lastError, gdy używane jest wywołanie zwrotne lub gdy obietnica zostanie odrzucona.
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

1000000

Wycofane

Interfejs API storage.sync nie ma już limitu operacji zapisu.
MAX_WRITE_OPERATIONS_PER_HOUR

1800

Maksymalna liczba operacji set, remove lub clear, które można wykonać w ciągu godziny. To 1 operacja co 2 sekundy, czyli niższy pułap niż krótkoterminowy wyższy limit liczby zapisów na minutę.

Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError, gdy używane jest wywołanie zwrotne lub gdy obietnica zostanie odrzucona.
MAX_WRITE_OPERATIONS_PER_MINUTE

120

Maksymalna liczba operacji set, remove lub clear, które można wykonać w ciągu minuty. To 2 operacje na sekundę, co zapewnia większą przepustowość niż zapisy na godzinę w krótszym okresie.

Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError, gdy używane jest wywołanie zwrotne lub gdy obietnica zostanie odrzucona.
QUOTA_BYTES

102400

Maksymalna łączna ilość danych (w bajtach), które można przechowywać w pamięci synchronizacji, mierzona jako ciąg znaków JSON każdej wartości plus długość każdego klucza. Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError, gdy używane jest wywołanie zwrotne lub gdy obietnica zostanie odrzucona.
QUOTA_BYTES_PER_ITEM

8192

Maksymalny rozmiar (w bajtach) każdego elementu w pamięci synchronizacji, mierzony jako długość ciągu znaków JSON wartości plus długość klucza. Aktualizacje zawierające elementy większe niż ten limit natychmiast się nie powiodą i ustawią runtime.lastError, gdy używane jest wywołanie zwrotne lub gdy obiekt Promise zostanie odrzucony.

Wydarzenia

onChanged

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

Uruchamiane, gdy co najmniej 1 element ulegnie zmianie.

Parametry

callback

funkcja

Parametr callback wygląda tak:
```
(changes: object, areaName: string) => void
```
- poniższych zmian
  
  obiekt
- areaName
  
  tekst

browser.storage Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Opis

Uprawnienia

Przykłady

Przykład (lokalny)

Przykład (synchronizacja)

Przykład (sesja)

Pojęcia i użycie

Czy rozszerzenia mogą używać interfejsów API pamięci masowej w internecie?

Limity miejsca na dane i ograniczania przepustowości

Miejsca na dane

Lokalne

Zarządzane

Sesja

Synchronizacja

Metody i zdarzenia

get()

getBytesInUse()

getKeys()

remove()

set()

setAccessLevel()

clear()

onChanged

Przypadki użycia

Reagowanie na aktualizacje miejsca na dane

Asynchroniczne wstępne wczytywanie z pamięci masowej

Narzędzia deweloperskie

Typy

AccessLevel

Typ wyliczeniowy

StorageChange

Właściwości

Właściwości

local

Typ

Właściwości

managed

Typ

session

Typ

Właściwości

sync

Typ

Właściwości

Wydarzenia

onChanged

Parametry

browser.storage