chrome.storage

Opis

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

Uprawnienia

storage

Przegląd

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.

Mimo że rozszerzenia mogą korzystać z interfejsu [Storage][mdn-storage] (dostępnego z window.localStorage) w niektórych kontekstach (wyskakujące okienko i na innych stronach HTML), 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 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. Utwórz dokument poza ekranem z procedurą konwersji i modułem obsługi [onMessage][on-message].
  2. Dodaj rutynę konwersji do dokumentu poza ekranem.
  3. W skrypcie service worker rozszerzenia sprawdź dane pod adresem chrome.storage.
  4. Jeśli Twoje dane nie zostaną znalezione, [create][create-offscreen] użyj funkcji poza ekranem i wywołaj metodę [sendMessage()][send-message], 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 [Miejsce na dane i pliki cookie][miejsce na dane i pliki cookie].

Powierzchnie magazynowe

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

storage.local
Dane są przechowywane lokalnie i usuwane po usunięciu rozszerzenia. Ograniczenie limitu to 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. 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. Rozważ użycie tej opcji, aby zachować ustawienia użytkowników w zsynchronizowanych przeglądarkach.
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(). Ograniczenie limitu to około 10 MB. Rozważ użycie jej do przechowywania zmiennych globalnych w uruchomieniach skryptu service worker.
storage.managed
Administratorzy mogą konfigurować ustawienia rozszerzenia pomocniczego w środowisku zarządzanym za pomocą schematu i zasad przedsiębiorstwa. Ten obszar pamięci masowej jest tylko do odczytu.

Plik manifestu

Aby używać 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 magazynowe 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);
});

Aby dowiedzieć się więcej o obszarze pamięci masowej managed, zapoznaj się z plikiem manifestu dotyczącym obszarów przechowywania.

Limity miejsca na dane i ograniczania

Nie traktuj dodawania funkcji do interfejsu Storage API jak umieszczania elementów w dużej ciężarówce. Ilość miejsca na dane to jak wkładanie czegoś do rurki. Rura może już zawierać materiał, a może być nawet wypełniona. Pamiętaj o opóźnieniu między dodaniem miejsca na dane a rzeczywistym nagraniem.

Aby uzyskać szczegółowe informacje na temat ograniczeń miejsca na dane i skutków ich przekroczenia, zapoznaj się z informacjami o limitach dotyczących 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

Ponieważ mechanizmy Service Worker nie zawsze działają, rozszerzenia na platformie Manifest V3 muszą czasami asynchronicznie wczytywać dane 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 rozszerzeń

Aby zobaczyć inne wersje demonstracyjne interfejsu 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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

  • 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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

  • 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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

  • 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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

  • 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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

  • 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 tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.

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,