chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Описание

Используйте chrome.declarativeContent API, чтобы выполнять действия в зависимости от контента страницы, не запрашивая разрешение на его чтение.

Разрешения

declarativeContent

Использование

Declarative Content API позволяет включить действие расширения в зависимости от URL веб-страницы или от того, соответствует ли селектор CSS элементу на странице, без необходимости добавлять разрешения хоста или внедрять скрипт контента.

Используйте разрешение activeTab, чтобы взаимодействовать со страницей после того, как пользователь нажмет на действие расширения.

Правила

Правила состоят из условий и действий. Если выполняется хотя бы одно из условий, выполняются все действия. Доступны действия setIcon и showAction.

PageStateMatcher сопоставляет веб-страницы, только если выполняются все перечисленные критерии. Это может быть URL страницы, составной селектор CSS или состояние закладки страницы. Следующее правило включает действие расширения на страницах Google, если на них есть поле для ввода пароля:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Чтобы также включить действие расширения для Google Сайтов с видео, можно добавить второе условие, поскольку каждого условия достаточно для запуска всех указанных действий:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Событие onPageChanged проверяет, выполнено ли хотя бы одно условие в каком-либо правиле, и выполняет действия. Правила сохраняются между сеансами просмотра, поэтому при установке расширения сначала нужно использовать removeRules, чтобы удалить ранее установленные правила, а затем addRules, чтобы зарегистрировать новые.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

При использовании разрешения activeTab расширение не будет показывать предупреждения о разрешениях, а когда пользователь нажмет на действие расширения, оно будет выполняться только на соответствующих страницах.

Сопоставление URL страниц

PageStateMatcher.pageurl срабатывает, когда выполняются критерии URL. Чаще всего критерии представляют собой объединение хоста, пути или URL, за которым следует Contains, Equals, Prefix или Suffix. В таблице ниже приведены некоторые примеры.

Критерии Соответствует
{ hostSuffix: 'google.com' } Все URL Google
{ pathPrefix: '/docs/extensions' } URL документации по расширениям
{ urlContains: 'developer.chrome.com' } Все URL документации для разработчиков Chrome

Все критерии чувствительны к регистру. Полный список критериев приведен в описании правила UrlFilter.

Сопоставление CSS

Условия PageStateMatcher.css должны быть составными селекторами. Это значит, что в них нельзя включать комбинаторы, такие как пробел или >. Это помогает Chrome более эффективно сопоставлять селекторы.

Составные селекторы (OK) Сложные селекторы (неправильно)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

Условия CSS соответствуют только отображаемым элементам. Если элемент, соответствующий вашему селектору, имеет значение display:none или один из его родительских элементов имеет значение display:none, условие не будет выполнено. Элементы, оформленные с помощью visibility:hidden, расположенные за пределами экрана или скрытые другими элементами, по-прежнему могут соответствовать вашему условию.

Соответствие статуса закладки

Условие PageStateMatcher.isBookmarked позволяет сопоставлять текущий URL с закладками в профиле пользователя. Чтобы использовать это условие, в манифесте расширения должно быть объявлено разрешение bookmarks.

Типы

Тип

ImageData

PageStateMatcher

Соответствует состоянию веб-страницы на основе различных критериев.

Свойства

  • конструктор

    void

    Функция constructor выглядит следующим образом: 

    (arg: PageStateMatcher) => {...}

  • css

    string[] необязательно

    Соответствие устанавливается, если все селекторы CSS в массиве соответствуют отображаемым элементам во фрейме с тем же источником, что и у основного фрейма страницы. Все селекторы в этом массиве должны быть составными, чтобы ускорить сопоставление. Примечание. Если вы укажете сотни селекторов CSS или селекторы CSS, которые встречаются на странице сотни раз, это может замедлить работу сайта.

  • isBookmarked

    Логическое значение (необязательно)

    Chrome 45 и более поздних версий;

    Соответствует, если статус закладки страницы равен указанному значению. Требуется разрешение на работу с закладками.

  • pageUrl

    UrlFilter необязательный

    Совпадение регистрируется, если условия UrlFilter выполняются для URL верхнего уровня страницы.

