chrome.storage

Opis

Przechowuj, pobieraj i śledź zmiany danych użytkownika za pomocą interfejsu chrome.storage API.

Uprawnienia

storage

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

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

Pojęcia i zastosowanie

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.

Czy rozszerzenia mogą używać interfejsów Web Storage API?

Rozszerzenia mogą korzystać z interfejsu Storage (dostępnego w window.localStorage) w niektórych kontekstach (wyskakujących okienkach i na innych stronach HTML), ale nie zalecamy korzystania z tego z tych powodów:

  • Skrypty service worker rozszerzenia nie mogą używać interfejsu Web Storage API.
  • Skrypty treści współdzielą pamięć ze stroną hosta.
  • Dane zapisane przy użyciu interfejsu Web Storage API 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:

  1. Przygotuj nieekranową stronę HTML dokumentu i plik skryptu. Plik skryptu powinien zawierać procedurę konwersji i moduł onMessage.
  2. W skrypcie service worker rozszerzenia sprawdź dane w pliku chrome.storage.
  3. Jeśli nie możesz znaleźć danych, zadzwoń pod numer createDocument().
  4. Po rozwiązaniu zwróconej obietnicy wywołaj metodę sendMessage(), aby rozpocząć procedurę konwersji.
  5. 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 Pamięć i pliki cookie.

Powierzchnie magazynowe

Interfejs Storage API jest podzielony na następujące obszary przechowywania:

storage.local
Dane są przechowywane lokalnie i usuwane po usunięciu rozszerzenia. Limit miejsca wynosi 10 MB (5 MB w Chrome 113 i starszych wersjach), ale można go zwiększyć, wysyłając prośbę o uprawnienie "unlimitedStorage". Do przechowywania większej ilości danych zalecamy użycie storage.local.
storage.managed
Pamięć zarządzana to miejsce tylko do odczytu na potrzeby rozszerzeń zainstalowanych zasad i zarządzane przez administratorów systemu przy użyciu schematu zdefiniowanego przez dewelopera i zasad przedsiębiorstwa. Zasady są podobne do opcji, ale są konfigurowane przez administratora systemu, a nie użytkownika, dzięki czemu można wstępnie skonfigurować rozszerzenie dla wszystkich użytkowników w organizacji. Więcej informacji o zasadach znajdziesz na stronie Dokumentacja dla administratorów. Aby dowiedzieć się więcej o obszarze przechowywania danych w usłudze managed, zapoznaj się z plikiem manifestu dotyczącym obszarów przechowywania.
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(). Limit miejsca wynosi 10 MB (1 MB w Chrome 111 i starszych wersjach). Interfejs storage.session jest jednym z kilku elementów, które polecamy w przypadku mechanizmów Service Worker.
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. Aby zachować ustawienia użytkownika w zsynchronizowanych przeglądarkach, zalecamy korzystanie z storage.sync. Jeśli masz do czynienia z poufnymi danymi użytkownika, użyj narzędzia storage.session.

Limity miejsca na dane i ograniczania

Interfejs Storage API ma następujące ograniczenia dotyczące wykorzystania:

  • Przechowywanie danych często wiąże się z kosztami wydajności, a interfejs API uwzględnia limity miejsca na dane. Zalecamy ostrożność podczas zapisywania danych, aby nie utracić możliwości ich przechowywania.
  • Przechowywanie danych może trochę potrwać. Pamiętaj, aby dostosować kod do tego czasu.

Aby dowiedzieć się więcej o ograniczeniach miejsca na dane i skutkach ich przekroczenia, zapoznaj się z informacjami o limitach na sync, local i session.

Przykłady zastosowań

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

Mechanizmy Service Worker nie działają przez cały czas, dlatego rozszerzenia na platformie Manifest V3 muszą czasami wczytywać dane asynchronicznie 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

Poniższe przykłady pokazują obszary magazynowe local, sync i session:

Kampania lokalna

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Synchronizuj

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Sesja

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

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

Typy

AccessLevel

Chrome 102 i nowsze wersje

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 nowszych

    Uruchamiane 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

    Obietnica

    Powoduje 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 wersje

      Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • get

    void

    Obietnica

    Pobiera co najmniej 1 element z miejsca na dane.

    Funkcja get wygląda tak: 

    (keys?: string|string[]|object,callback?: function)=> {...}

    • klucze

      string|string[]|object optional

      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 wersje

      Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • getBytesInUse

    void

    Obietnica

    Pobiera ilość miejsca (w bajtach) używaną przez co najmniej 1 element.

    Funkcja getBytesInUse wygląda tak: 

    (keys?: string|string[],callback?: function)=> {...}

    • klucze

      string|string[] optional

      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 wersje

      Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • usuwania

    void

    Obietnica

    Usuwa co najmniej 1 element z pamięci.

    Funkcja remove wygląda tak: 

    (keys: string|string[],callback?: function)=> {...}

    • klucze

      ciąg|ciąg[]

      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 wersje

      Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • Ustaw

    void

    Obietnica

    Ustawia 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ątkiem Array (serializowany zgodnie z oczekiwaniami), Date i Regex (serial z użyciem ich reprezentacji String).

    • wywołanie zwrotne

      funkcja opcjonalnie

      Parametr callback wygląda tak: 

      ()=>void

    • returns

      Promise<void>

      Chrome 88 i nowsze wersje

      Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • setAccessLevel

    void

    Obietnica Chrome w wersji 102 lub nowszej

    Ustawia 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

        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 w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

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&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

StorageArea

session

Chrome 102 i nowsze MV3 i nowsze

Elementy w obszarze pamięci session są przechowywane w pamięci i nie zostaną zachowane na dysku.

Typ

StorageArea&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&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

    Wycofano

    Interfejs Storage.sync API nie ma już limitu długotrwałych operacji zapisu.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    Maksymalna liczba operacji set, remove lub clear, 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 lub clear, 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,