хром.хранилище

Описание

Используйте API chrome.storage для хранения, получения и отслеживания изменений пользовательских данных.

Разрешения

storage

Обзор

API хранилища предоставляет специфичный для расширения способ сохранения пользовательских данных и состояния. Он похож на API-интерфейсы хранилища веб-платформы ( IndexedDB и Storage ), но был разработан для удовлетворения потребностей расширений в хранилище. Ниже приведены несколько ключевых особенностей:

  • Все контексты расширений, включая работника службы расширений и сценарии содержимого, имеют доступ к API хранилища.
  • Сериализуемые значения JSON хранятся как свойства объекта.
  • API хранилища является асинхронным с операциями массового чтения и записи.
  • Даже если пользователь очистит кеш и историю просмотров, данные сохранятся.
  • Сохраненные настройки сохраняются даже при использовании разделения в режиме инкогнито .
  • Включает эксклюзивную управляемую область хранения только для чтения для корпоративных политик.

Несмотря на то, что расширения могут использовать интерфейс [ Storage ][mdn-storage] (доступный из window.localStorage ) в некоторых контекстах (всплывающее окно и другие HTML-страницы), это не рекомендуется по следующим причинам:

  • Сервисный работник расширения не может получить доступ к Storage .
  • Скрипты контента делят хранилище с главной страницей.
  • Данные, сохраненные с помощью интерфейса Storage , теряются, когда пользователь очищает историю просмотров.

Чтобы переместить данные из API веб-хранилища в API хранилища расширений из сервис-воркера:

  1. Создайте закадровый документ с помощью процедуры преобразования и обработчика [ onMessage ][on-message].
  2. Добавьте процедуру преобразования в закадровый документ.
  3. В рабочем сервисе расширений проверьте chrome.storage на наличие ваших данных.
  4. Если ваши данные не найдены, [создайте][create-offscreen] закадровый документ и вызовите [ sendMessage() ][send-message], чтобы запустить процедуру преобразования.
  5. Внутри обработчика onMessage закадрового документа вызовите процедуру преобразования.

Также есть некоторые нюансы работы API веб-хранилищ в расширениях. Подробную информацию можно найти в статье [Хранилище и файлы cookie][storage-and-cookies].

Складские помещения

API хранилища разделен на следующие четыре сегмента («области хранения»):

storage.local
Данные хранятся локально и удаляются при удалении расширения. Ограничение квоты составляет примерно 10 МБ, но его можно увеличить, запросив разрешение "unlimitedStorage" . Рассмотрите возможность использования его для хранения больших объемов данных.
storage.sync
Если синхронизация включена, данные синхронизируются с любым браузером Chrome, в котором выполнен вход пользователя. Если этот параметр отключен, он ведет себя как storage.local . Chrome сохраняет данные локально, когда браузер находится в автономном режиме, и возобновляет синхронизацию, когда он снова подключается к сети. Ограничение квоты составляет примерно 100 КБ, по 8 КБ на элемент. Рассмотрите возможность использования его для сохранения пользовательских настроек в синхронизированных браузерах.
хранилище.сессия
Хранит данные в памяти на время сеанса браузера. По умолчанию он не доступен сценариям содержимого, но это поведение можно изменить, установив chrome.storage.session.setAccessLevel() . Ограничение квоты составляет примерно 10 МБ. Рассмотрите возможность использования его для хранения глобальных переменных во время выполнения сервисного работника.
хранилище.управляемое
Администраторы могут использовать схему и политики предприятия для настройки параметров поддерживающего расширения в управляемой среде. Эта область хранения доступна только для чтения.

Манифест

Чтобы использовать API хранилища, объявите разрешение "storage" в манифесте расширения. Например:

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

Использование

В следующих примерах демонстрируются local , sync и 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);
});

хранилище.сессия 

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

Дополнительные сведения об managed области хранения см. в разделе Манифест областей хранения .

Ограничения хранения и регулирования

Не думайте о добавлении API хранилища как о помещении вещей в большой грузовик. Думайте о добавлении хранилища как о помещении чего-то в трубу. В трубе может уже быть материал, и она может даже быть заполнена. Всегда учитывайте задержку между добавлением данных в хранилище и фактической записью.

Подробную информацию об ограничениях области хранения и о том, что происходит при их превышении, см. в информации о квотах для sync , local и session .

