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'}]});

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

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