chrome.storage

Opis

Interfejs API chrome.storage służy do przechowywania, pobierania i śledzenia zmian w danych użytkownika.

Uprawnienia

storage

Omówienie

Interfejs Storage API zapewnia sposób zachowywania danych i stanu użytkownika specyficzny dla rozszerzenia. Przypomina on interfejsy API do przechowywania danych na platformie internetowej (IndexedDB i Storage), ale został zaprojektowany tak, aby zaspokajać potrzeby rozszerzeń w zakresie miejsca na dane. Oto kilka najważniejszych cech:

  • Wszystkie konteksty rozszerzeń, w tym skrypt usługi rozszerzenia i skrypty treś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 ze zbiorczymi operacjami 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 podczas korzystania z podziału trybu incognito.
  • Obejmuje ekskluzywne zarządzane miejsce na dysku przeznaczone tylko do odczytu na zasady przedsiębiorstwa.

Mimo że rozszerzenia mogą korzystać z interfejsu [Storage][mdn-storage] (dostępnego z poziomu window.localStorage) w niektórych kontekstach (wyskakujących okienkach i 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 współdzielą miejsce na dane ze stroną hostującą.
  • Dane zapisane w interfejsie 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 rozszerzenia z 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ź, 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 przechowywania

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 włączona jest synchronizacja, dane są synchronizowane z dowolną przeglądarką Chrome, w której użytkownik jest zalogowany. Jeśli jest wyłączona, działa tak jak storage.local. Chrome zapisuje dane lokalnie, gdy przeglądarka jest offline, i wznawia synchronizację po powrocie do trybu online. Maksymalny limit wynosi około 100 KB i 8 KB na element. Rozważ użycie tej funkcji, 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 on widoczny dla skryptów treści, ale można to zmienić, ustawiając zasadę chrome.storage.session.setAccessLevel(). Ograniczenie limitu wynosi około 10 MB. Rozważ użycie jej do przechowywania zmiennych globalnych w wielu uruchomieniach mechanizmu Service Worker.
.
.
storage.managed
Administratorzy mogą używać schematu i zasad przedsiębiorstw do konfigurowania ustawień pomocniczego rozszerzenia w środowisku zarządzanym. Ten obszar jest tylko do odczytu.

Plik manifestu

Aby korzystać z interfejsu Storage API, zadeklaruj w rozszerzeniu uprawnienia "storage" manifestu. Na przykład:

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

Wykorzystanie

Poniższe przykłady przedstawiają local, sync oraz session miejsca przechowywania:

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. Rura może już zawierać jakiś materiał, może być nawet wypełnione. 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 dotyczące miejsca na dane, możesz dodać detektor 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 pójść o krok 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 zapisze nowe ustawienia w storage.sync, a skrypcja service worker jak najszybciej stosuje je za pomocą storage.onChanged.

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

Skrypty service worker nie zawsze są uruchomione, dlatego rozszerzenia na platformie Manifest V3 czasami muszą asynchronicznie ładować dane z pamięci przed wykonaniem przez nich modułów obsługi 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 miejsca na dane.

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

    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ść

    nieważne

    Obietnica .

    Usuwa wszystkie elementy z pamięci.

    Funkcja clear wygląda tak: 

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

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      () => void

    • returns

      Obietnica<void>

      Chrome 88 i nowsze .

      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 miejsca na dane.

    Funkcja get wygląda tak: 

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

    • klucze

      string | string[] | obiekt opcjonalny

      Pojedynczy klucz do pobrania, lista kluczy do pobrania lub słownik określający wartości domyślne (zobacz opis obiektu). Pusta lista lub obiekt zwróci pusty obiekt wyniku. 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 mapowaniu par klucz-wartość.

    • returns

      Promise&lt;object&gt;

      Chrome 88 i nowsze .

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

  • getBytesInUse

    nieważne

    Obietnica .

    Pobiera ilość miejsca (w bajtach) zajętego przez co najmniej 1 element.

    Funkcja getBytesInUse wygląda tak: 

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

    • klucze

      string | string[] opcjonalnie

      Pojedynczy klucz lub lista kluczy do pobrania łącznego wykorzystania. Pusta lista zwraca 0. Przekaż null, aby uzyskać całkowite 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

      Promise&lt;number&gt;

      Chrome 88 i nowsze .

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

  • getKeys,

    nieważne

    Obietnica Oczekujący

    Pobiera wszystkie klucze z pamięci.

    Funkcja getKeys wygląda tak: 

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

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      (keys: string[]) => void

      • klucze

        ciąg znaków[]

        Tablica z kluczami odczytywanymi z pamięci masowej.

    • returns

      Promise&lt;string[]&gt;

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

  • usuń

    nieważne

    Obietnica .

    Usuwa co najmniej 1 element z pamięci.

    Funkcja remove wygląda tak: 

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

    • klucze

      string | ciąg znaków[]

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

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      () => void

    • returns

      Obietnica<void>

      Chrome 88 i nowsze .

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

  • zestaw

    nieważne

    Obietnica .

    Ustawia wiele elementów.

    Funkcja set wygląda tak: 

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

    • items

      Obiekt

      Obiekt, który udostępnia każdą parę klucz-wartość, której ma używać aktualizacja pamięci. Nie będzie to miało wpływu na inne pary klucz-wartość przechowywane w pamięci.

      Wartości podstawowe, takie jak liczby, zostaną zserializowane 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 wygląda tak: 

      () => void

    • returns

      Obietnica<void>

      Chrome 88 i nowsze .

      Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą 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 wygląda tak: 

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

    • accessOptions

      Obiekt

      • accessLevel

        AccessLevel

        Poziom dostępu do miejsca na dane.

    • wywołanie zwrotne

      funkcja optional

      Parametr callback wygląda tak: 

      () => 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 występuje nowa wartość.

  • 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ść (w bajtach) danych, które można przechowywać w pamięci lokalnej, mierzona za pomocą ciągu znaków JSON dla każdej wartości i długości każdego klucza. Jeśli rozszerzenie ma uprawnienie unlimitedStorage, ta wartość zostanie zignorowana. Aktualizacje, które spowodowałyby przekroczenie tego limitu, natychmiast kończą się niepowodzeniem i ustawiają runtime.lastError w przypadku używania wywołania zwrotnego lub odrzuconej obietnicy (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. Więcej informacji o konfigurowaniu zasad znajdziesz w artykule Plik manifestu dla obszarów przechowywania.

Typ

StorageArea

session

Chrome 102 lub nowszy MV3 lub nowszy

Elementy w obszarze przechowywania 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óre mogą być przechowywane w pamięci, mierzona przez oszacowanie dynamicznie przydzielanego wykorzystania pamięci dla każdej wartości i klucza. 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 przy użyciu Synchronizacji Chrome.

Typ

StorageArea 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, zostaną natychmiast zakończone niepowodzeniem i ustawionym runtime.lastError przy użyciu wywołania zwrotnego lub w przypadku odrzucenia obietnicy.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Wycofano

    Interfejs storage.sync API nie ma już limitu operacji długotrwałego 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 na 2 sekundy, czyli niższy pułap niż krótkoterminowy wyższy limit zapisu na minutę.

    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ć na minutę. Jest to 2 na sekundę, co zapewnia większą przepustowość niż zapisy na godzinę w krótszym czasie.

    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.

  • QUOTA_BYTES

    102400

    Maksymalna łączna ilość (w bajtach) danych, które mogą być przechowywane w pamięci synchronizacji, mierzona za pomocą ciągu znaków JSON dla każdej wartości i długości każdego klucza. 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.

  • 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