browser.events

Opis

Pojęcia i zastosowanie

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

browser.alarms.onAlarm.addListener((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 jest obsługiwane. W dokumentacji funkcji alarms.onAlarm możesz sprawdzić, że ma ona jeden parametr: obiekt alarms.Alarm, który zawiera szczegóły o upłynięciu czasu alarmu.

Przykładowe interfejsy API korzystające z wydarzeń: 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 sieciowym i pozwala osiągnąć bardzo wysoką wydajność.

Deklaratywne funkcje obsługi zdarzeń są używane np. w Declarative Content API. Na tej stronie opisano 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:

const 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ć do każdej reguły identyfikator, który ułatwia wyrejestrowywanie wcześniej zarejestrowanych reguł, oraz priorytet, który określa pierwszeństwo między regułami. 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ł.

const 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().

Dodaj reguły

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.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (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 po wywołaniu wywołania zwrotnego zostanie ustawiona zmienna runtime.lastError. Każda reguła w rule_list musi zawierać unikalny identyfikator, który nie jest jeszcze 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.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

Jeśli rule_ids jest tablicą identyfikatorów, wszystkie reguły zawierające identyfikatory wymienione w tablicy zostaną usunięte. Jeśli element rule_ids zawiera identyfikator, który jest nieznany, 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ę zarejestrowanych reguł, wywołaj funkcję getRules(). Przyjmuje opcjonalną tablicę identyfikatorów reguł o takiej samej semantyce jak removeRules() oraz funkcję wywołania zwrotnego.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

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

Wydajność

Aby uzyskać maksymalną skuteczność, pamiętaj o tych wskazówkach.

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

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

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

Preferuj dopasowywanie podciągów do wyrażeń regularnych w events.UrlFilter. Dopasowywanie na podstawie podciągów jest niezwykle szybkie.

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

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

Jeśli istnieje wiele reguł, które mają te same działania, połącz je w jedną regułę. Reguły wywołują 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ń.

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

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ą ułatwić przejście z kodu filtrowania ręcznego.

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

Zdarzenia obsługują określone filtry, które są dla nich istotne. Lista filtrów obsługiwanych przez zdarzenie jest podana w dokumentacji tego zdarzenia w sekcji „filters” (filtry).

Podczas dopasowywania 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.