chrome.events

Описание

Пространство имен chrome.events содержит общие типы, используемые API-интерфейсами, отправляющими события, чтобы уведомлять вас, когда происходит что-то интересное.

Концепции и использование

Event — это объект, который позволяет вам получать уведомления, когда происходит что-то интересное. Вот пример использования события chrome.alarms.onAlarm для получения уведомлений по истечении сигнала тревоги:

chrome.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Как показано в примере, вы регистрируетесь для получения уведомлений с помощью addListener() . Аргументом addListener() всегда является функция, которую вы определяете для обработки события, но параметры функции зависят от того, какое событие вы обрабатываете. Проверив документацию по alarms.onAlarm , вы можете увидеть, что у функции есть единственный параметр: объект alarms.Alarm , который содержит подробную информацию о прошедшем сигнале тревоги.

Примеры API, использующих события: Alarms , i18n , Identity , Runtime . Большинство API Chrome так и делают.

Декларативные обработчики событий

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

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

Правила

Простейшее возможное правило состоит из одного или нескольких условий и одного или нескольких действий:

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Если какое-либо из условий выполнено, все действия выполняются.

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

const rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Объекты событий

Объекты событий могут поддерживать правила. Эти объекты событий не вызывают функцию обратного вызова при возникновении событий, но проверяют, имеет ли какое-либо зарегистрированное правило хотя бы одно выполненное условие, и выполняют действия, связанные с этим правилом. Объекты событий, поддерживающие декларативный API, имеют три соответствующих метода: events.Event.addRules() , events.Event.removeRules() events.Event.getRules() .

Добавить правила

Чтобы добавить правила, вызовите функцию addRules() объекта события. Он принимает массив экземпляров правил в качестве первого параметра и функцию обратного вызова, которая вызывается по завершении.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Если правила были вставлены успешно, параметр details содержит массив вставленных правил, расположенных в том же порядке, что и в переданном rule_list , где необязательные параметры id и priority были заполнены сгенерированными значениями. Если какое-либо правило недействительно, например, потому что оно содержит недопустимое условие или действие, ни одно из правил не добавляется, а переменная runtime.lastError устанавливается при вызове функции обратного вызова. Каждое правило в rule_list должно содержать уникальный идентификатор, который еще не используется другим правилом, или пустой идентификатор.

Удалить правила

Чтобы удалить правила, вызовите функцию removeRules() . Он принимает необязательный массив идентификаторов правил в качестве первого параметра и функцию обратного вызова в качестве второго параметра.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

Если rule_ids представляет собой массив идентификаторов, все правила, идентификаторы которых указаны в массиве, удаляются. Если rule_ids указан неизвестный идентификатор, этот идентификатор игнорируется. Если rule_ids undefined , все зарегистрированные правила этого расширения удаляются. Функция callback() вызывается при удалении правил.

Получить правила

Чтобы получить список зарегистрированных правил, вызовите функцию getRules() . Он принимает необязательный массив идентификаторов правил с той же семантикой, что и removeRules() и функцию обратного вызова.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

Параметр details , передаваемый в функцию callback() относится к массиву правил, включая заполненные необязательные параметры.

Производительность

Для достижения максимальной производительности следует учитывать следующие рекомендации.

Массовая регистрация и отмена регистрации правил. После каждой регистрации или отмены регистрации Chrome необходимо обновить внутренние структуры данных. Это обновление является дорогостоящей операцией.

Вместо
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
Предпочитать
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Предпочитайте сопоставление подстроки регулярным выражениям в event.UrlFilter . Сопоставление на основе подстрок происходит очень быстро.

Вместо
const match = new chrome.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Предпочитать
const match = new chrome.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

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

Вместо
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]
              };
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
Предпочитать
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new chrome.declarativeWebRequest.CancelRequest()]
             };
chrome.declarativeWebRequest.onRequest.addRules([rule]);

Отфильтрованные события

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

Отфильтрованные события предназначены для обеспечения перехода от кода фильтрации вручную.

Вместо
chrome.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Предпочитать
chrome.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

События поддерживают определенные фильтры, имеющие значение для этого события. Список фильтров, которые поддерживает событие, будет указан в документации по этому событию в разделе «фильтры».

При сопоставлении URL-адресов (как в примере выше) фильтры событий поддерживают те же возможности сопоставления URL-адресов, которые выражаются с помощью events.UrlFilter , за исключением сопоставления схемы и порта.

Типы

Event