Варианты использования

В следующих разделах демонстрируются распространенные случаи использования Storage API.

Синхронный ответ на обновления хранилища

Чтобы отслеживать изменения, внесенные в хранилище, вы можете добавить прослушиватель к событию onChanged . Когда что-то меняется в хранилище, это событие срабатывает. Пример кода прослушивает эти изменения:

фон.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}".`
    );
  }
});

Мы можем развить эту идею еще дальше. В этом примере у нас есть страница параметров , которая позволяет пользователю переключать «режим отладки» (реализация здесь не показана). Страница параметров немедленно сохраняет новые настройки в storage.sync , а сервис-воркер использует storage.onChanged чтобы применить настройки как можно скорее.

параметры.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>

варианты.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);

фон.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);
  }
});

Асинхронная предварительная загрузка из хранилища

Поскольку сервис-воркеры не всегда работают, расширениям Manifest V3 иногда требуется асинхронно загружать данные из хранилища перед выполнением своих обработчиков событий. Для этого в следующем фрагменте кода используется асинхронный обработчик событий action.onClicked , который ожидает заполнения глобального storageCache перед выполнением своей логики.

фон.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);
});

Примеры расширений

Чтобы увидеть другие демонстрации Storage API, изучите любой из следующих примеров:

Типы

AccessLevel

Хром 102+

Уровень доступа к хранилищу.

Перечисление

"TRUSTED_CONTEXTS"
Указывает контексты, происходящие из самого расширения.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Указывает контексты, происходящие за пределами расширения.

StorageArea

Характеристики

  • onChanged

    Событие<functionvoidvoid>

    Хром 73+

    Вызывается при изменении одного или нескольких элементов.

    Функция onChanged.addListener выглядит так: 

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

    • перезвонить

      функция

      Параметр callback выглядит так: 

      (changes: object) => void

      • изменения

        объект

  • прозрачный

    пустота

    Обещать

    Удаляет все предметы из хранилища.

    clear функция выглядит так: 

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

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      () => void

    • возвращает

      Обещание<void>

      Хром 88+

      Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • получать

    пустота

    Обещать

    Получает один или несколько элементов из хранилища.

    Функция get выглядит так: 

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

    • ключи

      строка | строка[] | объект необязательный

      Один ключ для получения, список ключей для получения или словарь, определяющий значения по умолчанию (см. описание объекта). Пустой список или объект вернет пустой объект результата. Передайте значение null чтобы получить все содержимое хранилища.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      (items: object) => void

      • предметы

        объект

        Объект с элементами в сопоставлениях ключ-значение.

    • возвращает

      Обещание<объект>

      Хром 88+

      Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • getBytesInUse

    пустота

    Обещать

    Получает объем пространства (в байтах), используемого одним или несколькими элементами.

    Функция getBytesInUse выглядит так: 

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

    • ключи

      строка | строка[] необязательно

      Один ключ или список ключей, для которых нужно получить общее количество использований. Пустой список вернет 0. Введите значение null чтобы получить общее использование всего хранилища.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      (bytesInUse: number) => void

      • байтинусе

        число

        Объем места, используемого в хранилище, в байтах.

    • возвращает

      Обещание<число>

      Хром 88+

      Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • получить ключи

    пустота

    Обещание Chrome 130+

    Получает все ключи из хранилища.

    Функция getKeys выглядит так: 

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

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      (keys: string[]) => void

      • ключи

        нить[]

        Массив с ключами, считанными из хранилища.

    • возвращает

      Обещание<string[]>

      Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • удалять

    пустота

    Обещать

    Удаляет один или несколько элементов из хранилища.

    Функция remove выглядит так: 

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

    • ключи

      строка | нить[]

      Один ключ или список ключей для элементов, которые нужно удалить.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      () => void

    • возвращает

      Обещание<void>

      Хром 88+

      Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • набор

    пустота

    Обещать

    Устанавливает несколько элементов.

    Функция set выглядит так: 

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

    • предметы

      объект

      Объект, который предоставляет каждой паре ключ/значение для обновления хранилища. Любые другие пары ключ/значение в хранилище не будут затронуты.

      Примитивные значения, такие как числа, будут сериализоваться, как и ожидалось. Значения typeof "object" и "function" обычно сериализуются в {} , за исключением Array (сериализуется, как и ожидалось), Date и Regex (сериализуется с использованием их String представления).

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      () => void

    • возвращает

      Обещание<void>

      Хром 88+

      Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

  • setAccessLevel

    пустота

    Обещание Chrome 102+

    Устанавливает желаемый уровень доступа к области хранения. По умолчанию будут только доверенные контексты.

    Функция setAccessLevel выглядит так: 

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

    • параметры доступа

      объект

    • перезвонить

      функция необязательна

      Параметр callback выглядит так: 

      () => void

    • возвращает

      Обещание<void>

      Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

