Декларативні правила контенту для розширень Chrome

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

Використовуйте declarativeContent, коли браузер може визначити доречність кнопки панелі за URL-критеріями чи підтримуваними CSS-селекторами. Оголосіть дозвіл, вимкніть кнопку за замовчуванням і встановіть правила ввімкнення за збігу. Правило не повертає текст сторінки й не дає необмеженого доступу.

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

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

1. Визначте умову доречності: підтримуваний хост чи video-елемент. Використовуйте конструктори PageStateMatcher і ShowAction, а не застарілі приклади кнопок Manifest V2.
2. Розрізняйте логіку: кожен критерій усередині одного matcher має виконатися, але будь-який matcher масиву умов може активувати дії. Поділ на окремі matchers може ненавмисно розширити правило.
3. Використовуйте підтримувані складені CSS-селектори без комбінаторів. video.preview підтримується; main video містить комбінатор і тут непридатний. Уникайте сотень селекторів із зайвою роботою зіставлення.
4. Встановлюйте чи замінюйте правила при встановленні/оновленні. Вони переживають сеанси, тому створення на кожному запуску воркера зайве. Дайте власним правилам сталі ID й видаліть старі перед заміною.
5. Перевірте сторінки зі збігом і без нього. CSS-зіставлення працює за документованими умовами відображення; visibility:hidden відрізняється від display:none. Активна кнопка лише підказує доречність, а не доводить роботу на всіх фреймах.

Font Picker ілюструє завдання дослідження, якому могла б допомогти контекстна доступність, але публічний запис не доводить використання API. Виберіть просте URL-правило, якщо DOM-критерії не додають продуктової користі.

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

За оголошеної кнопки й дозволу declarativeContent воркер вмикає її на HTTPS-сторінках example.com із відображеним video. Додаткові activeTab і scripting для явного дослідження — окремі рішення.

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.disable().catch(console.error);
  chrome.declarativeContent.onPageChanged.removeRules(["video-page"], () => {
    if (chrome.runtime.lastError) {
      console.error(chrome.runtime.lastError.message);
      return;
    }
    chrome.declarativeContent.onPageChanged.addRules([{
      id: "video-page",
      conditions: [new chrome.declarativeContent.PageStateMatcher({
        pageUrl: { hostEquals: "example.com", schemes: ["https"] },
        css: ["video"],
      })],
      actions: [new chrome.declarativeContent.ShowAction()],
    }], () => {
      if (chrome.runtime.lastError) console.error(chrome.runtime.lastError.message);
    });
  });
});

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

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

Декларативна доречність усуває постійний скрипт лише заради перевірки доступності. Для складнішої логіки чи непідтримуваних селекторів потрібен контентний скрипт. Не використовуйте експериментальний RequestContentScript як стабільну стратегію: довідник позначає його непідтримуваним у стабільних випусках Chrome.

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

• Плутати мережеві правила з правилами доречності сторінки.
• Використовувати складні CSS-селектори з пробілами чи >.
• Перевстановлювати постійні правила на кожному запуску воркера.
• Вважати ShowAction дозволом читати довільні дані сторінки.

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

• ☐ Логіка відповідає потрібним умовам І/АБО.
• ☐ Використані селектори підтримуються.
• ☐ Заміна зберігає правила інших власників.
• ☐ Стани зі збігом і без нього перевірені.
• ☐ Доступ операції обґрунтований окремо.

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

Чи отримаю знайдений елемент?

Ні. Воно активує оголошену дію, а не є API відповіді DOM-запиту.

Чи правила переживають воркер?

Так. Керуйте ними свідомо при встановленні/оновленні замість покладання на пам’ять воркера.

Коли уникати API?

Коли дія корисна майже на кожній підтримуваній сторінці чи доречність потребує складнішої логіки за API. Чітке повідомлення недоступності може бути простішим.

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

• API Declarative Content
• API кнопки
• Дозвіл activeTab

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

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