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

Описание

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

Разрешения

storage

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

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

Концепции и использование

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

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

Могут ли расширения использовать API веб-хранилищ?

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

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

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

  1. Подготовьте HTML-страницу внеэкранного документа и файл скрипта. Файл скрипта должен содержать процедуру преобразования и обработчик onMessage .
  2. В расширении service worker проверьте chrome.storage на наличие ваших данных.
  3. Если данные не найдены, вызовите createDocument() .
  4. После того, как возвращенное Promise будет разрешено, вызовите sendMessage() чтобы начать процедуру преобразования.
  5. Внутри обработчика onMessage внеэкранного документа вызовите процедуру преобразования.

Существуют также некоторые нюансы в работе API веб-хранилищ в расширениях. Подробнее см. статью «Хранилище и файлы cookie» .

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

API хранилища разделен на следующие области хранения:

storage.local
Данные хранятся локально и удаляются при удалении расширения. Максимальный объём хранилища составляет 10 МБ (5 МБ в Chrome 113 и более ранних версиях), но его можно увеличить, запросив разрешение "unlimitedStorage" . Для хранения больших объёмов данных рекомендуется использовать storage.local . По умолчанию он доступен скриптам контента, но это поведение можно изменить, вызвав chrome.storage.local.setAccessLevel() .
storage.managed
Управляемое хранилище — это хранилище, доступное только для чтения, предназначенное для расширений, установленных политиками, и управляемое системными администраторами с помощью схемы, определяемой разработчиком, и корпоративных политик. Политики аналогичны параметрам, но настраиваются системным администратором, а не пользователем, что позволяет предварительно настроить расширение для всех пользователей организации. Сведения о политиках см. в разделе «Документация для администраторов» . Подробнее об managed области хранения см. в разделе «Манифест для областей хранения» .
storage.session
Хранит данные в памяти во время загрузки расширения. Хранилище очищается при отключении, перезагрузке или обновлении расширения, а также при перезапуске браузера. По умолчанию оно недоступно для скриптов контента, но это поведение можно изменить, вызвав chrome.storage.session.setAccessLevel() . Ограничение по объёму хранилища составляет 10 МБ (1 МБ в Chrome 111 и более ранних версиях). Интерфейс storage.session — один из нескольких , рекомендуемых нами для сервис-воркеров .
storage.sync
Если синхронизация включена, данные синхронизируются с любым браузером Chrome, в который вошёл пользователь. Если отключена, она ведёт себя как storage.local . Chrome сохраняет данные локально, когда браузер находится в автономном режиме, и возобновляет синхронизацию при повторном подключении к сети. Ограничение квоты составляет приблизительно 100 КБ, по 8 КБ на элемент. Мы рекомендуем использовать storage.sync для сохранения пользовательских настроек во всех синхронизированных браузерах. Если вы работаете с конфиденциальными пользовательскими данными, вместо этого используйте storage.session . По умолчанию storage.sync доступен для скриптов содержимого, но это поведение можно изменить, вызвав chrome.storage.sync.setAccessLevel() .

Лимиты хранения и регулирования

API хранилища имеет следующие ограничения по использованию:

  • Хранение данных часто сопряжено с потерями производительности, а 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 для скорейшего применения настроек.

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

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

DevTools

Вы можете просматривать и редактировать данные, хранящиеся в DevTools, используя API. Подробнее см. на странице «Просмотр и редактирование хранилища расширений» в документации DevTools.

Примеры

В следующих примерах показаны local , sync и session области хранения:

Местный 

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

Синхронизация 

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

Сессия 

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

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

Типы

AccessLevel

Хром 102+

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

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

«ДОВЕРЕННЫЕ_КОНТЕКСТЫ»
Указывает контексты, исходящие из самого расширения.

«ДОВЕРЕННЫЕ_И_НЕДОВЕРЕННЫЕ_КОНТЕКСТЫ»
Указывает контексты, возникающие за пределами расширения.

StorageArea

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

  • onChanged

    Событие<functionvoidvoid>

    Хром 73+

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

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

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

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

      функция

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

      (changes: object) => void

      • изменения

        объект

  • прозрачный

    пустота

    Обещать

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

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

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

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

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

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

      () => void

    • возвращается

      Обещание<void>

      Хром 95+

      Обещания поддерживаются в Manifest V3 и более поздних версиях, но для обратной совместимости предусмотрены обратные вызовы. Нельзя использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передаётся обратному вызову.

  • получать

    пустота

    Обещать

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

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

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

    • ключи

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

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

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

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

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

      (items: object) => void

      • предметы

        объект

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

    • возвращается

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

      Хром 95+

      Обещания поддерживаются в Manifest V3 и более поздних версиях, но для обратной совместимости предусмотрены обратные вызовы. Нельзя использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передаётся обратному вызову.

  • getBytesInUse

    пустота

    Обещать

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

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

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

    • ключи

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

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

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

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

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

      (bytesInUse: number) => void

      • байтыВИспользовании

        число

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

    • возвращается

      Обещание<номер>

      Хром 95+

      Обещания поддерживаются в Manifest V3 и более поздних версиях, но для обратной совместимости предусмотрены обратные вызовы. Нельзя использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передаётся обратному вызову.

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

    пустота

    Обещание Chrome 130+

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

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

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

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

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

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

      (keys: string[]) => void

      • ключи

        нить[]

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

    • возвращается

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

      Обещания поддерживаются в Manifest V3 и более поздних версиях, но для обратной совместимости предусмотрены обратные вызовы. Нельзя использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передаётся обратному вызову.

  • удалять

    пустота

    Обещать

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

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

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

    • ключи

      строка | строка[]

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

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

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

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

      () => void

    • возвращается

      Обещание<void>

      Хром 95+

      Обещания поддерживаются в Manifest V3 и более поздних версиях, но для обратной совместимости предусмотрены обратные вызовы. Нельзя использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передаётся обратному вызову.

  • набор

    пустота

    Обещать

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

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

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

    • предметы

      объект

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

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

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

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

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

      () => void

    • возвращается

      Обещание<void>

      Хром 95+

      Обещания поддерживаются в Manifest V3 и более поздних версиях, но для обратной совместимости предусмотрены обратные вызовы. Нельзя использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передаётся обратному вызову.

  • setAccessLevel

    пустота

    Обещание Chrome 102+

    Устанавливает желаемый уровень доступа к области хранения. По умолчанию хранилище session ограничено доверенными контекстами (страницами расширений и сервис-воркерами), тогда как local и sync хранилище разрешает доступ как из доверенных, так и из недоверенных контекстов.

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

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

    • accessOptions

      объект

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

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

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

      () => void

    • возвращается

      Обещание<void>

      Обещания поддерживаются в Manifest V3 и более поздних версиях, но для обратной совместимости предусмотрены обратные вызовы. Нельзя использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передаётся обратному вызову.

StorageChange

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

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

    любой необязательный

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

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

    любой необязательный

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

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

local

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

Тип

StorageArea и объект

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

  • QUOTA_BYTES

    10485760

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

managed

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

Тип

StorageArea

session

Chrome 102+ MV3+

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

Тип

StorageArea и объект

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

  • QUOTA_BYTES

    10485760

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

sync

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

Тип

StorageArea и объект

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

  • МАКС_ЭЛЕМЕНТОВ

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    Устаревший

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

  • 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 при использовании обратного вызова или при отклонении Promise.

События

onChanged

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

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

Параметры

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

    функция

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

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

    • изменения

      объект

    • areaName

      нить