Расширения Manifest V2 были удалены из Chrome Web Store 31 августа 2026 года. Перенесите свое расширение на Manifest V3, чтобы оно снова стало доступно пользователям.

Эта страница переведена с помощью Cloud Translation API.

chrome.events

дата обновления: 2026-09-25 robots: noindex

Описание

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

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

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

As the example shows, you register for notification using addListener() . The argument to addListener() is always a function that you define to handle the event, but the parameters to the function depend on which event you're handling. Checking the documentation for alarms.onAlarm , you can see that the function has a single parameter: an alarms.Alarm object that has details about the elapsed alarm.

Примеры API, использующих события: alarms , i18n , identity , runtime . Большинство API Chrome это делают.

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

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

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

Правила

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

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

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

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

var 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() объекта события. В качестве первого параметра она принимает массив экземпляров правил, а в качестве результата — функцию обратного вызова, которая вызывается по завершении.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

If the rules were inserted successfully, the details parameter contains an array of inserted rules appearing in the same order as in the passed rule_list where the optional parameters id and priority were filled with the generated values. If any rule is invalid, eg, because it contained an invalid condition or action, none of the rules are added and the runtime.lastError variable is set when the callback function is called. Each rule in rule_list must contain a unique identifier that is not currently used by another rule or an empty identifier.

Удаление правил

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

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

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

Получение правил

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

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});

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

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

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

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

Вместо:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

предпочитать:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

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

Вместо:

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

предпочитать:

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

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

Вместо:

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

предпочитать:

  var rule = { conditions: [condition1, condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]};
  chrome.declarativeWebRequest.onRequest.addRules([rule]);

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

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

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

chrome.webNavigation.onCommitted.addListener(function(e) {
  if (hasHostSuffix(e.url, 'google.com') ||
      hasHostSuffix(e.url, 'google.com.au')) {
    // ...
  }
});

в это:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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

Типы

Event

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

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

addListener
пустота
Регистрирует обработчик события (обратный вызов ).
Функция addListener выглядит следующим образом:
```
(callback: H) => {...}
```
- перезвонить
  ЧАС
  Вызывается при возникновении события. Параметры этой функции зависят от типа события.
addRules
пустота
Регистрирует правила для обработки событий.
Функция addRules выглядит следующим образом:
```
(rules: Rule<anyany>[], callback?: function) => {...}
```
- правила
  Правило <anyany>[]
  Правила подлежат регистрации. Они не заменяют ранее зарегистрированные правила.
- перезвонить
  функция необязательна
  Параметр callback выглядит следующим образом:
```
(rules: Rule<anyany>[]) => void
```
  - правила
    Правило <anyany>[]
    В зарегистрированных правилах необязательные параметры заполняются значениями.
getRules
пустота
Возвращает зарегистрированные в данный момент правила.
Функция getRules выглядит следующим образом:
```
(ruleIdentifiers?: string[], callback: function) => {...}
```
- ruleIdentifiers
  строка[] необязательный
  Если передан массив, возвращаются только правила, идентификаторы которых содержатся в этом массиве.
- перезвонить
  функция
  Параметр callback выглядит следующим образом:
```
(rules: Rule<anyany>[]) => void
```
  - правила
    Правило <anyany>[]
    В зарегистрированных правилах необязательные параметры заполняются значениями.
hasListener
пустота
Функция hasListener выглядит следующим образом:
```
(callback: H) => {...}
```
- перезвонить
  ЧАС
  Слушатель, чей регистрационный статус подлежит проверке.
- возвраты
  логический
  Возвращает true, если функция обратного вызова зарегистрирована для события.
hasListeners
пустота
Функция hasListeners выглядит следующим образом:
```
() => {...}
```
- возвраты
  логический
  Возвращает true, если на мероприятие зарегистрированы какие-либо слушатели события.
удалитьСлушатель
пустота
Отменяет регистрацию обратного вызова обработчика события.
Функция removeListener выглядит следующим образом:
```
(callback: H) => {...}
```
- перезвонить
  ЧАС
  Слушатель, который не должен быть зарегистрирован.
removeRules
пустота
Отменяет регистрацию уже зарегистрированных правил.
Функция removeRules выглядит следующим образом:
```
(ruleIdentifiers?: string[], callback?: function) => {...}
```
- ruleIdentifiers
  строка[] необязательный
  Если передан массив, то отменяются только правила, идентификаторы которых содержатся в этом массиве.
- перезвонить
  функция необязательна
  Параметр callback выглядит следующим образом:
```
() => void
```

Rule

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

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

действия
любой[]
Список действий, которые запускаются при выполнении одного из условий.
условия
любой[]
Список условий, которые могут инициировать действия.
идентификатор
строка необязательный
Необязательный идентификатор, позволяющий ссылаться на это правило.
приоритет
число необязательно
Приоритет этого правила необязателен. По умолчанию — 100.
теги
строка[] необязательный
Теги можно использовать для аннотирования правил и выполнения операций над наборами правил.

UrlFilter

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

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

cidrBlocks
строка[] необязательный
Chrome 123+
Совпадение происходит, если хостовая часть URL-адреса представляет собой IP-адрес и содержится в любом из блоков CIDR, указанных в массиве.
hostContains
строка необязательный
Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.
hostEquals
строка необязательный
Срабатывает, если имя хоста в URL-адресе совпадает с указанной строкой.
hostPrefix
строка необязательный
Срабатывает, если имя хоста в URL-адресе начинается с указанной строки.
hostSuffix
строка необязательный
Совпадение происходит, если имя хоста в URL-адресе заканчивается указанной строкой.
originAndPathMatches
строка необязательный
Совпадение происходит, если URL-адрес без идентификаторов сегмента запроса и фрагмента соответствует указанному регулярному выражению. Номера портов удаляются из URL-адреса, если они совпадают с номером порта по умолчанию. В регулярных выражениях используется синтаксис RE2 .
pathContains
строка необязательный
Срабатывает, если сегмент пути URL содержит указанную строку.
pathEquals
строка необязательный
Срабатывает, если сегмент пути URL-адреса равен указанной строке.
pathPrefix
строка необязательный
Срабатывает, если сегмент пути URL начинается с указанной строки.
pathSuffix
строка необязательный
Срабатывает, если сегмент пути URL заканчивается указанной строкой.
порты
(число | число[])[] необязательно
Соответствует запросу, если порт URL-адреса содержится в каком-либо из указанных списков портов. Например, [80, 443, [1000, 1200]] соответствует всем запросам на портах 80, 443 и в диапазоне 1000-1200.
queryContains
строка необязательный
Срабатывает, если сегмент запроса URL содержит указанную строку.
queryEquals
строка необязательный
Совпадение происходит, если сегмент запроса URL-адреса равен указанной строке.
queryPrefix
строка необязательный
Совпадение происходит, если сегмент запроса URL начинается с указанной строки.
querySuffix
строка необязательный
Совпадение происходит, если сегмент запроса URL заканчивается указанной строкой.
схемы
строка[] необязательный
Совпадение происходит, если схема URL-адреса совпадает с любой из схем, указанных в массиве.
urlContains
строка необязательный
Совпадение происходит, если URL (без идентификатора фрагмента) содержит указанную строку. Номера портов удаляются из URL, если они совпадают с номером порта по умолчанию.
urlEquals
строка необязательный
Совпадение происходит, если URL (без идентификатора фрагмента) равен указанной строке. Номера портов удаляются из URL, если они совпадают с номером порта по умолчанию.
urlMatches
строка необязательный
Совпадение происходит, если URL-адрес (без идентификатора фрагмента) соответствует указанному регулярному выражению. Номера портов удаляются из URL-адреса, если они совпадают с номером порта по умолчанию. В регулярных выражениях используется синтаксис RE2 .
urlPrefix
строка необязательный
Совпадение происходит, если URL-адрес (без идентификатора фрагмента) начинается с указанной строки. Номера портов удаляются из URL-адреса, если они совпадают с номером порта по умолчанию.
urlSuffix
строка необязательный
Совпадение происходит, если URL-адрес (без идентификатора фрагмента) заканчивается указанной строкой. Номера портов удаляются из URL-адреса, если они совпадают с номером порта по умолчанию.

chrome.events Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

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

Правила

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

Добавление правил

Удаление правил

Получение правил

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

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

Типы

Event

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

Rule

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

UrlFilter

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

chrome.events