StorageChange

Характеристики

  • новое значение

    любые дополнительные

    Новое значение элемента, если оно существует.

  • старое значение

    любые дополнительные

    Старое значение элемента, если оно существовало.

Характеристики

local

Элементы в local хранилище являются локальными для каждой машины.

Тип

Область хранения и объект

Характеристики

  • QUOTA_BYTES

    10485760

    Максимальный объем (в байтах) данных, который может храниться в локальном хранилище, измеряемый строковой структурой каждого значения плюс длина каждого ключа в формате JSON. Это значение будет игнорироваться, если расширение имеет разрешение unlimitedStorage . Обновления, которые могут привести к превышению этого предела, немедленно завершаются сбоем и устанавливают runtime.lastError при использовании обратного вызова или отклоненное обещание при использовании async/await.

managed

Элементы в области managed хранилища задаются политикой предприятия, настроенной администратором домена, и доступны расширению только для чтения; попытка изменить это пространство имен приводит к ошибке. Информацию о настройке политики см. в разделе Манифест для областей хранения .

Тип

Область хранения

session

Хром 102+ МВ3+

Элементы в области хранения session хранятся в памяти и не сохраняются на диске.

Тип

Область хранения и объект

Характеристики

  • QUOTA_BYTES

    10485760

    Максимальный объем (в байтах) данных, который может храниться в памяти, измеряемый путем оценки использования динамически выделяемой памяти для каждого значения и ключа. Обновления, которые могут привести к превышению этого предела, немедленно завершаются сбоем и устанавливают runtime.lastError при использовании обратного вызова или при отклонении обещания.

sync

Объекты в области хранения sync синхронизируются с помощью Chrome Sync.

Тип

Область хранения и объект

Характеристики

  • MAX_ITEMS

    512

    Максимальное количество элементов, которые можно сохранить в синхронизированном хранилище. Обновления, которые могут привести к превышению этого предела, немедленно завершатся ошибкой и установят runtime.lastError при использовании обратного вызова или при отклонении обещания.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Устарело

    API Storage.sync больше не имеет квоты на устойчивую операцию записи.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800 г.

    Максимальное количество операций set , remove или clear , которые можно выполнять каждый час. Это 1 раз в 2 секунды, что является более низким пределом, чем краткосрочный более высокий предел количества операций записи в минуту.

    Обновления, которые могут привести к превышению этого предела, немедленно завершаются сбоем и устанавливают runtime.lastError при использовании обратного вызова или при отклонении обещания.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    Максимальное количество операций set , remove или clear , которые можно выполнять каждую минуту. Это 2 операции в секунду, что обеспечивает более высокую пропускную способность, чем количество операций записи в час, за более короткий период времени.

    Обновления, которые могут привести к превышению этого предела, немедленно завершаются сбоем и устанавливают runtime.lastError при использовании обратного вызова или при отклонении обещания.

  • QUOTA_BYTES

    102400

    Максимальный общий объем (в байтах) данных, который может храниться в хранилище синхронизации, измеряемый строковой структурой каждого значения в формате JSON плюс длиной каждого ключа. Обновления, которые могут привести к превышению этого предела, немедленно завершаются сбоем и устанавливают runtime.lastError при использовании обратного вызова или при отклонении обещания.

  • QUOTA_BYTES_PER_ITEM

    8192

    Максимальный размер (в байтах) каждого отдельного элемента в синхронизированном хранилище, измеряемый строковой структурой его значения в формате JSON плюс длина его ключа. Обновления, содержащие элементы, превышающие этот предел, немедленно завершатся ошибкой и устанавливают runtime.lastError при использовании обратного вызова или при отклонении обещания.

События

onChanged

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

Вызывается при изменении одного или нескольких элементов.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • изменения

      объект

    • имя области

      нить