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

Описание

Используйте 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. В рабочем сервисе расширений проверьте chrome.storage на наличие ваших данных.
  3. Если ваши данные не найдены, вызовите createDocument() .
  4. После того как возвращенное обещание будет разрешено, вызовите sendMessage() , чтобы запустить процедуру преобразования.
  5. Внутри обработчика onMessage закадрового документа вызовите процедуру преобразования.

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

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

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

storage.local
Данные хранятся локально и удаляются при удалении расширения. Ограничение хранилища составляет 10 МБ (5 МБ в Chrome 113 и более ранних версиях), но его можно увеличить, запросив разрешение "unlimitedStorage" . Мы рекомендуем использовать storage.local для хранения больших объемов данных.
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 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 , чтобы применить настройки как можно скорее.

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

Примеры

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

Чтобы просмотреть другие демонстрации 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+

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

  • получать

    пустота

    Обещать

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

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

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

    • ключи

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

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

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

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

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

      (items: object) => void

      • предметы

        объект

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

    • возвращает

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

      Хром 88+

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

  • getBytesInUse

    пустота

    Обещать

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

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

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

    • ключи

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

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

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

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

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

      (bytesInUse: number) => void

      • байтинусе

        число

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

    • возвращает

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

      Хром 88+

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

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

    пустота

    Обещание в ожидании

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

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

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

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

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

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

      (keys: string[]) => void

      • ключи

        нить[]

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

    • возвращает

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

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

  • удалять

    пустота

    Обещать

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

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

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

    • ключи

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

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

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

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

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

      () => void

    • возвращает

      Обещание<void>

      Хром 88+

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

  • набор

    пустота

    Обещать

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

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

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

    • предметы

      объект

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

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

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

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

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

      () => void

    • возвращает

      Обещание<void>

      Хром 88+

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

  • setAccessLevel

    пустота

    Обещание Chrome 102+

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

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

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

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

      объект

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

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

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

      () => void

    • возвращает

      Обещание<void>

      Промисы поддерживаются в Манифесте 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

    • изменения

      объект

    • имя области

      нить