Эта страница переведена с помощью Cloud Translation API.

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

Описание

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

Разрешения

storage

Для использования API хранилища необходимо указать разрешение "storage" в манифесте расширения. Например:

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

Примеры

Следующие примеры демонстрируют области 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 is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

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

Понятия и применение

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

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

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

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

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

Для переноса данных из API веб-хранилища в API расширенного хранилища из сервис-воркера:

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

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

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

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

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

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

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

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

Местный

Данные хранятся локально и удаляются при удалении расширения. Лимит хранилища составляет 10 МБ (5 МБ в Chrome 113 и более ранних версиях), но его можно увеличить, запросив разрешение "unlimitedStorage" . Мы рекомендуем использовать storage.local для хранения больших объемов данных. По умолчанию оно доступно для скриптов контента, но это поведение можно изменить, вызвав метод chrome.storage.local.setAccessLevel() .

Удалось

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

По умолчанию storage.managed доступен для скриптов контента, но это поведение можно изменить, вызвав метод chrome.storage.managed.setAccessLevel() . Информацию о политиках см. в разделе « Документация для администраторов» . Более подробную информацию об managed области хранения см. в разделе «Манифест областей хранения» .

Сессия

Сессионное хранилище хранит данные в памяти во время загрузки расширения. Хранилище очищается при отключении, перезагрузке, обновлении расширения, а также при перезапуске браузера. По умолчанию оно не доступно для скриптов контента, но это поведение можно изменить, вызвав метод chrome.storage.session.setAccessLevel() . Лимит хранилища составляет 10 МБ (1 МБ в Chrome 111 и более ранних версиях).

Интерфейс storage.session — один из нескольких , которые мы рекомендуем для сервисных работников .

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

Если пользователь включает синхронизацию, данные синхронизируются со всеми браузерами Chrome, в которые он авторизован. Если синхронизация отключена, она работает как storage.local . Chrome сохраняет данные локально, когда браузер находится в автономном режиме, и возобновляет синхронизацию, когда он снова подключается к сети. Ограничение по квоте составляет приблизительно 100 КБ, по 8 КБ на элемент.

Мы рекомендуем использовать storage.sync для сохранения пользовательских настроек между синхронизированными браузерами. Если вы работаете с конфиденциальными пользовательскими данными, используйте storage.session . По умолчанию storage.sync доступен для скриптов контента, но это поведение можно изменить, вызвав chrome.storage.sync.setAccessLevel() .

Методы и события

Все области хранения реализуют интерфейс StorageArea .

получать()

Метод get() позволяет считывать один или несколько ключей из StorageArea .

getBytesInUse()

Метод getBytesInUse() позволяет просмотреть квоту, используемую StorageArea .

getKeys()

Метод getKeys() позволяет получить все ключи, хранящиеся в StorageArea .

удалять()

Метод remove() позволяет удалить элемент из StorageArea .

набор()

Метод set() позволяет установить значение элемента в StorageArea .

setAccessLevel()

Метод setAccessLevel() позволяет управлять доступом к StorageArea .

прозрачный()

Метод clear() позволяет очистить все данные из StorageArea .

onChanged

Событие onChanged позволяет отслеживать изменения в StorageArea .

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

В следующих разделах показаны типичные сценарии использования 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);
});

Инструменты разработчика

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

Типы

AccessLevel

Chrome 102+

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

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

"НАДЕЖНЫЙ КОНТЕКСТ"
Указывает контексты, исходящие от самого расширения.

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

StorageChange

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

новое значение
любой необязательный
Новое значение элемента, если таковое имеется.
старое значение
любой необязательный
Прежняя стоимость товара, если таковая существовала.

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

local

Предметы, находящиеся в local зоне хранения, относятся к каждой конкретной машине.

Тип

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

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

