chrome.storage

Opis

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

Uprawnienia

storage

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

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

Pojęcia i wykorzystanie

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.

Czy rozszerzenia mogą korzystać z interfejsów Web Storage API?

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

  • Instancje robocze usługi rozszerzeń nie mogą używać interfejsu Web Storage API.
  • Skrypty treści współdzielą miejsce na dane ze stroną hostującą.
  • Dane zapisane przez 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 rozszerzenia z skryptu service worker:

  1. Przygotuj stronę html i plik skryptu poza ekranem dokumentu. Plik skryptu powinien zawierać rutynę konwersji i moduł obsługi onMessage.
  2. W skrypcie service worker rozszerzenia sprawdź swoje dane w usłudze chrome.storage.
  3. Jeśli nie uda się znaleźć danych, zadzwoń pod numer createDocument().
  4. Po zrealizowaniu zwrotu wywołaj metodę sendMessage(), aby rozpocząć rutynę konwersji.
  5. W module obsługi onMessage dokumentu poza ekranem wywołaj rutynę konwersji.

Istnieją też pewne niuanse w działaniu interfejsów API do przechowywania danych w internecie w rozszerzeniach. Więcej informacji: Miejsce na dane i pliki cookie.

Miejsca przechowywania

Interfejs Storage API jest podzielony na te obszary pamięci masowej:

storage.local
Dane są przechowywane lokalnie i są usuwane po usunięciu rozszerzenia. Limit miejsca na dane wynosi 10 MB (5 MB w Chrome w wersji 113 i starszych), ale można go zwiększyć, prosząc o uprawnienie "unlimitedStorage". Do przechowywania większych ilości danych zalecamy używanie funkcji storage.local.
storage.managed
Zarządzane miejsce na dane to miejsce tylko do odczytu dla rozszerzeń zainstalowanych za pomocą zasad i zarządzane przez administratorów systemu przy użyciu schematu zdefiniowanego przez programistę i zasad firmowych. Zasady są podobne do opcji, ale są konfigurowane przez administratora systemu, a nie przez użytkownika, dzięki czemu można wstępnie skonfigurować rozszerzenie dla wszystkich użytkowników w organizacji. Informacje o zasadach znajdziesz w dokumentacji dla administratorów. Więcej informacji o miejscu do przechowywania danych w usłudze managed znajdziesz w pliku manifestu dotyczącego obszarów przechowywania.
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(). Limit miejsca na dane wynosi 10 MB (1 MB w Chrome w wersji 111 i starszych). Interfejs storage.session jest jednym z kilku zalecanych dla mechanizmów Service Worker.
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. Zalecamy używanie zasady storage.sync, aby zachować ustawienia użytkownika w zsynchronizowanych przeglądarkach. Jeśli masz do czynienia z poufnymi danymi użytkownika, zamiast tego użyj zasady storage.session.

Limity miejsca na dane i ograniczania

Interfejs Storage API ma te ograniczenia wykorzystania:

  • Przechowywanie danych często wiąże się z kosztami związanymi z wydajnością, a interfejs API uwzględnia limity miejsca na dane. Zalecamy rozważenie wyboru przechowywanych danych, aby nie utracić ich możliwości.
  • Przechowywanie danych może trochę potrwać. Dopracuj strukturę kodu, by uwzględnić ten czas.

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, dodaj 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 działają cały czas, dlatego rozszerzenia na platformie Manifest V3 czasem 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

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

Lokalne

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);
});

Synchronizacja

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 interfejsu Storage API, zapoznaj się z każdym 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

  • 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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 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