chrome.events

Opis

Przestrzeń nazw chrome.events zawiera typowe typy wykorzystywane przez interfejsy API wysyłające zdarzenia, aby powiadamiać Cię, gdy wydarzy się coś interesującego.

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.

Uwaga: Uwaga: reguły są trwałe podczas sesji przeglądania. Dlatego instaluj reguły w trakcie czas instalacji rozszerzenia za pomocą zdarzenia runtime.onInstalled. Zwróć uwagę, że to zdarzenie jest uruchamianych również po zaktualizowaniu rozszerzenia. Dlatego najpierw wyczyść wcześniej zainstalowane reguły, a następnie zarejestruj nowe reguły.

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.

Filtrowane zdarzenia mają umożliwiać przejście od kodu filtrowania ręcznego w ten sposób:

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 mają dla niego znaczenie. Lista filtrów używanych przez zdarzenie obsługiwane dane są wymienione w dokumentacji tego zdarzenia w sekcji „filtry” .

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.

Typy

Event

Obiekt, który umożliwia dodawanie i usuwanie detektorów zdarzenia Chrome.

Właściwości

• addListener

  nieważne

  Rejestruje detektor wywołania zwrotnego zdarzenia.

  Funkcja addListener wygląda tak:

  (callback: H) => {...}

  • wywołanie zwrotne

    H

    Wywoływane po wystąpieniu zdarzenia. Parametry tej funkcji zależą od typu zdarzenia.

• addRules

  nieważne

  Rejestruje reguły obsługi zdarzeń.

  Funkcja addRules wygląda tak:

  (rules: Rule<anyany>[], callback?: function) => {...}

  • reguły

    Reguła<dowolna>[]

    Reguły do zarejestrowania. Nie zastępują one wcześniej zarejestrowanych reguł.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak:

    (rules: Rule<anyany>[]) => void

    • reguły

      Reguła<dowolna>[]

      Zarejestrowane reguły; parametry opcjonalne są wypełniane wartościami.

• getRules

  nieważne

  Zwraca obecnie zarejestrowane reguły.

  Funkcja getRules wygląda tak:

  (ruleIdentifiers?: string[], callback: function) => {...}

  • ruleIdentifiers

    string[] opcjonalnie

    Jeśli tablica zostanie przekazana, zwracane są tylko reguły, które zawierają zawarte w niej identyfikatory.

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak:

    (rules: Rule<anyany>[]) => void

    • reguły

      Reguła<dowolna>[]

      Zarejestrowane reguły; parametry opcjonalne są wypełniane wartościami.

• hasListener

  nieważne

  Funkcja hasListener wygląda tak:

  (callback: H) => {...}

  • wywołanie zwrotne

    H

    Detektor, którego stan rejestracji ma zostać przetestowany.

  • returns

    wartość logiczna

    Prawda, jeśli zdarzenie wywołania zwrotnego jest zarejestrowane.

• hasListeners

  nieważne

  Funkcja hasListeners wygląda tak:

  () => {...}

  • returns

    wartość logiczna

    Prawda, jeśli w zdarzeniu są zarejestrowani detektory zdarzeń.

• removeListener,

  nieważne

  Wyrejestrowuje ze zdarzenia wywołanie zwrotne detektora zdarzeń.

  Funkcja removeListener wygląda tak:

  (callback: H) => {...}

  • wywołanie zwrotne

    H

    Odbiornik, który zostanie niezarejestrowany.

• removeRules

  nieważne

  Wyrejestrowuje obecnie zarejestrowane reguły.

  Funkcja removeRules wygląda tak:

  (ruleIdentifiers?: string[], callback?: function) => {...}

  • ruleIdentifiers

    string[] opcjonalnie

    Jeśli tablica jest przekazywana, wyrejestrowane są tylko reguły, które zawierają zawarte w niej identyfikatory.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak:

    () => void

Rule

Opis reguły deklaratywnej do obsługi zdarzeń.

Właściwości

• działania

  dowolne[]

  Lista działań, które są wywoływane, gdy jeden z warunków jest spełniony.

• warunku

  dowolne[]

  Lista warunków, które mogą aktywować działania.

• id

  ciąg znaków opcjonalny

  Opcjonalny identyfikator, który umożliwia odwoływanie się do tej reguły.

• kampanii

  liczba opcjonalnie

  Opcjonalny priorytet tej reguły. Domyślna wartość to 100.

• tagi

  string[] opcjonalnie

  Za ich pomocą można dodawać adnotacje do reguł i wykonywać operacje na ich zbiorach.

UrlFilter

