browser.events

Описание

Понятия и применение

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

browser.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 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

В events.UrlFilter предпочтительнее использовать сопоставление подстрок, а не регулярные выражения. Сопоставление на основе подстрок выполняется чрезвычайно быстро.

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

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

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

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

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

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

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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