chrome.storage

Opis

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

Uprawnienia

storage

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

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

Pojęcia i zastosowanie

Interfejs Storage API umożliwia przechowywanie danych i stanu użytkownika w sposób specyficzny dla rozszerzenia. Jest podobny do interfejsów API pamięci platformy internetowej (IndexedDB i Storage), ale został zaprojektowany pod kątem potrzeb rozszerzeń. Oto kilka kluczowych funkcji:

  • Wszystkie konteksty rozszerzenia, w tym usługa workera rozszerzenia i skrypty dotyczące zawartości, mają dostęp do interfejsu Storage API.
  • Wartości zserializowane w formacie 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 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.

Czy rozszerzenia mogą korzystać z interfejsów API pamięci internetowej?

Chociaż rozszerzenia mogą używać interfejsu Storage (dostępnego z poziomu window.localStorage) w niektórych kontekstach (popupy i inne strony HTML), nie zalecamy tego z tych powodów:

  • Skrypty service worker w rozszerzeniach nie mogą korzystać z interfejsu Web Storage API.
  • Skrypty treści korzystają z miejsca na stronie hostującej.
  • Dane zapisane za pomocą interfejsu Web Storage API są tracone, gdy użytkownik usuwa historię przeglądania.

Aby przenieść dane z interfejsów API pamięci masowej w internecie do interfejsów API pamięci masowej w rozszerzeniu z poziomu skryptu service worker:

  1. Przygotuj stronę HTML dokumentu poza ekranem i plik skryptu. Plik skryptu powinien zawierać procedurę konwersji i obsługę onMessage.
  2. W workerze rozszerzenia sprawdź, czy w elementach chrome.storage znajdują się Twoje dane.
  3. Jeśli nie znajdziesz swoich danych, zadzwoń pod numer createDocument().
  4. Po wykonaniu zwróconego obietnica wywołaj funkcję sendMessage(), aby rozpocząć procedurę konwersji.
  5. W obsługniku onMessage dokumentu poza ekranem wywołaj procedurę konwersji.

Istnieją też pewne różnice w działaniu interfejsów API pamięci internetowej w rozszerzeniach. Więcej informacji znajdziesz w artykule Przechowywanie danych i pliki cookie.

Magazyny

Interfejs Storage API jest podzielony na te obszary:

storage.local
Dane są przechowywane lokalnie i usuwane po usunięciu rozszerzenia. Limit miejsca na dane to 10 MB (5 MB w Chrome 113 i starszych wersjach), ale można go zwiększyć, prosząc o uprawnienie "unlimitedStorage". Zalecamy używanie storage.local do przechowywania większych ilości danych.
storage.managed
Zarządzane miejsce na dane to miejsce na dane tylko do odczytu przeznaczone dla rozszerzeń zainstalowanych przez zasady i zarządzanych przez administratorów systemów za pomocą schematu zdefiniowanego przez dewelopera i zasad firmy. Zasady są podobne do opcji, ale konfiguruje je administrator systemu, a nie użytkownik. Dzięki temu rozszerzenie może być wstępnie skonfigurowane dla wszystkich użytkowników organizacji. Informacje o zasadach znajdziesz w dokumentacji dla administratorów. Więcej informacji o obszarze magazynowania managed znajdziesz w pliku manifestu dla obszarów magazynowania.
storage.session
Przechowuje dane w pamięci przez czas trwania 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(). Limit miejsca na dane to 10 MB (1 MB w Chrome 111 i wcześniejszych wersjach). Interfejs storage.session to jeden z kilku zalecanych interfejsów dla usług działających w tle.
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ę. Limit to około 100 KB, czyli 8 KB na element. Zalecamy używanie storage.sync, aby zachować ustawienia użytkownika w różnych synchronizowanych przeglądarkach. Jeśli pracujesz z danymi użytkownika, które są wrażliwe, użyj zamiast tego storage.session.

Limity miejsca na dane i ograniczenia

Interfejs Storage API ma te ograniczenia użytkowania:

  • Przechowywanie danych często wiąże się z kosztami wydajności, a API ma limity miejsca na dane. Zalecamy ostrożność przy przechowywaniu danych, aby nie stracić możliwości ich przechowywania.
  • Przechowywanie może zająć trochę czasu. Pamiętaj, aby uwzględnić ten czas w strukturze kodu.

Szczegółowe informacje o ograniczeniach miejsca na dane i o tym, co się dzieje, gdy zostaną przekroczone, znajdziesz w informacjach o limitach dla sync, local i session.

Przypadki użycia

W następnych sekcjach znajdziesz typowe zastosowania interfejsu Storage API.

Synchroniczna odpowiedź na aktualizacje miejsca na dane

