chrome.storage

refresh date: 2026-09-25 robots: noindex

Opis

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

Uprawnienia

storage

Przegląd

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.

Chociaż rozszerzenia mogą w niektórych kontekstach (wyskakujące okienka i inne strony HTML) używać interfejsu [Storage][mdn-storage] (dostępnego z window.localStorage), 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 zostaną utracone, 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:

  1. Utwórz dokument poza ekranem z procedurą konwersji i modułem obsługi [onMessage][on-message].
  2. Dodaj procedurę konwersji do dokumentu poza ekranem.
  3. W skrypcie service worker rozszerzenia sprawdź, czy są dostępne dane chrome.storage.
  4. Jeśli nie znajdziesz danych, [utwórz][create-offscreen] dokument poza ekranem i wywołaj [sendMessage()][send-message], aby rozpocząć procedurę konwersji.
  5. W procedurze obsługi onMessage dokumentu poza ekranem wywołaj procedurę konwersji.

Istnieją też pewne niuanse związane z działaniem interfejsów API pamięci masowej w rozszerzeniach. Więcej informacji znajdziesz w artykule [Pamięć i pliki cookie][storage-and-cookies].

Miejsca na dane

Interfejs Storage API jest podzielony na 4 zasobniki („obszary pamięci”):

storage.local
Dane są przechowywane lokalnie i usuwane po usunięciu rozszerzenia. Limit wynosi 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. 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. Rozważ użycie go, aby zachować ustawienia użytkownika w zsynchronizowanych przeglądarkach.
storage.session
Przechowuje dane w pamięci przez czas trwania sesji przeglądarki. Domyślnie nie jest on widoczny dla skryptów treści, ale można to zmienić, ustawiając chrome.storage.session.setAccessLevel(). Limit wynosi około 10 MB. Rozważ użycie go do przechowywania zmiennych globalnych między uruchomieniami skryptu service worker.
storage.managed
Administratorzy mogą używać schematu i zasad firmowych do konfigurowania ustawień rozszerzenia pomocniczego w zarządzanym środowisku. Ten obszar pamięci jest tylko do odczytu.

Plik manifestu

Aby korzystać z 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 pamięci 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);
});

Więcej informacji o obszarze pamięci managed znajdziesz w artykule Manifest dla obszarów pamięci.

Limity miejsca na dane i ograniczania przepustowości

Nie myśl o dodawaniu danych do interfejsu Storage API jak o ładowaniu ich na dużą ciężarówkę. Dodawanie danych do pamięci masowej można porównać do wkładania czegoś do rury. W rurze może już znajdować się materiał, a nawet może być ona wypełniona. Zawsze zakładaj, że między dodaniem danych do pamięci masowej a ich faktycznym zapisaniem występuje opóźnienie.

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.

Przypadki użycia

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

Synchroniczna odpowiedź na aktualizacje miejsca na dane

Aby śledzić zmiany wprowadzone w pamięci, możesz dodać 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:

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ść 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;
  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);
  }
});

Asynchroniczne wstępne wczytywanie z pamięci masowej

Skrypty service worker nie zawsze działają, więc rozszerzenia platformy Manifest V3 czasami muszą 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 = 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

Chrome 102 lub nowsza wersja

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

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

chrome.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