Як використовувати chrome.storage у Manifest V3

Коротка відповідь

Використовуйте chrome.storage.local для сталих записів пристрою, sync — малих міжпристроєвих параметрів, session — даних сеансу в пам’яті, managed — політик підприємства лише для читання. Оголосіть storage, очікуйте записи й перевіряйте прочитані значення. Збережений JSON може походити зі старого випуску й не є гарантованим поточним TypeScript-об’єктом.

Сховище розширення належить розширенню, на відміну від вебсховища сайту в контентному скрипті. Воркер не може використовувати window localStorage. Звичайні local і sync не шифровані сховища секретів; мінімізуйте конфіденційні дані замість припущень за назвами.

Практичні кроки реалізації

1. Призначте кожному запису мету, строк зберігання й автора. За можливості зберігайте незалежні параметри окремими ключами, щоб застаріле подання не перезаписало весь об’єкт.
2. Читайте з явними типовими значеннями й перевіряйте структуру. Типові значення get обробляють відсутні ключі, а не неправильні наявні. Самостійно перевіряйте діапазони й переліки.
3. Обробляйте відмову запису до оголошення успіху. Поточна документація Chrome зазначає 10 MB для local і session, із меншими межами старих версій; sync має значно менші загальні, поелементні та частотні межі. Читайте актуальний довідник замість однієї квоти для всіх областей.
4. Використовуйте storage.onChanged для оновлення потрібних активних подань. Перевіряйте область і ключ; зміна історії не має перебудовувати сторонні параметри.
5. Визначте потребу прямого доступу контентних скриптів. Підтримувані області мають керування рівнем доступу; session за замовчуванням не відкритий скриптам. Обмежте записи, що належать лише довіреним контекстам.

LocaleStress описує окремий продуктовий бюджет до 20 звітів у 3 MB. Це суворіше за місткість області браузера й потребує власного очищення. Квота браузера — остання межа відмови, а не політика зберігання продукту.

Приклад реалізації

Адаптер читає й записує один перевірений параметр. Викликачі обробляють відхилені проміси та визначають час застосування.

export async function readExpansion() {
  const { expansion } = await chrome.storage.local.get("expansion");
  return expansion === 50 ? 50 : 30;
}

export async function saveExpansion(value) {
  if (value !== 30 && value !== 50) throw new RangeError("Unsupported expansion");
  await chrome.storage.local.set({ expansion: value });
}

chrome.storage.onChanged.addListener((changes, area) => {
  if (area === "local" && "expansion" in changes) {
    const value = changes.expansion.newValue === 50 ? 50 : 30;
    console.log("Current expansion", value);
  }
});

Збільшення через читання й запис не атомарне між контекстами. Для списку централізуйте записи або використовуйте сховище з транзакціями за потреби. Очікування промісу не забезпечує транзакційної ізоляції.

Компроміси та альтернативи

Sync зручний для параметрів, але недоречний для звітів чи великих знімків. IndexedDB дає локальні індекси й транзакції за достатньої складності. Session зменшує тривалість даних, але потребує доступу й очищення. Managed може перевизначати типові значення на підприємстві; зробіть такі поля видимо недоступними для редагування.

Поширені помилки

• Вважати типові значення get перевіркою наявних даних.
• Записувати цілі об’єкти з кількох застарілих контекстів.
• Використовувати sync для великих звітів чи облікових даних.
• Повідомляти успіх до завершення запису.
• Стирати всі записи заради одного параметра.

Контрольний список випуску

• ☐ Структура, власник і зберігання задокументовані.
• ☐ Старі неправильні значення передбачувано відновлюються.
• ☐ Квоти мають видиму відновлювану відмову.
• ☐ Рівні доступу відповідають конфіденційності.
• ☐ Паралельні зміни не стирають важливі дані мовчки.

Поширені запитання

Чи unlimitedStorage є політикою зберігання?

Ні. Додаткова місткість не визначає потрібні дані й спосіб видалення.

Чи видалення розширення збереже локальні записи?

Не обіцяйте цього. Надайте явний експорт для переносних копій.

Що реалізувати далі?

Виберіть найменшу придатну область, визначте перевірку й видалення, потім перевірте відмови запису та стару схему перед розширенням зберігання.

Первинні джерела

• API сховища та квоти
• Збереження стану воркера
• Маніфест керованих параметрів

Пов’язані посібники та приклади

• Тематичний розділ
• Як створити розширення Chrome з Manifest V3
• Структура проєкту розширення Chrome, що масштабується
• Як написати файл manifest.json для Manifest V3
• Добровільна локальна історія й бюджет LocaleStress