chrome.declarativeContent

Описание

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

Разрешения

declarativeContent

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

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-адреса, за которым следуют «Содержит», «Равно», «Префикс» или «Суффикс». В следующей таблице приведено несколько примеров:

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

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

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

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

Составные селекторы (ОК) Сложные селекторы (не подходит)
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-адреса в профиле пользователя. Чтобы использовать это условие, разрешение «закладки» должно быть объявлено в манифесте расширения.

Типы

Тип

Данные изображения

PageStateMatcher

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

Характеристики

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

    пустота

    Функция constructor выглядит так:

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

  • CSS

    строка[] необязательно

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

  • есть в закладках

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

    Хром 45+

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

  • URL-адрес страницы

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

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

RequestContentScript

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

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

Характеристики

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

    пустота

    Функция constructor выглядит так:

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

  • всекадры

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

    Запускается ли сценарий содержимого во всех кадрах соответствующей страницы или только в верхнем кадре. По умолчанию — false .

  • CSS

    строка[] необязательно

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

  • js

    строка[] необязательно

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

  • matchО программеBlank

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

    Вставлять ли сценарий содержимого в about:blank и about:srcdoc . По умолчанию — false .

SetIcon

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

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

Характеристики

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

    пустота

    Функция constructor выглядит так:

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

  • данные изображения

    Данные изображения | объект необязательный

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

ShowAction

Хром 97+

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

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

Характеристики

ShowPageAction

Устарело с Chrome 97.

Пожалуйста, используйте declarativeContent.ShowAction .

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

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

Характеристики

События

onPageChanged

Предоставляет API декларативных событий , состоящий из addRules , removeRules и getRules .