КВОТА_БАЙТЫ
10485760
Максимальный объем данных (в байтах), который может храниться в локальном хранилище, определяется как сумма длины каждого значения и каждого ключа в JSON-строке. Это значение будет игнорироваться, если расширение имеет разрешение unlimitedStorage . Обновления, которые приведут к превышению этого лимита, немедленно завершатся с ошибкой runtime.lastError при использовании функции обратного вызова или отклонят Promise при использовании async/await.

managed

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

Тип

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

session

Chrome 102+ MV3+

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

Тип

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

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

КВОТА_БАЙТЫ
10485760
Максимальный объем данных (в байтах), который может храниться в памяти, определяется путем оценки динамически выделяемой памяти для каждого значения и ключа. Обновления, которые приведут к превышению этого лимита, немедленно завершатся с ошибкой и вызовут runtime.lastError при использовании функции обратного вызова или при отклонении Promise.

sync

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

Тип

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

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

MAX_ITEMS
512
Максимальное количество элементов, которое может храниться в синхронном хранилище. Обновления, которые приведут к превышению этого лимита, немедленно завершатся с ошибкой и установят значение runtime.lastError при использовании функции обратного вызова или при отклонении промиса.
МАКСИМАЛЬНОЕ КОЛИЧЕСТВО ОПЕРАЦИЙ ЗАПИСИ В МИНУТУ
1000000
Устаревший
В API storage.sync больше нет квоты на постоянные операции записи.
МАКСИМАЛЬНОЕ КОЛИЧЕСТВО ОПЕРАЦИЙ ЗАПИСИ В ЧАС
1800
Максимальное количество операций set , remove или clear , которые могут быть выполнены за час. Это 1 операция каждые 2 секунды, что ниже краткосрочного более высокого лимита на количество операций записи в минуту.
Обновления, которые могут привести к превышению этого лимита, немедленно завершаются с ошибкой и устанавливают значение runtime.lastError при использовании функции обратного вызова или при отклонении промиса.
МАКСИМАЛЬНОЕ КОЛИЧЕСТВО ОПЕРАЦИЙ ЗАПИСИ В МИНУТУ
120
Максимальное количество операций set , remove или clear , которое может быть выполнено за минуту. Оно составляет 2 в секунду, что обеспечивает более высокую пропускную способность, чем количество операций записи в час, за более короткий период времени.
Обновления, которые могут привести к превышению этого лимита, немедленно завершаются с ошибкой и устанавливают значение runtime.lastError при использовании функции обратного вызова или при отклонении промиса.
КВОТА_БАЙТЫ
102400
Максимально допустимый общий объем данных (в байтах), который может храниться в синхронном хранилище, определяется как строковое представление JSON каждого значения плюс длина каждого ключа. Обновления, которые приведут к превышению этого лимита, немедленно завершатся с ошибкой и вызовут runtime.lastError при использовании функции обратного вызова или при отклонении Promise.
КВОТА_БАЙТОВ_НА_ТОВАР
8192
Максимальный размер (в байтах) каждого отдельного элемента в синхронизируемом хранилище, измеряемый как строковое представление его значения в формате JSON плюс длина ключа. Обновления, содержащие элементы, превышающие этот лимит, немедленно завершатся с ошибкой и вызовут runtime.lastError при использовании функции обратного вызова или при отклонении Promise.

События

onChanged

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

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

Параметры

перезвонить
функция
Параметр callback выглядит следующим образом:
```
(changes: object, areaName: string) => void
```
- изменения
  объект
- areaName
  нить

хром.хранилище Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

Разрешения

Примеры

Пример (локальный)

Пример (синхронизация)

Пример (сессии)

Понятия и применение

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

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

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

Местный

Удалось

Сессия

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

Методы и события

получать()

getBytesInUse()

getKeys()

удалять()

набор()

setAccessLevel()

прозрачный()

onChanged

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

Реагируйте на обновления хранилища.

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

Инструменты разработчика

Типы

AccessLevel

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

StorageChange

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

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

local

Тип

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

managed

Тип

session

Тип

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

sync

Тип

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

События

onChanged

Параметры

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