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

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

Описание

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

Разрешения

storage

Обзор

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

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

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

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

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

Создайте внеэкранный документ с процедурой преобразования и обработчиком [ onMessage ][on-message].
Добавьте процедуру преобразования в документ, отображаемый вне экрана.
В расширении service worker проверьте chrome.storage на наличие ваших данных.
Если ваши данные не найдены, [создайте][create-offscreen] внеэкранный документ и вызовите [ sendMessage() ][send-message], чтобы начать процедуру преобразования.
Внутри обработчика onMessage внеэкранного документа вызовите процедуру преобразования.

Существуют также некоторые нюансы, связанные с работой API веб-хранилищ в расширениях. Подробнее см. статью [Хранилище и файлы cookie][storage-and-cookies].

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

API хранилища разделен на следующие четыре сегмента («области хранения»):

storage.local: Данные хранятся локально и очищаются при удалении расширения. Ограничение квоты составляет около 10 МБ, но его можно увеличить, запросив разрешение "unlimitedStorage" . Рассмотрите возможность использования этого разрешения для хранения больших объёмов данных.

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

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

storage.session: Сохраняет данные в памяти в течение всего сеанса браузера. По умолчанию они не доступны скриптам контента, но это поведение можно изменить, настроив chrome.storage.session.setAccessLevel() . Ограничение квоты составляет примерно 10 МБ. Рассмотрите возможность использования этой квоты для хранения глобальных переменных между запусками Service Worker.

хранилище.управляемое: Администраторы могут использовать схему и корпоративные политики для настройки параметров поддерживаемого расширения в управляемой среде. Эта область хранения доступна только для чтения.

Манифест

Чтобы использовать 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 currently 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 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 области хранения см. в разделе Манифест для областей хранения .

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

Не думайте, что добавление данных в 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);
});

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

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

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
  нить

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

Описание

Разрешения

Обзор

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

Манифест

Использование

хранилище.локальное

хранилище.синхронизация

storage.session

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

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

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

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

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

Типы

AccessLevel

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

StorageArea

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

StorageChange

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

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

local

Тип

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

managed

Тип

sync

Тип

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

События

onChanged

Параметры

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