Описание
Используйте 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 хранилища расширений из сервис-воркера:
- Подготовьте HTML-страницу закадрового документа и файл сценария. Файл сценария должен содержать процедуру преобразования и обработчик
onMessage
. - В рабочем сервисе расширений проверьте
chrome.storage
на наличие ваших данных. - Если ваши данные не найдены, вызовите
createDocument()
. - После того как возвращенное обещание будет разрешено, вызовите
sendMessage()
, чтобы запустить процедуру преобразования. - Внутри обработчика
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
Уровень доступа к хранилищу.
Перечисление
"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 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
- получить ключи
пустота
Обещание в ожиданииПолучает все ключи из хранилища.
Функция
getKeys
выглядит так:(callback?: function) => {...}
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(keys: string[]) => void
- ключи
нить[]
Массив с ключами, считанными из хранилища.
- возвращает
Обещание<string[]>
Промисы поддерживаются в Манифесте 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
Элементы в области хранения 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
- изменения
объект
- имя области
нить