Описание
Используйте API chrome.storage
для хранения, получения и отслеживания изменений пользовательских данных.
Разрешения
storage
Обзор
API хранилища предоставляет специфичный для расширения способ сохранения пользовательских данных и состояния. Он похож на API-интерфейсы хранилища веб-платформы ( IndexedDB и Storage ), но был разработан для удовлетворения потребностей расширений в хранилище. Ниже приведены несколько ключевых особенностей:
- Все контексты расширений, включая работника службы расширений и сценарии содержимого, имеют доступ к API хранилища.
- Сериализуемые значения JSON хранятся как свойства объекта.
- API хранилища является асинхронным с операциями массового чтения и записи.
- Даже если пользователь очистит кеш и историю просмотров, данные сохранятся.
- Сохраненные настройки сохраняются даже при использовании разделения в режиме инкогнито .
- Включает эксклюзивную управляемую область хранения только для чтения для корпоративных политик.
Несмотря на то, что расширения могут использовать интерфейс [ Storage
][mdn-storage] (доступный из window.localStorage
) в некоторых контекстах (всплывающее окно и другие HTML-страницы), это не рекомендуется по следующим причинам:
- Сервисный работник расширения не может получить доступ к
Storage
. - Скрипты контента делят хранилище с главной страницей.
- Данные, сохраненные с помощью интерфейса
Storage
, теряются, когда пользователь очищает историю просмотров.
Чтобы переместить данные из API веб-хранилища в API хранилища расширений из сервис-воркера:
- Создайте закадровый документ с помощью процедуры преобразования и обработчика [
onMessage
][on-message]. - Добавьте процедуру преобразования в закадровый документ.
- В рабочем сервисе расширений проверьте
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 КБ на элемент. Рассмотрите возможность использования его для сохранения пользовательских настроек в синхронизированных браузерах.
- хранилище.сессия
- Хранит данные в памяти на время сеанса браузера. По умолчанию он не доступен сценариям содержимого, но это поведение можно изменить, установив
chrome.storage.session.setAccessLevel()
. Ограничение квоты составляет примерно 10 МБ. Рассмотрите возможность использования его для хранения глобальных переменных во время выполнения сервисного работника.
- хранилище.управляемое
- Администраторы могут использовать схему и политики предприятия для настройки параметров поддерживающего расширения в управляемой среде. Эта область хранения доступна только для чтения.
Манифест
Чтобы использовать API хранилища, объявите разрешение "storage"
в манифесте расширения. Например:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
Использование
В следующих примерах демонстрируются local
, sync
и session
области хранения:
Storage.local
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);
});
Storage.sync
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);
});
хранилище.сессия
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
чтобы применить настройки как можно скорее.
параметры.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);
});
Примеры расширений
Чтобы увидеть другие демонстрации Storage API, изучите любой из следующих примеров:
Типы
AccessLevel
Уровень доступа к хранилищу.
Перечисление
"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+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
- получать
пустота
ОбещатьПолучает один или несколько элементов из хранилища.
Функция
get
выглядит так:(keys?: string | string[] | object, callback?: function) => {...}
- ключи
строка | строка[] | объект необязательный
Один ключ для получения, список ключей для получения или словарь, определяющий значения по умолчанию (см. описание объекта). Пустой список или объект вернет пустой объект результата. Передайте значение
null
чтобы получить все содержимое хранилища. - перезвонить
функция необязательна
Параметр
callback
выглядит так:(items: object) => void
- предметы
объект
Объект с элементами в сопоставлениях ключ-значение.
- возвращает
Обещание<объект>
Хром 88+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
- getBytesInUse
пустота
ОбещатьПолучает объем пространства (в байтах), используемого одним или несколькими элементами.
Функция
getBytesInUse
выглядит так:(keys?: string | string[], callback?: function) => {...}
- ключи
строка | строка[] необязательно
Один ключ или список ключей, для которых нужно получить общее количество использований. Пустой список вернет 0. Введите значение
null
чтобы получить общее использование всего хранилища. - перезвонить
функция необязательна
Параметр
callback
выглядит так:(bytesInUse: number) => void
- байтинусе
число
Объем места, используемого в хранилище, в байтах.
- возвращает
Обещание<число>
Хром 88+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
- получить ключи
пустота
Обещание Chrome 130+Получает все ключи из хранилища.
Функция
getKeys
выглядит так:(callback?: function) => {...}
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(keys: string[]) => void
- ключи
нить[]
Массив с ключами, считанными из хранилища.
- возвращает
Обещание<string[]>
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
- удалять
пустота
ОбещатьУдаляет один или несколько элементов из хранилища.
Функция
remove
выглядит так:(keys: string | string[], callback?: function) => {...}
- ключи
строка | нить[]
Один ключ или список ключей для элементов, которые нужно удалить.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
- возвращает
Обещание<void>
Хром 88+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
- набор
пустота
ОбещатьУстанавливает несколько элементов.
Функция
set
выглядит так:(items: object, callback?: function) => {...}
- предметы
объект
Объект, который предоставляет каждой паре ключ/значение для обновления хранилища. Любые другие пары ключ/значение в хранилище не будут затронуты.
Примитивные значения, такие как числа, будут сериализоваться, как и ожидалось. Значения
typeof
"object"
и"function"
обычно сериализуются в{}
, за исключениемArray
(сериализуется, как и ожидалось),Date
иRegex
(сериализуется с использованием ихString
представления). - перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
- возвращает
Обещание<void>
Хром 88+Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
- setAccessLevel
пустота
Обещание Chrome 102+Устанавливает желаемый уровень доступа к области хранения. По умолчанию будут только доверенные контексты.
Функция
setAccessLevel
выглядит так:(accessOptions: object, callback?: function) => {...}
- параметры доступа
объект
- уровень доступа
Уровень доступа к хранилищу.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
- возвращает
Обещание<void>
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.
StorageChange
Характеристики
- новое значение
любые дополнительные
Новое значение элемента, если есть новое значение.
- старое значение
любые дополнительные
Старое значение элемента, если оно существовало.
Характеристики
local
Элементы в local
хранилище являются локальными для каждой машины.
Тип
Область хранения и объект
Характеристики
- QUOTA_BYTES
10485760
Максимальный объем (в байтах) данных, который может храниться в локальном хранилище, измеряемый строковой структурой каждого значения плюс длина каждого ключа в формате JSON. Это значение будет игнорироваться, если расширение имеет разрешение
unlimitedStorage
. Обновления, которые могут привести к превышению этого предела, немедленно завершаются сбоем и устанавливаютruntime.lastError
при использовании обратного вызова или отклоненное обещание при использовании async/await.
managed
Элементы в области managed
хранилища задаются политикой предприятия, настроенной администратором домена, и доступны расширению только для чтения; попытка изменить это пространство имен приводит к ошибке. Информацию о настройке политики см. в разделе Манифест для областей хранения .
Тип
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
- изменения
объект
- имя области
нить