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 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 robocza 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.

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:

  • Pracownik usługi rozszerzenia nie ma dostępu do Storage.
  • Skrypty treści korzystają z miejsca na stronie hostującej.
  • Dane zapisane za pomocą interfejsu Storage 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. Utwórz dokument poza ekranem z rutyną konwersji i obsługą [onMessage][on-message].
  2. Dodawanie rutyny konwersji do dokumentu poza ekranem.
  3. W rozszerzeniu workera usługi sprawdź chrome.storage, aby znaleźć swoje dane.
  4. Jeśli nie znajdziesz danych, [create][create-offscreen] utwórz dokument offscreen i wywołaj [sendMessage()][send-message], aby rozpocząć procedurę konwersji.
  5. W obsługniku onMessage dokumentu poza ekranem wywołaj procedurę konwersji.

Istnieją też pewne subtelności związane z działaniem interfejsów API pamięci internetowej w rozszerzeniach. Więcej informacji znajdziesz w artykule [Storage and Cookies][storage-and-cookies].

Magazyny

Interfejs Storage API jest podzielony na 4 kategorie („obszary miejsca na dane”):

storage.local
Dane są przechowywane lokalnie i usuwane po usunięciu rozszerzenia. Limit przydziału 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 dowolną przeglądarką Chrome, w której użytkownik jest zalogowany. Jeśli jest wyłączona, działa jak storage.local. Chrome przechowuje dane lokalnie, gdy przeglądarka jest offline, i wznacza synchronizację, gdy znów połączy się z internetem. Limit to około 100 KB, czyli 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 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 kwoty wynosi około 10 MB. Rozważ użycie go do przechowywania zmiennych globalnych w ramach przebiegów usługi workera.
storage.managed
Aby skonfigurować ustawienia rozszerzenia obsługującego w środowisku zarządzanym, administratorzy mogą użyć schematu i zasad korporacyjnych. 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 obszarze magazynowania managed znajdziesz w pliku manifestu.

Limity miejsca na dane i ograniczenia

Nie traktuj dodawania do interfejsu Storage API jako wrzucania rzeczy do dużego samochodu. Dodawanie do magazynu jest jak wkładanie czegoś do rury. W rampie może już być materiał, a może nawet być ona pełna. Zawsze zakładaj opóźnienie między dodaniem danych do pamięci a ich faktycznym zapisaniem.

Szczegółowe informacje o ograniczeniach dotyczących 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 przykłady typowych zastosowań interfejsu Storage API.

Synchroniczna odpowiedź na aktualizacje miejsca na dane

Aby śledzić zmiany wprowadzone w miejscu na dane, możesz dodać do niego detektor dla 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 masowej;

Ponieważ serwisy nie zawsze działają, rozszerzenia z pliku manifestu V3 czasami muszą asynchronicznie wczytywać dane z magazynu przed wykonaniem swoich modułów obsługi 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 swojej 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 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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • 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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • getBytesInUse

    nieważne

    Obietnice

    Pobiera ilość miejsca (w bajtach) używaną przez co najmniej jeden 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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • 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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • usuń

    nieważne

    Obietnice

    usuwa co najmniej 1 element z pamięci.

    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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

  • 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 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 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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy 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 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, 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 pamięci managed są ustawiane przez zasady firmy skonfigurowane przez administratora domeny i są tylko do odczytu dla rozszerzenia. Próba zmodyfikowania tej przestrzeni nazw spowoduje błąd. Informacje o konfigurowaniu zasad znajdziesz w artykule Plik manifestu dla obszarów pamięci.

Typ

StorageArea

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, nie są od razu wykonywane i ustawiają wartość 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.

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