browser.storage

Opis

Uprawnienia

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:

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

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

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:

• Rozszerzenie wyszukiwania globalnego
• Rozszerzenie alarmu wodnego

Pojęcia i zastosowanie

Interfejs Storage API zapewnia sposób przechowywania danych i stanu użytkownika, który jest specyficzny dla danego rozszerzenia. Jest podobny do interfejsów API pamięci platformy internetowej (IndexedDB i Storage), ale został zaprojektowany z myślą o potrzebach rozszerzeń w zakresie przechowywania danych. 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ć do formatu JSON, są przechowywane jako właściwości obiektu.
• Interfejs Storage API jest asynchroniczny i umożliwia wykonywanie zbiorczych operacji odczytu i zapisu.
• Nawet jeśli użytkownik wyczyści pamięć podręczną i historię przeglądania, dane pozostaną.
• Zapisane ustawienia są zachowywane nawet podczas korzystania z podzielonego trybu incognito.
• Zawiera ekskluzywny obszar zarządzanej pamięci masowej tylko do odczytu na potrzeby zasad przedsiębiorstwa.

Czy rozszerzenia mogą korzystać z interfejsów Web Storage API?

Rozszerzenia mogą w niektórych kontekstach (wyskakujące okienko i inne strony HTML) korzystać z interfejsu Storage (dostępnego z window.localStorage), 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ęć masową ze stroną hostującą.
• 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 internetowej do interfejsów API pamięci rozszerzeń z poziomu skryptu service worker:

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

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

Limity miejsca na dane i ograniczania przepustowości

Interfejs Storage API ma ograniczenia użytkowania:

• Przechowywanie danych wiąże się z kosztami związanymi z wydajnością, a interfejs API obejmuje limity miejsca na dane. Zaplanuj dane, które chcesz przechowywać, aby zachować miejsce na dane.
• Przenoszenie danych może zająć trochę czasu. Zorganizuj kod tak, aby uwzględniał ten czas.

Szczegółowe informacje o ograniczeniach obszaru pamięci i o tym, co się dzieje po ich przekroczeniu, znajdziesz w informacjach o limitach dla sync, local i session.

Obszary przechowywania

Interfejs Storage API dzieli się 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 w wersji 113 i starszych), 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 ona udostępniana skryptom treści, ale można to zmienić, wywołując funkcję browser.storage.local.setAccessLevel().

Zarządzane

Pamięć zarządzana jest przeznaczona tylko do odczytu w przypadku rozszerzeń zainstalowanych zgodnie z zasadami. Zarządzają nim administratorzy systemów przy użyciu zdefiniowanego przez dewelopera schematu i zasad firmy. Zasady są podobne do opcji, ale konfiguruje je administrator systemu, a nie użytkownik. Dzięki temu rozszerzenie można wstępnie skonfigurować dla wszystkich użytkowników w organizacji.

Domyślnie storage.managed jest udostępniana skryptom 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 manifestach 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 oraz gdy przeglądarka jest ponownie uruchamiana. Domyślnie nie jest on udostępniany skryptom 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 zalecanych przez nas w przypadku skryptów service worker.

Synchronizacja

Jeśli użytkownik włączy synchronizację, dane będą synchronizowane z każdą przeglądarką Chrome, w której jest zalogowany. Jeśli ta opcja jest wyłączona, działa tak samo jak storage.local. Gdy przeglądarka jest offline, Chrome zapisuje dane lokalnie i wznawia synchronizację po ponownym połączeniu z internetem. Limit wynosi około 100 KB, czyli 8 KB na element.

Zalecamy używanie storage.sync, aby zachować ustawienia użytkownika w synchronizowanych przeglądarkach. Jeśli pracujesz z poufnych danymi użytkownika, użyj storage.session. Domyślnie storage.sync jest udostępniana skryptom 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 StorageArea.

getBytesInUse()

Metoda getBytesInUse() umożliwia sprawdzenie limitu wykorzystanego przez StorageArea.

getKeys()

Metoda getKeys() umożliwia pobranie wszystkich kluczy przechowywanych w StorageArea.

remove()

Metoda remove() umożliwia usunięcie elementu z StorageArea.

set()

Metoda set() pozwala ustawić element w StorageArea.

setAccessLevel()

Metoda setAccessLevel() pozwala kontrolować dostęp do StorageArea.

clear()

Metoda clear() umożliwia wyczyszczenie wszystkich danych z StorageArea.

onChanged

Zdarzenie onChanged umożliwia monitorowanie zmian w StorageArea.

Przypadki użycia

W sekcjach poniżej znajdziesz przykłady typowych zastosowań interfejsu Storage API.

Reagowanie na aktualizacje dotyczące miejsca na dane

Aby śledzić zmiany wprowadzone w pamięci, dodaj detektor do zdarzenia onChanged. Gdy w pamięci zmieni się cokolwiek, 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 rozwinąć ten pomysł. W tym przykładzie mamy stronę opcji, która umożliwia użytkownikowi włączenie i wyłączenie „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

Ponieważ skrypty service worker nie działają cały czas, rozszerzenia z Manifestem V3 czasami muszą asynchronicznie wczytywać dane z pamięci, zanim wykonają swoje procedury obsługi zdarzeń. W tym celu poniższy fragment kodu używa asynchronicznego action.onClicked modułu obsługi zdarzeń, który czeka na wypełnienie obiektu storageCache globalnego przed wykonaniem swojej 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.

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