Объект, который позволяет добавлять и удалять прослушиватели событий Chrome.

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

  • добавить прослушиватель

    пустота

    Регистрирует обратный вызов прослушивателя событий для события.

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

    (callback: H) => {...}

    • перезвонить

      ЧАС

      Вызывается при возникновении события. Параметры этой функции зависят от типа события.

  • добавитьправила

    пустота

    Регистрирует правила для обработки событий.

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

    (rules: Rule<anyany>[], callback?: function) => {...}

    • правила

      Правило <anyany>[]

      Правила регистрации. Они не заменяют ранее зарегистрированные правила.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так:

      (rules: Rule<anyany>[]) => void

      • правила

        Правило <anyany>[]

        Правила, которые были зарегистрированы, необязательные параметры заполняются значениями.

  • получить правила

    пустота

    Возвращает зарегистрированные в данный момент правила.

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

    (ruleIdentifiers?: string[], callback: function) => {...}

    • Идентификаторы правил

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

      Если передается массив, возвращаются только правила с идентификаторами, содержащимися в этом массиве.

    • перезвонить

      функция

      Параметр callback выглядит так:

      (rules: Rule<anyany>[]) => void

      • правила

        Правило <anyany>[]

        Правила, которые были зарегистрированы, необязательные параметры заполняются значениями.

  • имеет прослушиватель

    пустота

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

    (callback: H) => {...}

    • перезвонить

      ЧАС

      Прослушиватель, статус регистрации которого должен быть проверен.

    • возвращает

      логическое значение

      True, если обратный вызов зарегистрирован для события.

  • имеет слушателей

    пустота

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

    () => {...}

    • возвращает

      логическое значение

      Значение true, если для этого события зарегистрированы какие-либо прослушиватели событий.

  • удалить прослушиватель

    пустота

    Отменяет регистрацию обратного вызова прослушивателя событий из события.

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

    (callback: H) => {...}

    • перезвонить

      ЧАС

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

  • удалить правила

    пустота

    Отменяет регистрацию текущих зарегистрированных правил.

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

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • Идентификаторы правил

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

      Если передается массив, отменяются только правила с идентификаторами, содержащимися в этом массиве.

    • перезвонить

      функция необязательна

      Параметр callback выглядит так:

      () => void

Rule

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

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

  • действия

    любой[]

    Список действий, которые срабатывают при выполнении одного из условий.

  • условия

    любой[]

    Список условий, которые могут вызвать действия.

  • идентификатор

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

    Необязательный идентификатор, позволяющий ссылаться на это правило.

  • приоритет

    номер необязательно

    Необязательный приоритет этого правила. По умолчанию 100.

  • теги

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

    Теги можно использовать для аннотирования правил и выполнения операций над наборами правил.

UrlFilter

Фильтрует URL-адреса по различным критериям. См. фильтрацию событий . Все критерии чувствительны к регистру.

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

  • cidrБлоки

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

    Хром 123+

    Соответствует, если хостовая часть URL-адреса является IP-адресом и содержится в любом из блоков CIDR, указанных в массиве.

  • хостСодержит

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

    Соответствует, если имя хоста URL-адреса содержит указанную строку. Чтобы проверить, имеет ли компонент имени хоста префикс «foo», используйте hostContains: «.foo». Это соответствует «www.foobar.com» и «foo.com», поскольку в начале имени хоста добавляется неявная точка. Аналогично, hostContains можно использовать для сопоставления с суффиксом компонента («foo.») и для точного сопоставления с компонентами («.foo.»). Сопоставление суффиксов и точное соответствие последних компонентов необходимо выполнять отдельно с помощью hostSuffix, поскольку в конце имени хоста не добавляется неявная точка.

  • хостEquals

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

    Соответствует, если имя хоста URL-адреса равно указанной строке.

  • хостПрефикс

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

    Соответствует, если имя хоста URL-адреса начинается с указанной строки.

  • хостСуффикс

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

    Соответствует, если имя хоста URL-адреса заканчивается указанной строкой.

  • originAndPathMatches

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

    Соответствует, если URL-адрес без сегмента запроса и идентификатора фрагмента соответствует указанному регулярному выражению. Номера портов удаляются из URL-адреса, если они соответствуют номеру порта по умолчанию. Регулярные выражения используют синтаксис RE2 .

  • путьСодержит

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

    Соответствует, если сегмент пути URL-адреса содержит указанную строку.

  • путьРавно

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

    Соответствует, если сегмент пути URL-адреса равен указанной строке.

  • префикс пути

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

    Соответствует, если сегмент пути URL-адреса начинается с указанной строки.

  • путьСуффикс

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

    Соответствует, если сегмент пути URL-адреса заканчивается указанной строкой.

  • порты

    (число | число[])[] необязательно

    Соответствует, если порт URL-адреса содержится в любом из указанных списков портов. Например [80, 443, [1000, 1200]] соответствует всем запросам на портах 80, 443 и в диапазоне 1000–1200.

  • запросСодержит

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

    Соответствует, если сегмент запроса URL-адреса содержит указанную строку.

  • запросEquals

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

    Соответствует, если сегмент запроса URL-адреса равен указанной строке.

  • префикс запроса

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

    Соответствует, если сегмент запроса URL-адреса начинается с указанной строки.

  • запросСуффикс

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

    Соответствует, если сегмент запроса URL-адреса заканчивается указанной строкой.

  • схемы

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

    Соответствует, если схема URL-адреса равна любой из схем, указанных в массиве.

  • urlСодержит

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

    Соответствует, если URL-адрес (без идентификатора фрагмента) содержит указанную строку. Номера портов удаляются из URL-адреса, если они соответствуют номеру порта по умолчанию.

  • URLEquals

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

    Соответствует, если URL-адрес (без идентификатора фрагмента) равен указанной строке. Номера портов удаляются из URL-адреса, если они соответствуют номеру порта по умолчанию.

  • urlMatches

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

    Соответствует, если URL-адрес (без идентификатора фрагмента) соответствует указанному регулярному выражению. Номера портов удаляются из URL-адреса, если они соответствуют номеру порта по умолчанию. Регулярные выражения используют синтаксис RE2 .

  • URLПрефикс

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

    Соответствует, если URL-адрес (без идентификатора фрагмента) начинается с указанной строки. Номера портов удаляются из URL-адреса, если они соответствуют номеру порта по умолчанию.

  • URLСуффикс

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

    Соответствует, если URL-адрес (без идентификатора фрагмента) заканчивается указанной строкой. Номера портов удаляются из URL-адреса, если они соответствуют номеру порта по умолчанию.