Filtruje adresy URL pod kątem różnych kryteriów. Zobacz Filtrowanie zdarzeń. Wielkość liter we wszystkich kryteriach ma znaczenie.

Właściwości

• cidrBlocks

  string[] opcjonalnie

  Chrome w wersji 123 lub nowszej .

  Dopasowanie, jeśli część adresu URL będąca hostem jest adresem IP i znajduje się w dowolnym z bloków CIDR określonych w tablicy.

• hostContains

  ciąg znaków opcjonalny

  Pasuje, jeśli nazwa hosta w adresie URL zawiera określony ciąg. Aby sprawdzić, czy komponent nazwy hosta ma prefiks „foo”, użyj parametru hostContains: „.foo”. Pasuje do „www.foobar.com”. i „foo.com”, ponieważ na początku nazwy hosta jest dodawana kropka. Komponent hostContains może też służyć do dopasowywania do sufiksu komponentu („foo.”) lub dokładnego dopasowania do komponentów („.foo.”). Dopasowanie sufiksu i dopasowania ścisłego ostatnich komponentów trzeba wykonać oddzielnie za pomocą parametru hostSuffix, ponieważ na końcu nazwy hosta nie jest dodawana żadna niepewna kropka.

• hostEquals

  ciąg znaków opcjonalny

  Dopasowuje się, jeśli nazwa hosta w adresie URL jest równa określonemu ciągowi znaków.

• hostPrefix

  ciąg znaków opcjonalny

  Dopasowuje się, jeśli nazwa hosta adresu URL zaczyna się określonym ciągiem znaków.

• hostSuffix

  ciąg znaków opcjonalny

  Pasuje, jeśli nazwa hosta w adresie URL kończy się określonym ciągiem.

• originAndPathMatches

  ciąg znaków opcjonalny

  Pasuje, jeśli adres URL bez segmentu zapytania i identyfikatora fragmentu pasuje do określonego wyrażenia regularnego. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu. Wyrażenia regularne używają składni RE2.

• pathContains

  ciąg znaków opcjonalny

  Pasuje, jeśli segment ścieżki adresu URL zawiera określony ciąg.

• pathEquals

  ciąg znaków opcjonalny

  Dopasowuje się, jeśli segment ścieżki adresu URL jest równy określonemu ciągowi znaków.

• pathPrefix

  ciąg znaków opcjonalny

  Dopasowuje się, jeśli segment ścieżki adresu URL zaczyna się określonym ciągiem znaków.

• pathSuffix

  ciąg znaków opcjonalny

  Pasuje, jeśli segment ścieżki adresu URL kończy się określonym ciągiem.

• ports

  (liczba | numer[])[] opcjonalny

  Pasuje, jeśli port adresu URL jest na dowolnej z określonych list portów. Na przykład [80, 443, [1000, 1200]] dopasowuje wszystkie żądania na porcie 80, 443 i z zakresu 1000–1200.

• queryContains

  ciąg znaków opcjonalny

  Pasuje, jeśli segment zapytania w adresie URL zawiera określony ciąg znaków.

• queryEquals

  ciąg znaków opcjonalny

  Dopasowuje, jeśli segment zapytania w adresie URL jest równy określonemu ciągowi znaków.

• queryPrefix

  ciąg znaków opcjonalny

  Dopasowuje, jeśli segment zapytania adresu URL zaczyna się określonym ciągiem znaków.

• querySuffix

  ciąg znaków opcjonalny

  Pasuje, jeśli segment zapytania w adresie URL kończy się określonym ciągiem znaków.

• schematy

  string[] opcjonalnie

  Dopasowuje, jeśli schemat adresu URL jest równy dowolnemu ze schematów określonych w tablicy.

• urlContains

  ciąg znaków opcjonalny

  Pasuje, jeśli adres URL (bez identyfikatora fragmentu) zawiera określony ciąg znaków. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu.

• urlEquals

  ciąg znaków opcjonalny

  Dopasowuje, jeśli adres URL (bez identyfikatora fragmentu) jest równy określonemu ciągowi znaków. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu.

• urlMatches

  ciąg znaków opcjonalny

  Pasuje, jeśli adres URL (bez identyfikatora fragmentu) pasuje do określonego wyrażenia regularnego. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu. Wyrażenia regularne używają składni RE2.

• urlPrefix

  ciąg znaków opcjonalny

  Pasuje, jeśli adres URL (bez identyfikatora fragmentu) zaczyna się określonym ciągiem znaków. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu.

• urlSuffix

  ciąg znaków opcjonalny

  Pasuje, jeśli adres URL (bez identyfikatora fragmentu) kończy się określonym ciągiem. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu.