Як створити розширення Chrome з Manifest V3

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

Почніть із трьох файлів: маніфесту Manifest V3, HTML-вікна та зовнішнього JavaScript-файлу. Приклад відкривається з панелі браузера, після натискання кнопки читає заголовок поточної сторінки й показує його у вікні. Потрібні activeTab і scripting; фоновий воркер, сервер і постійний доступ до всіх сайтів не потрібні.

Спливне вікно — це сторінка розширення. Впроваджена функція виконується на вибраній вебсторінці й повертає значення, яке можна серіалізувати. Це перше корисне архітектурне рішення: вікно володіє елементами керування та повідомленнями, а код сторінки — DOM-запитом. Фоновий воркер стане корисним пізніше, якщо треба реагувати на події поза часом існування вікна.

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

1. Створіть порожню папку й збережіть три наведені файли в її корені. Шляхи маніфесту відносні до встановленого розширення, тому popup.html має існувати саме з таким написанням. JSON не допускає коментарів і завершальних ком.
2. Відкрийте chrome://extensions, увімкніть режим розробника, виберіть Load unpacked і цю папку. Закріпіть розширення, якщо потрібна видима кнопка на панелі. Це завантажує локальні файли й нічого не публікує у Store.
3. Відкрийте звичайну HTTPS-сторінку й викличте розширення. Натисніть Read title та порівняйте результат із заголовком сторінки. Потім спробуйте сторінку chrome://, щоб побачити повідомлення про відмову. Тимчасовий дозвіл не дозволяє впровадження на захищені сторінки браузера.
4. Змініть JavaScript, перезавантажте розширення через його картку й знову відкрийте вікно. Якщо згодом додасте контентні скрипти, перезавантажте також цільову сторінку: перезавантаження розширення не замінює старий код у відкритому документі.
5. Збережіть вузьку функціональність першого випуску. Додавайте налаштування, коли є вподобання, які потрібно зберегти. Додавайте воркер, коли він потрібен події чи завданню. Інструмент, що досліджує шрифт або заголовок, може починати з дії користувача замість скрипту на кожній сторінці.

Для помилок інтерфейсу відкривайте інструменти розробника самого вікна. Помилки впровадження належать контексту розширення, що викликає API; журнали коду сторінки з’являються в цільовій вкладці. Перегляд не тієї консолі легко створює враження, що обробник не запускався. Видиме повідомлення прикладу звільняє користувача від потреби розбиратися в консолях.

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

manifest.json:

{
  "manifest_version": 3,
  "name": "Read page title",
  "version": "1.0.0",
  "action": { "default_popup": "popup.html" },
  "permissions": ["activeTab", "scripting"]
}

Збережіть popup.html із кнопкою з id read, елементом результату з id result і зовнішнім тегом скрипту, що вказує на popup.js. Розмістіть скрипт після елементів або використайте defer. Не використовуйте вбудований обробник подій: сторінки розширення мають політику безпеки вмісту, яка обмежує вбудований JavaScript.

popup.js:

const button = document.querySelector("#read");
const output = document.querySelector("#result");
button.addEventListener("click", async () => {
  button.disabled = true;
  output.textContent = "Reading…";
  try {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    if (!Number.isInteger(tab?.id)) throw new Error("No active tab");
    const [frame] = await chrome.scripting.executeScript({
      target: { tabId: tab.id },
      func: () => document.title,
    });
    output.textContent = String(frame?.result ?? "Untitled page");
  } catch {
    output.textContent = "Open a regular web page and try again.";
  } finally {
    button.disabled = false;
  }
});

Впроваджена функція самодостатня, бо Chrome серіалізує її в інший контекст виконання. Посилання всередині неї на змінну з popup.js не спрацює; передавайте параметри, що серіалізуються в JSON, через args. textContent також забезпечує показ заголовка як тексту, а не його інтерпретацію як HTML.

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

Спливне вікно підходить для короткої команди й результату, що вміщується на невеликій поверхні. Бічна панель доречніша для завдання, яке має залишатися видимим під час роботи зі сторінкою. Статичні контентні скрипти підходять для автоматичної поведінки на визначених сайтах, а activeTab — для явного виклику. Ці рішення змінюють час і місце виконання коду та важливіші за вибір UI-фреймворку.

Звичайний JavaScript дозволяє завантажити приклад без збирання. TypeScript або React можуть допомогти зі зростанням інтерфейсу, але Chrome встановлює зібраний пакет, а не TSX-код. Перевірте, що вихідний маніфест посилається на вихідні ресурси й пакет не залежить від сервера розробки.

Font Picker — реальний приклад спеціалізованого інструмента дослідження в портфоліо. Він ілюструє продуктовий обсяг, але це не означає, що він використовує реалізацію цього посібника. Не визначайте його дозволи чи архітектуру лише за знімком екрана.

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

• Додавати tabs лише через виклик tabs.query: сам запит ідентифікаторів вкладок не потребує цього дозволу. Для конфіденційних властивостей діють додаткові правила доступу.
• Очікувати автоматичної роботи activeTab після встановлення: доступ виникає після відповідного виклику користувачем.
• Додавати обробник action.onClicked разом із налаштованим вікном: натискання відкриває вікно.
• Класти в ZIP вихідні файли, коли маніфест посилається на відсутні зібрані шляхи.
• Вважати успіх на HTTPS доказом роботи на сторінках браузера, файлових URL або сторонніх фреймах.

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

• ☐ Завантажте точну папку для поширення в окремий профіль браузера.
• ☐ Перевірте звичайну й захищену сторінку, закриту вкладку та повторні натискання.
• ☐ Знову відкрийте вікно й переконайтеся, що тимчасові результати можуть зникати за задумом.
• ☐ Використайте кнопку клавіатурою та забезпечте доступне оголошення стану результату.
• ☐ Видаліть невикористані дозволи й додайте потрібні Store-зображення перед публікацією.
• ☐ Запишіть версію браузера та результати; цей посібник не стверджує, що ваш пакет перевірено у браузері.

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

Чи потрібен сервісний воркер?

Для цього прикладу — ні. Додавайте його для подій усього розширення, команд, обробки встановлення або роботи поза вікном. Воркер у маніфесті необов’язковий.

Чи можна завантажувати код із CDN?

Пакуйте виконуваний код розширення разом із розширенням. Приклад фреймворку з CDN для розробки не підходить для робочого пакета. Розглядайте віддалені дані й виконуваний код як різні рішення.

Що створювати далі?

Виберіть одну корисну дію дослідження сторінки й збережіть цей шлях: явний виклик, вузька DOM-операція, серіалізований результат і видима відмова. Потім визначте, чи справді цьому завданню допомагають збережені налаштування або триваліше видимий інтерфейс.

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

• Посібник Hello World
• Формат маніфесту
• Дозвіл activeTab
• API Scripting

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

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