Aby śledzić zmiany wprowadzone w miejscu na dane, dodaj do niego detektor do zdarzenia onChanged. Gdy w miejscu na dane nastąpi jakaś zmiana, zostanie wywołane to zdarzenie. Przykładowy kod reaguje na 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 jednak pójść jeszcze dalej. W tym przykładzie mamy stronę opcji, która umożliwia użytkownikowi przełączanie „trybu debugowania” (nie pokazano implementacji). Strona opcji natychmiast zapisuje nowe ustawienia w storage.sync, a usługa w tle używa 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 wstępne wczytywanie z pamięci;

Ponieważ serwisy nie działają cały czas, rozszerzenia Manifest V3 muszą czasami asynchronicznie wczytywać dane z magazynu, zanim wykonają przetwarzanie swoich przetwarzaczy zdarzeń. W tym celu poniższy fragment kodu używa asynchronicznego przetwarzacza zdarzeń action.onClicked, który czeka na wypełnienie zmiennej globalnej storageCache przed wykonaniem 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 pamięci local, sync i session:

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 demonstracje interfejsu Storage API, zapoznaj się z tymi przykładami:

Typy

AccessLevel

Chrome w wersji 102 lub nowszej

Poziom dostępu do obszaru magazynowania.

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 73 lub nowszy

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

    Funkcja onChanged.addListener ma postać:

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

    • wywołanie zwrotne

      funkcja

      Parametr callback ma postać:

      (changes: object) => void

      • Zmiany

        Obiekt

  • wyczyść

    nieważne

    Obietnice

    Usuwa wszystkie elementy z pamięci.

    Funkcja clear ma postać:

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

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • get

    nieważne

    Obietnice

    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. Przekaż wartość null, aby uzyskać całą zawartość pamięci.

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      (items: object) => void

      • items

        Obiekt

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

    • returns

      Obietkw<object>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • getBytesInUse

    nieważne

    Obietnice

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

    Funkcja getBytesInUse ma postać:

    (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. Pusty list zwróci wartość 0. Przekaż wartość null, aby uzyskać łączne wykorzystanie całego miejsca na dane.

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      (bytesInUse: number) => void

      • bytesInUse

        liczba

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

    • returns

      Obietnice<number>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • getKeys

    nieważne

    Obietnice Chrome 130 lub nowszy

    Pobiera wszystkie klucze z pamięci.

    Funkcja getKeys ma postać:

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

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      (keys: string[]) => void

      • klucze

        string[]

        Tablica z kluczami odczytanymi z magazynu.

    • returns

      Promise<string[]>

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • usuń

    nieważne

    Obietnice

    usuwa co najmniej 1 element z magazynu.

    Funkcja remove ma postać:

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

    • klucze

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

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

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • zestaw

    nieważne

    Obietnice

    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 masowej. 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 wartością typeof "object" i "function" zwykle serializują się jako {}, z wyjątkiem wartości Array (serializacja przebiega zgodnie z oczekiwaniami), Date i Regex (serializacja za pomocą reprezentacji String).

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Chrome 88 lub nowszy

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

  • setAccessLevel

    nieważne

    Obietnica Chrome 102 i nowsze wersje

    Ustawia żądany poziom dostępu do obszaru magazynowania. Domyślnie będą to tylko zaufane konteksty.

    Funkcja setAccessLevel ma postać:

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

    • accessOptions

      Obiekt

      • accessLevel

        AccessLevel

        Poziom dostępu do obszaru magazynowania.

    • wywołanie zwrotne

      function opcjonalny

      Parametr callback ma postać:

      () => void

    • returns

      Obietnica<void>

      Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

StorageChange

Właściwości

  • newValue

    dowolne opcjonalne

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

  • oldValue

    dowolne opcjonalne

    Stara wartość elementu, jeśli była wcześniej ustawiona.

Właściwości

local

Elementy w obszarze pamięci local są lokalne dla każdego komputera.

Typ

StorageArea i obiekt

Właściwości

  • QUOTA_BYTES

    10485760

    Maksymalna ilość danych (w bajtach), którą 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, nie są od razu wykonywane 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 pamięci managed są ustawiane przez zasady firmy skonfigurowane przez administratora domeny i są tylko do odczytu dla rozszerzenia. Próba zmodyfikowania tego obszaru nazw kończy się błędem. 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 i 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, nie są od razu wykonywane i ustawiają wartość runtime.lastError, gdy używasz wywołania zwrotnego lub gdy obietnica zostanie odrzucona.

sync

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

Typ

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

    Wycofany

    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 ciągu godziny. 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, kończą się błędem natychmiast i ustawiają runtime.lastError, gdy używasz wywołania zwrotnego lub gdy obietnica zostanie odrzucona.

  • 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 czasu.

    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 pamięci 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 pojedynczego elementu w magazynie synchronizacji, mierzony jako ciąg znaków w formacie JSON jego wartości plus długość klucza. Aktualizacje zawierające elementy większe niż ten limit zostaną odrzucone natychmiast i ustawione jako runtime.lastError, gdy używasz wywołania zwrotnego lub gdy obietnica zostanie odrzucona.

Wydarzenia

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

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

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (changes: object, areaName: string) => void

    • Zmiany

      Obiekt

    • areaName

      ciąg znaków