chrome.storage

refresh date: 2026-09-25 robots: noindex

Opis

Uprawnienia

Przegląd

Interfejs Storage API umożliwia przechowywanie danych i stanu użytkownika w sposób specyficzny dla rozszerzenia. Jest podobny do interfejsów API platformy internetowej do przechowywania danych (IndexedDB i Storage), ale został zaprojektowany z myślą o potrzebach rozszerzeń w zakresie przechowywania danych. Oto kilka najważniejszych funkcji:

• Wszystkie konteksty rozszerzenia, 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.
• Obejmuje ekskluzywny zarządzany obszar pamięci masowej tylko do odczytu na potrzeby zasad przedsiębiorstwa.

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

1. Utwórz dokument poza ekranem z procedurą konwersji i handlerem [onMessage][on-message].
2. Dodawanie procedury konwersji do dokumentu poza ekranem.
3. W skrypcie service worker rozszerzenia sprawdź chrome.storage swoje dane.
4. Jeśli dane nie zostaną znalezione, [utwórz][create-offscreen] dokument poza ekranem i wywołaj [sendMessage()][send-message], 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][storage-and-cookies].

Obszary przechowywania

Interfejs Storage API jest podzielony na 4 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 ta opcja jest wyłączona, działa tak samo jak storage.local. Gdy przeglądarka jest offline, Chrome zapisuje dane lokalnie i wznawia synchronizację, gdy znów połączysz się z internetem. Limit wynosi około 100 KB, czyli 8 KB na element. Możesz go używać, 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 udostępniany skryptom treści, ale można to zmienić, ustawiając wartość chrome.storage.session.setAccessLevel(). Limit wynosi około 10 MB. Możesz go używać do przechowywania zmiennych globalnych w różnych uruchomieniach skryptu service worker.

storage.managed

Administratorzy mogą używać schematu i zasad Enterprise do konfigurowania ustawień rozszerzenia pomocniczego w środowisku zarządzanym. 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 manifestach obszarów pamięci.

Limity miejsca na dane i ograniczania

Nie myśl o dodawaniu danych do interfejsu Storage API jak o umieszczaniu rzeczy w dużej ciężarówce. Dodawanie danych do pamięci można porównać do wkładania czegoś do rury. Rura może już zawierać materiał, a nawet być wypełniona. Zawsze zakładaj opóźnienie między dodaniem danych do pamięci a ich faktycznym zapisaniem.

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

Przypadki użycia

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

Synchroniczna odpowiedź na aktualizacje pamięci masowej

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

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 rozwinąć ten pomysł. W tym przykładzie mamy stronę opcji, która umożliwia użytkownikowi włą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;
  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

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

• Rozszerzenie wyszukiwania globalnego
• Rozszerzenie alarmu wodnego

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