chrome.events

refresh date: 2026-09-25 robots: noindex

Opis

Event to obiekt, który umożliwia otrzymywanie powiadomień o interesujących zdarzeniach. Oto przykład użycia zdarzenia chrome.alarms.onAlarm, aby otrzymywać powiadomienia o upływie czasu alarmu:

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

Jak widać na przykładzie, rejestracja powiadomienia odbywa się za pomocą funkcji addListener(). Argumentem funkcji addListener() jest zawsze zdefiniowana przez Ciebie funkcja obsługująca zdarzenie, ale parametry tej funkcji zależą od tego, które zdarzenie obsługujesz. W dokumentacji alarms.onAlarm możesz sprawdzić, że funkcja ma jeden parametr: obiekt alarms.Alarm, który zawiera szczegóły o upłynięciu czasu alarmu.

Przykładowe interfejsy API korzystające ze zdarzeń: alarms, i18n, identity, runtime. Większość interfejsów API Chrome to robi.

Deklaratywne moduły obsługi zdarzeń

Deklaratywne procedury obsługi zdarzeń umożliwiają definiowanie reguł składających się z deklaratywnych warunków i działań. Warunki są oceniane w przeglądarce, a nie w mechanizmie JavaScript, co zmniejsza opóźnienia związane z ruchem w obie strony i zapewnia bardzo wysoką wydajność.

Deklaratywne procedury obsługi zdarzeń są używane np. w interfejsie Declarative Web Request API i Declarative Content API. Na tej stronie opisujemy podstawowe koncepcje wszystkich deklaratywnych procedur obsługi zdarzeń.

Reguły

Najprostsza reguła składa się z co najmniej 1 warunku i co najmniej 1 działania:

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

Jeśli zostanie spełniony którykolwiek z warunków, zostaną wykonane wszystkie działania.

Oprócz warunków i działań możesz przypisać każdej regule identyfikator, który ułatwia wyrejestrowywanie wcześniej zarejestrowanych reguł, oraz priorytet, który określa kolejność wykonywania reguł. Priorytety są brane pod uwagę tylko wtedy, gdy reguły są ze sobą sprzeczne lub muszą być wykonywane w określonej kolejności. Działania są wykonywane w kolejności malejącej priorytetu reguł.

var rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Obiekty zdarzeń

Obiekty zdarzeń mogą obsługiwać reguły. Te obiekty zdarzeń nie wywołują wywołania zwrotnego, gdy wystąpią zdarzenia, ale sprawdzają, czy któraś z zarejestrowanych reguł ma co najmniej 1 spełniony warunek, i wykonują działania powiązane z tą regułą. Obiekty zdarzeń obsługujące deklaratywny interfejs API mają 3 odpowiednie metody: events.Event.addRules, events.Event.removeRules i events.Event.getRules.

Dodawanie reguł

Aby dodać reguły, wywołaj funkcję addRules() obiektu zdarzenia. Jako pierwszy parametr przyjmuje tablicę instancji reguł, a jako drugi – funkcję wywołania zwrotnego, która jest wywoływana po zakończeniu działania.

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

Jeśli reguły zostały wstawione, parametr details zawiera tablicę wstawionych reguł w tej samej kolejności co w przekazanym parametrze rule_list, w którym opcjonalne parametry id i priority zostały wypełnione wygenerowanymi wartościami. Jeśli któraś reguła jest nieprawidłowa, np. zawiera nieprawidłowy warunek lub działanie, żadna z reguł nie zostanie dodana, a zmienna runtime.lastError zostanie ustawiona po wywołaniu zwrotnym. Każda reguła w rule_list musi zawierać unikalny identyfikator, który nie jest obecnie używany przez inną regułę, lub pusty identyfikator.

Usuwanie reguł

Aby usunąć reguły, wywołaj funkcję removeRules(). Jako pierwszy parametr przyjmuje opcjonalną tablicę identyfikatorów reguł, a jako drugi – funkcję wywołania zwrotnego.

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

Jeśli rule_ids jest tablicą identyfikatorów, wszystkie reguły zawierające identyfikatory wymienione w tablicy zostaną usunięte. Jeśli rule_ids zawiera nieznany identyfikator, jest on ignorowany. Jeśli rule_ids ma wartość undefined, wszystkie zarejestrowane reguły tego rozszerzenia zostaną usunięte. Funkcja callback() jest wywoływana po usunięciu reguł.

Pobieranie reguł

Aby pobrać listę aktualnie zarejestrowanych reguł, wywołaj funkcję getRules(). Przyjmuje opcjonalną tablicę identyfikatorów reguł o tej samej semantyce co removeRules i funkcję wywołania zwrotnego.

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

Parametr details przekazywany do funkcji callback() odnosi się do tablicy reguł, w tym wypełnionych parametrów opcjonalnych.

Wydajność

Aby osiągnąć maksymalną skuteczność, pamiętaj o tych wytycznych.

Rejestrowanie i wyrejestrowywanie reguł zbiorczo. Po każdej rejestracji lub wyrejestrowaniu Chrome musi zaktualizować wewnętrzne struktury danych. Ta aktualizacja jest kosztowną operacją.

Zamiast:

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

prefer:

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

Preferuj dopasowywanie podłańcucha do wyrażeń regularnych w events.UrlFilter. Dopasowywanie na podstawie podciągów jest bardzo szybkie.

Zamiast:

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

prefer:

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

Jeśli masz wiele reguł, które mają te same działania, połącz je w jedną regułę. Reguły uruchamiają działania, gdy tylko zostanie spełniony jeden warunek. Przyspiesza to dopasowywanie i zmniejsza zużycie pamięci w przypadku zduplikowanych zestawów działań.

Zamiast:

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

prefer:

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

Filtrowane zdarzenia

Filtrowane zdarzenia to mechanizm, który umożliwia detektorom określanie podzbioru zdarzeń, które ich interesują. Detektor, który używa filtra, nie będzie wywoływany w przypadku zdarzeń, które nie przejdą filtra, co sprawia, że kod nasłuchiwania jest bardziej deklaratywny i wydajny. Skrypt service worker nie musi być wybudzany do obsługi zdarzeń, które go nie interesują.

Filtrowane zdarzenia mają umożliwić przejście z ręcznego filtrowania kodu, takiego jak ten:

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

w ten sposób:

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

Zdarzenia obsługują określone filtry, które są dla nich istotne. Lista filtrów obsługiwanych przez zdarzenie będzie podana w dokumentacji tego zdarzenia w sekcji „Filtry”.

W przypadku pasujących adresów URL (jak w przykładzie powyżej) filtry zdarzeń obsługują te same możliwości dopasowywania adresów URL, które można wyrazić za pomocą events.UrlFilter, z wyjątkiem dopasowywania schematu i portu.