Розробка Options Page: де ламається логіка налаштувань
Розробка options page майже ніколи не впирається у верстку — вона впирається у стан. Користувач змінює налаштування, інтерфейс показує «збережено», а фонова логіка розширення продовжує працювати зі старим значенням, бо запис пішов в одне сховище, а читання йде з іншого.
Класика: значення лежать і в локальному сховищі, і в синхронізованому, при цьому пріоритет між ними ніде не зафіксований — і після перевстановлення або входу на другому пристрої сторінка налаштувань розширення показує один набір, а поведінка розширення визначається іншим.
Другий частий збій — втрата стану при оновленні. Options page живе в окремому контексті, і якщо вона не підписана на зміни сховища, відкрита вкладка залишається із застарілим знімком. Користувач править поле, зберігає — і затирає те, що встиг змінити інший контекст.
Синхронізація налаштувань розширення додає до цього гонки: два пристрої пишуть майже одночасно, перемагає останній запис, а проміжне значення губиться без сліду і без виразної помилки в інтерфейсі.
Третій клас помилок в options page — права та межі. Налаштування зберігається, але не застосовується, бо для нього не видано дозвіл або його відкликано; або поле валідується тільки на клієнті, і в сховище їде значення, яке ламає логіку при наступному запуску.
Окремо спливають міграції: схема налаштувань змінюється між версіями, старі ключі залишаються, нові читаються як порожні, і розширення стартує в дефолтному режимі — мовчки.
Ціна у всього цього одна: реліз блокується не багом у коді, а тим, що поведінка налаштувань непередбачувана і не відтворюється у тестувальника. Розбираємо, як це закривається на рівні моделі зберігання, підписок і міграцій.
Як влаштована надійна Options Page і що вона дає
Шари зберігання та реактивність
Налаштування розширення живуть у двох площинах: синхронізоване сховище (переживає перевстановлення та переноситься між пристроями користувача) і локальне (об'ємніше, але прив'язане до машини).
Змішувати їх в одному ключі — типова причина, через яку частина користувачів втрачає конфігурацію після перевстановлення. Ми розносимо шари явно: у синхронізоване кладемо лише те, що вкладається в ліміти й не містить чутливих даних, решту — локально.
Реактивність будується на підписці на зміни сховища: сторінка налаштувань і робочі скрипти розширення читають одне джерело, тому правка в інтерфейсі застосовується без перезапуску браузера.
Це прибирає клас помилок «зберіг, але не застосувалося» — стан розходиться лише за прямого редагування сховища в обхід API.
Валідація введення та міграції
Валідація — на межі запису, а не в момент використання. Схема описує типи, діапазони та обов'язковість полів; невалідне значення не потрапляє у сховище, а форма показує конкретну причину відмови.
Так битий конфіг не спливає через тиждень у робочому сценарії, коли користувач уже забув, що змінював.
Міграції — версіоновані: під час старту розширення порівнює збережену версію схеми з поточною та застосовує ланцюжок перетворень.
Старі ключі перейменовуються, значення приводяться до нових типів, невідомі поля зберігаються, а не видаляються — відкат на попередню версію залишається безпечним.
Порівняння підходів до реалізації
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Власна форма на DOM | Невеликий набір полів, мінімум залежностей | Ручна валідація та реактивність, зростає обсяг коду |
| Компонентний шар із реактивною моделлю | Багато пов'язаних полів, умовна видимість | Потрібна дисципліна в структурі стану |
| Схемо-орієнтований підхід | Налаштування описуються декларативно | Потребує проєктування схеми заздалегідь |
| Готові бібліотеки налаштувань | Швидкий старт, типові поля | Складніше кастомізувати логіку міграцій |
Для сторінки з десятками взаємозалежних параметрів схемо-орієнтований підхід окупається: додавання поля — правка опису, а не трьох місць у коді. Ми спираємося на Chrome Extensions API для сховища та підписок — це дає передбачувану поведінку в актуальній гілці браузерів.
Вимірний ефект
- Частка відмов «налаштування не збереглися» прямує до нуля: запис іде через один валідувальний шар.
- Час на додавання нового параметра скорочується в рази — змінюється опис схеми, а не логіка форми.
- Міграція проходить без втрати користувацьких даних, відкат на попередню версію розширення не ламає конфіг.
- Реактивність прибирає перезапуск браузера під час зміни налаштувань — сценарій перевірки займає секунди.
Етапи розробки Options Page під ключ
Розробка options page — це не «намалювати форму з полями», а спроєктувати шар налаштувань, який переживе зміну версій розширення, синхронізацію між пристроями та відкат. Нижче — процес, за яким ми ведемо проєкт від аудиту поточної логіки до передачі документації.
- Аудит розширення та поточної логіки налаштувань. Дивимося, де зараз зберігаються параметри, як вони читаються у фоновому скрипті та на сторінках, які значення підставляються за замовчуванням. Фіксуємо розбіжності між заявленою поведінкою та фактичною.
- Проєктування моделі налаштувань. Розділяємо параметри на рівні: глобальні, прив'язані до профілю, прив'язані до сайту. Визначаємо схему зберігання, правила злиття та пріоритети — це знімає більшість майбутніх конфліктів.
- Прототип інтерфейсу сторінки налаштувань. Збираємо структуру розділів, поведінку при невалідному введенні, стани «збережено / не збережено», сценарії скидання до значень за замовчуванням.
- Реалізація та зв'язка з фоновою частиною. Налаштування пишуться у сховище розширення та застосовуються без перезапуску — через підписку на зміни, а не через повне перезавантаження сторінок.
- Тестування налаштувань розширення. Перевіряємо міграцію зі старих версій, поведінку при порожньому та пошкодженому сховищі, синхронізацію між вікнами, права доступу та сценарії відкату.
- Передача документації та конфігурацій. Віддаємо опис схеми налаштувань, значення за замовчуванням, інструкцію щодо додавання нових параметрів і порядок випуску оновлень.
Кожен етап закінчується артефактом, який можна перевірити: схема зберігання, прототип, набір автотестів на міграцію, інструкція для підтримки. Опишіть задачу — повернемося з оцінкою та планом по вашому розширенню.
Чим відрізняється Options Page від Popup і вкладки налаштувань?
Popup і Options Page вирішують різні завдання, і плутанина між ними — часта причина переробок на етапі підтримки. Popup живе рівно стільки, скільки відкритий: клік по іконці, коротка дія, закриття. Щойно вікно закрилося, його стан і всі незавершені операції обриваються.
Для швидких дій — увімкнути режим, подивитися статус — цього достатньо. Для форми з десятком полів, завантаження файлу або покрокового майстра — ні: користувач втратить введене.
Options Page — це окрема сторінка розширення, яка живе у своїй вкладці й не залежить від того, чи відкритий popup. Тут розміщуються довгі форми, групування налаштувань за розділами, попередній перегляд змін і валідація полів до збереження.
Ключова різниця між сторінками розширення в тому, де зберігається стан: popup перестворюється при кожному відкритті, а options page зберігає контекст, поки вкладка відкрита.
Тому сценарії з імпортом конфігурації, вибором папок або налаштуванням інтеграцій майже завжди ведуть на окрему сторінку.
Є й третій варіант — вкладка налаштувань, вбудована в інтерфейс самого сайту або застосунку. Вона зручна, коли налаштування логічно живуть поруч з основним продуктом і не потребують прав доступу розширення.
Але якщо параметр впливає на поведінку розширення в чужих вкладках, тримати його всередині однієї сторінки незручно: користувач не зрозуміє, де шукати керування.
На практиці вибір між options page або popup визначає не лише зручність, а й вартість підтримки. Логіка, розмазана між спливаючим вікном і сторінкою, дублюється, а стан доводиться синхронізувати вручну.
Коли налаштування зібрані в одному місці, додавання нового параметра — це правка однієї форми й однієї схеми зберігання, а не пошук по трьох файлах. Саме тому на старті ми фіксуємо, які сценарії потребують тривалої взаємодії, і під них проєктуємо окрему сторінку.
Кейс: як ми усунули розсинхрон налаштувань у розширенні
До нас звернулися з розширенням для роботи з корпоративними вебсервісами: кілька тисяч активних встановлень, налаштування зберігалися в chrome.storage.sync, а сторінка параметрів записувала їх безпосередньо з форми.
Користувачі скаржилися, що встановлені правила «відкочуються» після перезапуску браузера, а частина профілів взагалі не синхронізувалася між пристроями.
Що було до
Звернень до підтримки щодо налаштувань — близько 40 на місяць, з них третина з формулюванням «все скинулося». Збереження форми займало 3-5 секунд: кожне поле записувало в сховище окремим викликом, а в разі конфлікту версій між пристроями перемагав той, хто записав останнім.
Клас відмов — тиха втрата користувацьких даних: помилок у консолі немає, інтерфейс показує «збережено», а фактичний стан розходиться з очікуваним.
Що змінили
Зібрали єдину модель налаштувань: форма працює з локальним станом, а запис відбувається однією транзакцією через фоновий процес розширення.
Додали версіонування схеми та міграції під час читання старих профілів, а конфлікти синхронізації вирішуються за міткою часу зміни, а не за порядком запису.
Окремо закрили сценарій скидання: перед перезаписом сховище звіряється з поточним станом, розходження логується й показується користувачеві.
Що стало
Звернення щодо налаштувань упали до 6-8 на місяць — переважно питання щодо інтерфейсу, а не щодо втрати даних. Збереження вклалося в 200-400 мс, тому що замість десятка розрізнених записів відбувається один.
Клас відмов «тиха втрата налаштувань» зник повністю: будь-яке розходження тепер видно в лозі та в самому інтерфейсі.
Для контролю стану ми підключили Sentry — помилки синхронізації та міграцій надходять з контекстом версії схеми й пристрою, тому регресії виявляються до звернень користувачів.
Далі — підтримка розширення: оновлення схеми налаштувань, міграції для старих профілів і розбір інцидентів за логами.
Сумніви перед стартом: сумісність, відкат, доступи
Перед стартом замовник зазвичай ставить три питання: чи не зламає нова сторінка налаштувань уже випущену версію розширення, чи можна відкотити зміни, якщо щось піде не так, і який доступ потрібен нашій команді до його інфраструктури. Відповідаємо по суті.
Сумісність options page. Сторінка налаштувань — ізольований контекст: вона спілкується з фоновим скриптом і сховищем через штатний обмін повідомленнями, тому переписування інтерфейсу не зачіпає логіку роботи самого розширення.
Якщо у вас уже є користувачі зі збереженими налаштуваннями, ми додаємо міграцію схеми зберігання: старі ключі читаються, приводяться до нового формату й записуються назад. Користувач не помічає переходу.
Відкат налаштувань розширення. Кожен реліз збирається як окремий артефакт, попередня версія залишається доступною. Відкат — це публікація минулої збірки і, за потреби, зворотна міграція сховища.
Ми заздалегідь описуємо, які зміни схеми оборотні автоматично, а які потребують ручного кроку — щоб рішення ухвалювалося до релізу, а не в момент збою.
Доступи для розробки. Потрібен доступ до репозиторію, тестового середовища та панелі публікації в магазині розширень. Працюємо через окремі облікові записи з мінімальними правами, ключі публікації залишаються у вас. Доступи відкликаються після завершення робіт.
Що якщо у нас уже є своя сторінка налаштувань і ми не хочемо її втрачати?
Тоді ми не переписуємо її з нуля, а розбираємо поточну реалізацію: дивимося, як влаштовано зберігання й обмін повідомленнями, і переносимо логіку частинами.
Стара сторінка продовжує працювати, поки нова не пройде перевірку на тестовій збірці — перемикання відбувається за один реліз.
Що якщо знадобиться доопрацювання після здачі? Передаємо код з історією змін і описом точок розширення — нове налаштування можна додати, не переглядаючи всю сторінку.
Після здачі ви отримуєте на руки:
- вихідний код сторінки налаштувань з історією змін;
- схему зберігання та правила міграції користувацьких даних;
- опис обміну повідомленнями між сторінкою, фоном і сховищем;
- інструкцію зі збірки та публікації нової версії;
- регламент відкату на попередній реліз;
- документацію щодо розширення: структура, точки розширення, порядок правок;
- чеклист перевірки перед випуском у магазин.
Опишіть задачу та поточний стан розширення — повернемося з оцінкою та планом робіт.
