chrome.storage

Opis

Użyj interfejsu API chrome.storage, aby przechowywać, pobierać i śledzić zmiany w danych użytkownika.

Uprawnienia

storage

Omówienie

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

  • Wszystkie konteksty rozszerzenia, w tym usługa workera rozszerzenia i skrypty dotyczące zawartości, mają dostęp do interfejsu Storage API.
  • Serializowane wartości JSON są przechowywane jako właściwości obiektu.
  • Interfejs Storage API jest asynchroniczny w przypadku operacji zbiorczego odczytu i zapisu.
  • Nawet jeśli użytkownik wyczyści pamięć podręczną i historię przeglądania, dane pozostaną zapisane.
  • Zapisane ustawienia są zachowywane nawet wtedy, gdy używasz podziału incognito.
  • Obejmuje obszar zarządzanego miejsca na dane tylko do odczytu przeznaczony do obsługi zasad korporacyjnych.

Chociaż rozszerzenia mogą używać interfejsu [Storage][mdn-storage] (dostępnego z poziomu window.localStorage) w niektórych kontekstach (np. w wyświetlanych oknach i na innych stronach HTML), nie jest to zalecane z tych powodów:

  • Skrypt service worker rozszerzenia nie ma dostępu do elementu Storage.
  • Skrypty treści korzystają z miejsca na stronie hosta.
  • Dane zapisane za pomocą interfejsu Storage są tracone, gdy użytkownik usuwa historię przeglądania.

Aby przenieść dane z interfejsów Web Storage API do interfejsów API pamięci rozszerzenia z skryptu service worker:

  1. Utwórz dokument poza ekranem z rutyną konwersji i obsługą [onMessage][on-message].
  2. Dodawanie procedury konwersji do dokumentu poza ekranem.
  3. W skrypcie service worker rozszerzenia sprawdź, czy chrome.storage zawiera Twoje dane.
  4. Jeśli nie uda się znaleźć danych, [create][create-offscreen] utwórz dokument poza ekranem i wywołaj [sendMessage()][send-message], aby rozpocząć procedurę konwersji.
  5. W module obsługi onMessage dokumentu poza ekranem wywołaj rutynę konwersji.

Są też pewne niuanse dotyczące działania interfejsów API do przechowywania danych w internecie w rozszerzeniach. Więcej informacji: [Miejsce na dane i pliki cookie][miejsce na dane i pliki cookie]

Miejsca na dane

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

storage.local
Dane są przechowywane lokalnie i są usuwane po usunięciu rozszerzenia. Limit wynosi około 10 MB, ale można go zwiększyć, prosząc o uprawnienie "unlimitedStorage". Warto używać jej do przechowywania większych ilości danych.
storage.sync
Jeśli synchronizacja jest włączona, dane są synchronizowane z dowolną przeglądarką Chrome, w której użytkownik jest zalogowany. Jeśli jest wyłączona, działa jak storage.local. Gdy przeglądarka jest offline, Chrome przechowuje dane lokalnie, a gdy wróci do trybu online, wznawia synchronizację. Maksymalny limit wynosi około 100 KB i 8 KB na element. Zastanów się nad jego użyciem, aby zachować ustawienia użytkownika w różnych synchronizowanych przeglądarkach.
storage.session
Przechowuje dane w pamięci na czas sesji przeglądarki. Domyślnie nie jest ona dostępna dla skryptów treści, ale można to zmienić, ustawiając parametr chrome.storage.session.setAccessLevel(). Ograniczenie limitu wynosi około 10 MB. Rozważ użycie go do przechowywania zmiennych globalnych w ramach przebiegów usługi workera.
.
storage.managed
Administratorzy mogą używać schematu i zasad przedsiębiorstw do konfigurowania ustawień pomocniczego rozszerzenia w środowisku zarządzanym. Ten obszar pamięci jest tylko do odczytu.

Plik manifestu

Aby korzystać z interfejsu Storage API, w pliku manifestu rozszerzenia zadeklaruj uprawnienie "storage". 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 miejscu do przechowywania danych w usłudze managed znajdziesz w pliku manifestu dotyczącego obszarów przechowywania.

Limity miejsca na dane i ograniczania

Nie wyobrażaj sobie dodawania interfejsu Storage API do treści w dużej ciężarówce. Warto rozważyć jest jak włożenie czegoś do rury. W rampie może znajdować się materiał, a może nawet być ona pełna. Zawsze zakładaj opóźnienie między momentem dodania miejsca na dane a faktycznym zostały nagrane.

Szczegółowe informacje na temat ograniczeń miejsca na dane oraz tego, co się dzieje po jego 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 miejsca na dane

