chrome.events

Описание

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

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 , за исключением сопоставления схемы и порта.