chrome.events

Opis

Pojęcia i wykorzystanie

Event to obiekt umożliwiający otrzymywanie powiadomień, gdy wydarzy się coś interesującego. Oto przykład użycia zdarzenia chrome.alarms.onAlarm do otrzymywania powiadomień o upływie alarmu:

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

Jak widać w przykładzie, do rejestracji powiadomień używasz konta addListener(). Argument dla funkcji addListener() to zawsze funkcja, którą zdefiniujesz do obsługi zdarzenia, ale parametry parametru zależnie od obsługiwanego zdarzenia. Sprawdzam dokumentację dotyczącą alarms.onAlarm. zobaczysz, że funkcja ma 1 parametr: obiekt alarms.Alarm ze szczegółami na temat upływu czasu.

Przykładowe interfejsy API korzystające z funkcji Zdarzenia: alarms, i18n, identity, środowisko wykonawcze. Większość Chrome interfejsów API.

Deklaracyjne moduły obsługi zdarzeń

Deklaratywne moduły obsługi zdarzeń umożliwiają definiowanie reguł złożonych z warunków deklaratywnych i czynności. Warunki są oceniane w przeglądarce, a nie w mechanizmie JavaScript, co zmniejsza opóźnienia w obie strony i pozwalają na bardzo wysoką wydajność.

Deklaracyjne moduły obsługi zdarzeń są używane np. Interfejs Deklaracyjny Content API. Ta strona opisuje podstawowe pojęcia związane ze wszystkimi zdarzeniami deklaratywnymi modułów obsługi.

Reguły

Najprostsza z reguły składa się z co najmniej jednego warunku i co najmniej jednego działania:

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

W przypadku spełnienia dowolnego z warunków wykonywane są wszystkie działania.

Oprócz warunków i działań możesz nadać każdej regule identyfikator, który upraszcza wyrejestrowanie wcześniej zarejestrowanych reguł i ustalenie priorytetu, który z nich ma być brany pod uwagę. Priorytety są uwzględniane tylko wtedy, gdy reguły są sprzeczne ze sobą lub muszą być stosowane w określonym zakresie zamówienie. 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 zdarzeń, ale przetestuj, czy któraś z zarejestrowanych reguł ma co najmniej jeden spełniony warunek i wykonanie powiązane z nią działania. Obiekty zdarzeń obsługujące deklaratywny interfejs API mają trzy 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. Potrzebna jest tablica instancji reguł jako pierwszy parametr i funkcję 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ł. występują w tej samej kolejności co w przekazywanych rule_list, gdzie opcjonalne parametry id i Pole priority zostało wypełnione wygenerowanymi wartościami. Jeśli któraś reguła jest nieprawidłowa, na przykład dlatego, że zawiera nieprawidłowy warunek lub działanie, nie zostanie dodana żadna z reguł ani zmienna runtime.lastError jest ustawiany przy wywołaniu funkcji wywołania zwrotnego. Każda reguła w rule_list musi zawierać unikalny identyfikator identyfikator, który nie jest jeszcze używany przez inną regułę lub jest pusty.

Usuń reguły

Aby usunąć reguły, wywołaj funkcję removeRules(). Akceptuje opcjonalną tablicę identyfikatorów reguł jako pierwszego parametru, a funkcji wywołania zwrotnego jako drugiego.

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

Jeśli rule_ids jest tablicą identyfikatorów, wszystkie reguły zawierające identyfikatory w tablicy są usunięto. Jeśli rule_ids podaje nieznany identyfikator, zostanie on dyskretnie ignorowany. Jeśli rule_ids ma wartość undefined. Wszystkie zarejestrowane reguły tego rozszerzenia zostały usunięte. callback() jest wywoływana przy usuwaniu reguł.

Pobierz reguły

Aby pobrać listę zarejestrowanych reguł, wywołaj funkcję getRules(). Akceptuje ona opcjonalna tablica identyfikatorów reguł o tej samej semantyce co removeRules() oraz funkcja wywołania zwrotnego.

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

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

Wyniki

Aby osiągnąć maksymalną skuteczność, pamiętaj o przestrzeganiu poniższych wskazówek.

Zbiorcze rejestrowanie i wyrejestrowywanie reguł Po każdej rejestracji lub wyrejestrowaniu Chrome musi: aktualizowania wewnętrznych struktur 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]);

W obiekcie events.UrlFilter używaj dopasowywania podłańcucha zamiast wyrażeń regularnych. Dopasowywanie na podstawie podłańcuchów jest niezwykle 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 masz wiele reguł o tych samych działaniach, scal je w jedną. Reguły uruchamiają działania natychmiast po spełnieniu jednego warunku. To przyspieszy i zmniejsza wykorzystanie pamięci w przypadku zduplikowanych zestawów 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

Filtrowane zdarzenia to mechanizm, który umożliwia detektorom określenie podzbioru zdarzeń, którymi są co może Cię zainteresować. Detektor używający filtra nie zostanie wywołany w przypadku zdarzeń, które nie spełniają wartości który sprawia, że kod odtwarzania jest bardziej deklaratywny i wydajny. Skrypt service worker musi nie może się więc obudzić w związku z wydarzeniami, które są dla niego nieistotne.

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

W przypadku dopasowywania adresów URL (jak w przykładzie powyżej) filtry zdarzeń obsługują ten sam adres URL możliwości w sposób wyraźny za pomocą events.UrlFilter, z wyjątkiem dopasowania schematu i portów.