Aby śledzić zmiany wprowadzone w miejscu na dane, możesz dodać do niego listenera do zdarzenia onChanged. Zdarzenie to uruchamia się, gdy cokolwiek zmieni się w pamięci masowej. 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 jednak pójść jeszcze dalej. W tym przykładzie mamy stronę opcji, na której umożliwia użytkownikowi włączenie „trybu debugowania” (implementacja nie jest tutaj przedstawiona). Strona opcji natychmiast zapisuje nowe ustawienia w pliku storage.sync, a worker usługi używa pliku 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 wczytywanie z pamięci masowej

Ponieważ serwisowe pliki workera nie są zawsze uruchomione, rozszerzenia Manifest V3 muszą czasami asynchronicznie wczytywać dane z magazynu, zanim wykonają swoje przetwarzacze zdarzeń. W tym celu ten fragment kodu używa asynchronicznego modułu obsługi zdarzenia action.onClicked, który czeka na storageCache globalny do zapełnienia przed wykonaniem jej 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, skorzystaj z tych przykładów:

Typy

AccessLevel

Chrome 102 lub nowszy

Poziom dostępu do obszaru magazynowania.

Typ wyliczeniowy

"TRUSTED_CONTEXTS"
Określa konteksty pochodzące z samego rozszerzenia.

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
Określa konteksty pochodzące spoza rozszerzenia.

StorageArea

Właściwości

  • onChanged

    Zdarzenie<functionvoidvoid>

    Chrome 73 lub nowszy

    Wywoływany, gdy zmienia się co najmniej 1 element.

    Funkcja onChanged.addListener wygląda tak: 

    (callback: function) => {...}

    • wywołanie zwrotne

      funkcja

      Parametr callback wygląda tak: 

      (changes: object) => void

      • Zmiany

        Obiekt

  • wyczyść

    nieważne

    Obietnice

    Usuwa wszystkie elementy z pamięci.

    Funkcja clear ma postać:

    (callback?: function) => {...}

    • wywołanie zwrotne

      funkcja optional

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

  • get

    nieważne

    Obietnica

    Pobiera co najmniej 1 element z pamięci.

    Funkcja get ma postać:

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

    • klucze

      string | string[] | object opcjonalnie

      pojedynczy klucz do pobrania, lista kluczy do pobrania lub słownik określający wartości domyślne (patrz opis obiektu); Pusty obiekt lub lista zwróci pusty obiekt wyników. Podaj null, aby uzyskać dostęp do całej zawartości miejsca na dane.

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      (items: object) => void

      • items

        Obiekt

        Obiekt z elementami w mapowaniach par klucz-wartość.

    • returns

      Obietkw<object>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • getBytesInUse

    nieważne

    Obietnica

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

    Funkcja getBytesInUse wygląda tak: 

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

    • klucze

      ciąg znaków | ciągi znaków[] opcjonalnie

      Pojedynczy klucz lub lista kluczy, dla których chcesz uzyskać łączne dane o użyciu. Pusta lista zwraca 0. Przekaż wartość null, aby uzyskać łączne wykorzystanie całego miejsca na dane.

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      (bytesInUse: number) => void

      • bytesInUse

        liczba

        Ilość miejsca wykorzystywanego w pamięci (w bajtach).

    • returns

      Obietnice<number>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • getKeys

    nieważne

    Obietnica Chrome w wersji 130 lub nowszej

    Pobiera wszystkie klucze z pamięci.

    Funkcja getKeys ma postać:

    (callback?: function) => {...}

    • wywołanie zwrotne

      funkcja optional

      Parametr callback ma postać:

      (keys: string[]) => void

      • klucze

        string[]

        Tablica z kluczami odczytanymi z magazynu.

    • returns

      Promise<string[]>

      Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • usuń

    nieważne

    Obietnica

    usuwa co najmniej 1 element z pamięci.

    Funkcja remove ma postać:

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

    • klucze

      ciąg tekstowy | ciągi tekstowe[]

      Pojedynczy klucz lub lista kluczy do usunięcia elementów.

    • wywołanie zwrotne

      funkcja optional

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 88 i nowsze

      Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • zestaw

    nieważne

    Obietnica

    Ustawia wiele elementów.

    Funkcja set ma postać:

    (items: object, callback?: function) => {...}

    • items

      Obiekt

      Obiekt, który zawiera pary klucz-wartość do zaktualizowania pamięci. Nie będzie to miało wpływu na inne pary klucz-wartość w pamięci.

      Wartości proste, takie jak liczby, będą serializowane zgodnie z oczekiwaniami. Wartości z typeof "object" i "function" będą zwykle serializowane do {}, z wyjątkiem Array (serializuje zgodnie z oczekiwaniami), Date i Regex (zserializuje z użyciem ich reprezentacji String).

    • wywołanie zwrotne

      funkcja optional

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • setAccessLevel

    nieważne

    Obietnica Chrome w wersji 102 lub nowszej

    Określa odpowiedni poziom dostępu do obszaru przechowywania. Domyślnie będą to tylko zaufane konteksty.

    Funkcja setAccessLevel ma postać:

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      Obiekt

      • accessLevel

        AccessLevel

        Poziom dostępu do miejsca na dane.

    • wywołanie zwrotne

      funkcja optional

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

StorageChange

Właściwości

  • newValue

    dowolne opcjonalne

    Nowa wartość elementu (jeśli istnieje).

  • oldValue

    dowolne opcjonalne

    Stara wartość elementu (jeśli była taka sama).

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ść danych (w bajtach), które można przechowywać w pamięci lokalnej, mierzona przez konwersję na ciąg JSON każdej wartości oraz długość każdego klucza. Ta wartość zostanie zignorowana, jeśli rozszerzenie ma uprawnienie unlimitedStorage. Aktualizacje, które spowodowałyby przekroczenie tego limitu, kończą się błędem natychmiast i ustawiają wartość runtime.lastError, gdy używasz funkcji wywołania zwrotnego, lub odrzucają obietnicę, jeśli używasz funkcji async/await.

managed

Elementy w obszarze miejsca na dane managed są ustawiane przez zasady przedsiębiorstwa skonfigurowane przez administratora domeny i są dostępne tylko do odczytu rozszerzenia. próba zmodyfikowania tej przestrzeni nazw powoduje błąd. Informacje o konfigurowaniu zasad znajdziesz w artykule Plik manifestu dla obszarów pamięci.

Typ

StorageArea

session

Chrome 102 i nowsze MV3 i nowsze

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

Typ

StorageArea obiekt

Właściwości

  • QUOTA_BYTES

    10485760

    Maksymalna ilość danych (w bajtach), którą można przechowywać w pamięci, mierzona przez oszacowanie dynamicznie przydzielonego wykorzystania pamięci przez każdą wartość i klucz. Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError, gdy używasz wywołania zwrotnego lub obietnicy odrzucasz.

sync

Elementy w obszarze pamięci sync są synchronizowane za pomocą Synchronizacji Chrome.

Typ

StorageArea obiekt

Właściwości

  • MAX_ITEMS

    512

    Maksymalna liczba elementów, które można przechowywać w magazynie synchronizacji. Aktualizacje, które spowodowałyby przekroczenie tego limitu, zostaną odrzucone natychmiast i ustawione na runtime.lastError, gdy używasz wywołania zwrotnego lub gdy obietnica zostanie odrzucona.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Wycofane

    Interfejs API storage.sync nie ma już limitu operacji zapisu ciągłego.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    Maksymalna liczba operacji set, remove lub clear, które można wykonać w każdej godzinie. Oznacza to 1 na 2 sekundy, co jest niższym pułapem niż limit zapisów na minutę na krótki okres.

    Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError, gdy używasz wywołania zwrotnego lub obietnicy odrzucasz.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Maksymalna liczba operacji set, remove lub clear, które można wykonać w ciągu minuty. Oznacza to 2 na sekundę, co zapewnia większą przepustowość niż zapisy na godzinę w krótszym okresie.

    Aktualizacje, które spowodowałyby przekroczenie tego limitu, nie są od razu wykonywane i ustawiają wartość runtime.lastError, gdy używasz wywołania zwrotnego lub gdy obietnica zostanie odrzucona.

  • QUOTA_BYTES

    102400 
     

    Maksymalna łączna ilość danych (w bajtach), jaką można przechowywać w magazynie synchronizacji, mierzona jako suma długości ciągu JSON dla każdej wartości i długości każdego klucza. Aktualizacje, które spowodowałyby przekroczenie tego limitu, nie są od razu wykonywane i ustawiają wartość runtime.lastError, gdy używasz wywołania zwrotnego lub gdy obietnica zostanie odrzucona.

  • QUOTA_BYTES_PER_ITEM

    8192

    Maksymalny rozmiar (w bajtach) każdego elementu w pamięci synchronizacji mierzony za pomocą ciągu znaków JSON jego wartości i długości klucza. Aktualizacje zawierające elementy przekraczające ten limit zostaną natychmiast zakończone niepowodzeniem i zostaną ustawione runtime.lastError, jeśli używasz wywołania zwrotnego lub obietnicy zostaną odrzucone.

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

      ciąg znaków