chrome.events

Opis

Pojęcia i zastosowanie

Event to obiekt, dzięki któremu możesz otrzymywać powiadomienia, gdy wydarzy się coś interesującego. Oto przykład użycia zdarzenia chrome.alarms.onAlarm do wysyłania powiadomień po zakończeniu alarmu:

chrome.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Jak pokazujemy w tym przykładzie, do zarejestrowania się w celu otrzymywania powiadomień służy addListener(). Argumentem funkcji addListener() jest zawsze funkcja zdefiniowana przez Ciebie na potrzeby obsługi zdarzenia, ale parametry funkcji zależą od obsługi. W dokumentacji funkcji alarms.onAlarm możesz zobaczyć, że funkcja zawiera 1 parametr: obiekt alarms.Alarm, który zawiera szczegółowe informacje o zakończonym alarmie.

Przykładowe interfejsy API korzystające ze zdarzeń: alarmy, i18n, tożsamość, środowisko wykonawcze. Tak jest większość interfejsów API Chrome.

Deklaracyjne moduły obsługi zdarzeń

Deklaratywne moduły obsługi zdarzeń umożliwiają definiowanie reguł składających się z deklaratywnych warunków i działań. Warunki są sprawdzane w przeglądarce, a nie przez mechanizm JavaScript, co skraca czas oczekiwania w obie strony i pozwala na bardzo wysoką wydajność.

Deklaracyjne moduły obsługi zdarzeń są używane na przykład w interfejsie Deklaracja Content API. Na tej stronie opisujemy podstawowe pojęcia dotyczące wszystkich deklaratywnych modułów obsługi zdarzeń.

Reguły

Najprostsza możliwa reguła składa się z co najmniej jednego warunku i co najmniej jednego działania:

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

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

Oprócz warunków i działań możesz nadać każdej regule identyfikator, który ułatwia wyrejestrowanie wcześniej zarejestrowanych reguł i nadanie priorytetu definiowaniu pierwszeństwa między regułami. Priorytety są uwzględniane tylko wtedy, gdy reguły są ze sobą sprzeczne lub muszą zostać wykonane w określonej kolejności. Działania są wykonywane w kolejności malejącej według 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ą funkcji wywołania zwrotnego, gdy występują zdarzenia, ale sprawdzają, czy któraś zarejestrowana reguła ma co najmniej jeden spełniony warunek i wykonuje działania powiązane z tą regułą. Obiekty zdarzeń obsługujące deklaratywny interfejs API mają 3 istotne metody: events.Event.addRules(), events.Event.removeRules() i events.Event.getRules().

Dodaj reguły

Aby dodać reguły, wywołaj funkcję addRules() obiektu zdarzenia. Pierwszym parametrem jest tablica instancji reguł oraz funkcja wywołania zwrotnego, która jest wywoływana po zakończeniu.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Jeśli reguły zostały wstawione, parametr details będzie zawierał tablicę wstawionych reguł wyświetlanych w tej samej kolejności co w przekazanych wartościach rule_list, gdzie opcjonalne parametry id i priority zostały wypełnione wygenerowanymi wartościami. Jeśli jakakolwiek reguła jest nieprawidłowa (np. zawiera nieprawidłowy warunek lub działanie), żadna reguła nie jest dodawana, a zmienna runtime.lastError jest ustawiana przy wywołaniu funkcji wywołania zwrotnego. Każda reguła w dyrektywie rule_list musi zawierać unikalny identyfikator, który nie jest już używany przez inną regułę, lub pusty identyfikator.

Usuń reguły

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

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

Jeśli rule_ids to tablica identyfikatorów, wszystkie reguły, które mają wymienione w niej identyfikatory, są usuwane. Jeśli rule_ids zawiera nieznany identyfikator, jest on dyskretnie ignorowany. Jeśli rule_ids ma wartość undefined, wszystkie zarejestrowane reguły w tym rozszerzeniu zostaną usunięte. Funkcja callback() jest wywoływana po usunięciu reguł.

Pobierz reguły

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

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

Parametr details przekazywany do funkcji callback() odnosi się do tablicy reguł zawierającej wypełnione parametry opcjonalne.

Występy

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

Zbiorcze rejestrowanie i wyrejestrowywanie reguł Po każdej rejestracji lub wyrejestrowaniu Chrome musi zaktualizować wewnętrzne struktury danych. Ta aktualizacja jest kosztowna.

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

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

Wybieraj w elemencie events.UrlFilter dopasowanie podłańcucha zamiast wyrażeń regularnych. Dopasowywanie na podstawie podłańcucha jest bardzo szybkie.

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

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

Jeśli istnieje wiele reguł o tych samych działaniach, scal je w jedną. Reguły uruchamiają działania, gdy tylko zostanie spełniony jeden warunek. Przyspiesza to dopasowywanie i zmniejsza zużycie pamięci przez zduplikowane zestawy działań.

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

Filtrowane zdarzenia

Odfiltrowane zdarzenia to mechanizm, który umożliwia detektorom określanie podzbioru zdarzeń, którymi są zainteresowani. Detektor używający filtra nie będzie wywoływany w przypadku zdarzeń, które nie przejdą filtra, co zwiększa deklaratywne i wydajność kodu nasłuchiwania. Skrypt service worker nie musi być uruchamiany, by obsługiwać zdarzenia, które go nie interesują.

Odfiltrowane zdarzenia umożliwiają przejście z kodu ręcznego filtrowania.

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

Zdarzenia obsługują określone filtry, które mają znaczenie dla danego zdarzenia. Listę filtrów obsługiwanych przez zdarzenie znajdziesz w jego dokumentacji w sekcji „Filtry”.

W przypadku dopasowywania adresów URL (jak w przykładzie powyżej) filtry zdarzeń obsługują te same możliwości dopasowywania adresów URL co w events.UrlFilter, z wyjątkiem dopasowania schematu i portu.