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

Описание

Разрешения

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

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

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

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

storage.local

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

storage.managed

Управляемое хранилище — это хранилище только для чтения для установленных политикой расширений, которым управляют системные администраторы с помощью схемы, определяемой разработчиком, и корпоративных политик. Политики аналогичны параметрам, но настраиваются системным администратором, а не пользователем, что позволяет предварительно настроить расширение для всех пользователей организации. По умолчанию storage.managed доступен для скриптов содержимого, но это поведение можно изменить, вызвав chrome.storage.managed.setAccessLevel() . Подробнее о политиках см. в разделе « Документация для администраторов» . Подробнее об 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.sync доступен для скриптов содержимого, но это поведение можно изменить, вызвав chrome.storage.sync.setAccessLevel() .

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

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 для скорейшего применения настроек.

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);
});

DevTools

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

Примеры

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

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

• Расширение глобального поиска .
• Расширение для сигнализации о протечке воды .

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