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 должно содержать уникальный идентификатор, который еще не используется другим правилом, или пустой идентификатор.

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

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

Чтобы удалить правила, вызовите функцию 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-адреса, если они соответствуют номеру порта по умолчанию.