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

Описание

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

• удалять

  пустота

  Обещать

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

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

  • изменения

    объект

  • имя области

    нить