RequestContentScript

Действие декларативного события, которое внедряет скрипт контента.

ВНИМАНИЕ! Это действие пока является экспериментальным и не поддерживается в стабильных сборках Chrome.

Свойства

  • конструктор

    void

    Функция constructor выглядит следующим образом: 

    (arg: RequestContentScript) => {...}

  • allFrames

    Логическое значение (необязательно)

    Указывает, выполняется ли скрипт контента во всех фреймах соответствующей страницы или только в верхнем фрейме. Значение по умолчанию: false.

  • css

    string[] необязательно

    Названия CSS-файлов, которые будут внедрены как часть скрипта контента.

  • js

    string[] необязательно

    Названия файлов JavaScript, которые будут внедрены как часть скрипта обработки контента.

  • matchAboutBlank

    Логическое значение (необязательно)

    Указывает, нужно ли вставлять скрипт контента в about:blank и about:srcdoc. Значение по умолчанию — false.

SetIcon

Декларативное действие события, которое устанавливает квадратный значок n-dip для действия на странице или действия в браузере, когда выполняются соответствующие условия. Это действие можно использовать без разрешений хоста, но у расширения должно быть действие на странице или в браузере.

Необходимо указать только одно значение: imageData или path. Оба представляют собой словари, сопоставляющие количество пикселей с представлением изображения. Изображение в imageData – это объект ImageData, например из элемента canvas, а изображение в path – это путь к графическому файлу относительно манифеста расширения. Если в независимый от устройства пиксель помещается scale пикселей экрана, используется значок scale * n. Если такого изображения нет, то размер другого изображения изменяется до требуемого.

Свойства

  • конструктор

    void

    Функция constructor выглядит следующим образом: 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | объект необязательный

    Объект ImageData или словарь {size -> ImageData}, представляющий значок, который нужно установить. Если значок задан в виде словаря, то используемое изображение выбирается в зависимости от плотности пикселей экрана. Если количество пикселей изображения, помещающихся в одну единицу пространства экрана, равно scale, то выбирается изображение размером scale * n, где n – размер значка в интерфейсе. Необходимо указать хотя бы одно изображение. Обратите внимание, что details.imageData = foo эквивалентно details.imageData = {'16': foo}.

ShowAction

Chrome 97 и более поздних версий;

Декларативное действие события, которое включает действие на панели инструментов расширения, когда выполняются соответствующие условия. Это действие можно использовать без разрешений хоста. Если у расширения есть разрешение activeTab, нажатие на значок расширения предоставляет доступ к активной вкладке.

На страницах, где условия не выполняются, значок расширения на панели инструментов будет серым, а при нажатии на него будет открываться контекстное меню, а не выполняться действие.

Свойства

  • конструктор

    void

    Функция constructor выглядит следующим образом: 

    (arg: ShowAction) => {...}

ShowPageAction

Поддержка прекращена в Chrome 97

Используйте declarativeContent.ShowAction.

Декларативное действие события, которое переводит действие на странице расширения в активное состояние, пока выполняются соответствующие условия. Это действие можно использовать без разрешений хоста, но у расширения должно быть действие на странице. Если у расширения есть разрешение activeTab, нажатие на значок расширения предоставляет доступ к активной вкладке.

На страницах, где условия не выполняются, значок расширения на панели инструментов будет серым, а при нажатии на него будет открываться контекстное меню, а не выполняться действие.

Свойства

События

onPageChanged

Предоставляет Declarative Event API, состоящий из addRules, removeRules и getRules.

Условия

PageStateMatcher

Действия

RequestContentScript

SetIcon

ShowPageAction

ShowAction