chrome.storage

refresh date: 2026-09-25 robots: noindex

Описание

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

Разрешения

storage

Обзор

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

  • Все контексты расширения, включая сервис-воркер расширения и скрипты контента, имеют доступ к Storage API.
  • Сериализуемые значения JSON хранятся как свойства объекта.
  • Storage API – это асинхронный 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].

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

Storage API разделен на четыре сегмента ("области хранения"):

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

Манифест

Чтобы использовать Storage 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);
});

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

Подробнее managed о манифесте для областей хранения…

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

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

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

Примеры использования

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

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

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

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

Эту идею можно развить. В этом примере у нас есть страница настроек, которая позволяет пользователю переключать режим отладки (реализация здесь не показана). Страница параметров сразу сохраняет новые настройки в storage.sync, а сервис-воркер использует 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);
  }
});

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

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

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

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

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

Типы

AccessLevel

Chrome 102 и более поздних версий;

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

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

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

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
Указывает контексты, которые не относятся к расширению.

StorageChange

Свойства

  • newValue

    any optional

    Новое значение объекта (если есть).

  • oldValue

    any optional

    Старое значение объекта (если оно было).

Свойства

local

Объекты в хранилище local являются локальными для каждого компьютера.

Тип

StorageArea и объект

Свойства

  • QUOTA_BYTES

    10485760

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

managed

Объекты в хранилище managed задаются корпоративным правилом, настроенным администратором домена, и доступны расширению только для чтения. Попытка изменить это пространство имен приведет к ошибке. Подробнее о том, как настроить правило…

Тип

StorageArea

sync

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

Тип

StorageArea и объект

Свойства

  • MAX_ITEMS

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1 000 000

    Поддержка прекращена

    Для storage.sync API больше не используется квота на непрерывные операции записи.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

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

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

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

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

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

  • QUOTA_BYTES

    102400

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

События

onChanged

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

Срабатывает, когда изменяется один или несколько элементов.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • Изменения

      Объект

    • areaName

      string