browser.declarativeContent

Описание

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

Разрешения

declarativeContent

Основные понятия и использование

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

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

Правила

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

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

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

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

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

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

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

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

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

Шаблон PageStateMatcher.pageurl соответствует URL, если выполняются критерии. Чаще всего используются критерии, представляющие собой объединение хоста, пути или URL, за которым следует оператор "Содержит", "Равно", "Префикс" или "Суффикс". В таблице ниже приведены некоторые примеры.

Критерии Соответствует
{ 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 | object необязательный

    Объект 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, нажатие на действие страницы предоставляет доступ к активной вкладке.

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

Свойства

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

    void

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

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

События

onPageChanged

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

Условия

PageStateMatcher

Действия

RequestContentScript

SetIcon

ShowPageAction

ShowAction