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

Описание

Используйте 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 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

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

  пустота

  Обещание Chrome 130+

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

  Функция 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

  • изменения

    объект

  • имя области

    нить