chrome.events

Opis

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(function(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. w interfejsie Detectative Web Request API oraz 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:

var 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ł.

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ą 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.

Dodawanie reguł

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.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(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, np. 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 aktualnie używany przez inną regułę lub jest pusty.

Usuwam 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.

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 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ł.

Pobieram reguły

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

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(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.

Zamiast:

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

preferowany:

var rule1 = {...};
var 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.

Zamiast:

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

preferowane:

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

Jeśli wiele reguł ma te same działania, 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ń.

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

preferowany:

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

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.