browser.events

Opis

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

Pojęcia i użycie

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, rejestrujesz się, aby otrzymywać powiadomienia, za pomocą addListener(). Argumentem metody addListener() jest zawsze funkcja, którą definiujesz do obsługi zdarzenia, ale parametry tej funkcji zależą od obsługiwanego zdarzenia. W dokumentacji alarms.onAlarm możesz sprawdzić, że funkcja ma jeden parametr: obiekt alarms.Alarm, który zawiera szczegóły dotyczące alarmu, który się włączył.

Przykładowe interfejsy API korzystające ze zdarzeń: alarms, i18n, identity, runtime. Większość interfejsów API Chrome tak robi.

Deklaratywne 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ą oceniane w przeglądarce, a nie w mechanizmie JavaScriptu, co zmniejsza opóźnienia i pozwala na bardzo wysoką wydajność.

Deklaratywne moduły obsługi zdarzeń są używane na przykład w interfejsie Declarative Content API. Na tej stronie opisano podstawowe pojęcia dotyczące wszystkich deklaratywnych modułów 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 którykolwiek z warunków zostanie spełniony, zostaną wykonane wszystkie działania.

Oprócz warunków i działań możesz nadać każdej regule identyfikator, który upraszcza wyrejestrowywanie wcześniej zarejestrowanych reguł, oraz priorytet, który określa kolejność reguł. 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 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ąpią zdarzenia, ale sprawdzają, czy jakakolwiek zarejestrowana reguła 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 reklamowe, wywołaj funkcję addRules() obiektu zdarzenia. Jako pierwszy parametr przyjmuje tablicę instancji reguł, a jako drugi – wywołanie zwrotne, które jest wywoływane po zakończeniu.

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

Jeśli reguły zostały wstawione prawidłowo, parametr details zawiera tablicę wstawionych reguł, które pojawiają się 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ś z reguł jest nieprawidłowa, na przykład zawiera nieprawidłowy warunek lub działanie, żadna z reguł nie zostanie dodana, a zmienna runtime.lastError zostanie ustawiona po wywołaniu funkcji wywołania zwrotnego. Każda reguła w pliku rule_list musi zawierać unikalny identyfikator, który nie jest już 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 z identyfikatorami wymienionymi w tablicy zostaną usunięte. Jeśli rule_ids zawiera nieznany identyfikator, jest on ignorowany bez powiadomienia. 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(). Akceptuje opcjonalną tablicę identyfikatorów reguł o tej samej semantyce co 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ł, w tym wypełnionych parametrów opcjonalnych.

Wydajność

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

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

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

W events.UrlFilter preferuj dopasowywanie podłańcuchów zamiast wyrażeń regularnych. Dopasowywanie na podstawie podłańcucha jest bardzo szybkie.

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

Jeśli masz wiele reguł, które mają te same działania, 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 w przypadku zduplikowanych zestawów działań.

zamiast
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]);
Preferowane
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ślenie podzbioru zdarzeń, które ich interesują. Detektor, który używa filtra, nie będzie wywoływany w przypadku zdarzeń, które nie przejdą przez filtr, co sprawia, że kod detektora jest bardziej deklaratywny i wydajny. Skryptu service worker nie trzeba wybudzać, aby obsługiwał zdarzenia, które go nie dotyczą.

Zdarzenia filtrowane mają umożliwiać przejście z ręcznego kodu filtrowania.

zamiast
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Preferowane
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 znajduje się w dokumentacji tego zdarzenia 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, które można wyrazić za pomocą events.UrlFilter, z wyjątkiem dopasowywania schematu i portu.

Typy

Event

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

Właściwości

  • addListener

    unieważnienie,

    Rejestruje wywołanie zwrotne detektora zdarzeń w przypadku zdarzenia.

    Funkcja addListener wygląda tak:

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

    • callback

      H

      Wywoływana, gdy wystąpi zdarzenie. Parametry tej funkcji zależą od typu zdarzenia.

  • addRules

    unieważnienie,

    Rejestruje reguły obsługi zdarzeń.

    Funkcja addRules wygląda tak:

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

    • reguły

      Rule<anyany>[]

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

    • callback

      function opcjonalne

      Parametr callback wygląda tak:

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

      • reguły

        Rule<anyany>[]

        Reguły, które zostały zarejestrowane, parametry opcjonalne są wypełnione wartościami.

  • getRules

    unieważnienie,

    Zwraca obecnie zarejestrowane reguły.

    Funkcja getRules wygląda tak:

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

    • ruleIdentifiers

      string[] opcjonalne

      Jeśli przekazywana jest tablica, zwracane są tylko reguły z identyfikatorami zawartymi w tej tablicy.

    • callback

      funkcja

      Parametr callback wygląda tak:

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

      • reguły

        Rule<anyany>[]

        Reguły, które zostały zarejestrowane, parametry opcjonalne są wypełnione wartościami.

  • hasListener

    unieważnienie,

    Funkcja hasListener wygląda tak:

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

    • callback

      H

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

    • returns

      wartość logiczna

      Wartość True, jeśli wywołanie zwrotne jest zarejestrowane w zdarzeniu.

  • hasListeners

    unieważnienie,

    Funkcja hasListeners wygląda tak:

    () => {...}

    • returns

      wartość logiczna

      Wartość „true”, jeśli do zdarzenia są zarejestrowane jakieś detektory zdarzeń.

  • removeListener

    unieważnienie,

    Wyrejestrowuje wywołanie zwrotne detektora zdarzeń ze zdarzenia.

    Funkcja removeListener wygląda tak:

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

    • callback

      H

      Detektor, który ma zostać wyrejestrowany.

  • removeRules

    unieważnienie,

    Wyrejestrowuje obecnie zarejestrowane reguły.

    Funkcja removeRules wygląda tak:

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

    • ruleIdentifiers

      string[] opcjonalne

      Jeśli przekazywana jest tablica, wyrejestrowywane są tylko reguły z identyfikatorami zawartymi w tej tablicy.

    • callback

      function opcjonalne

      Parametr callback wygląda tak:

      () => void

Rule

Opis reguły deklaratywnej dotyczącej obsługi zdarzeń.

Właściwości

  • działania

    any[]

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

  • schorzenia

    any[]

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

  • id

    ciąg znaków opcjonalny

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

  • kampanii

    number optional

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

  • Tagi

    string[] opcjonalne

    Tagi mogą służyć do dodawania adnotacji do reguł i wykonywania operacji na zestawach reguł.

UrlFilter

Filtruje adresy URL według różnych kryteriów. Zobacz filtrowanie zdarzeń. We wszystkich kryteriach wielkość liter ma znaczenie.

Właściwości

  • cidrBlocks

    string[] opcjonalne

    Chrome 123 lub nowsza browser.* od Chrome 148

    Dopasowanie występuje, jeśli część adresu URL zawierająca hosta jest adresem IP i znajduje się w dowolnym bloku CIDR określonym w tablicy.

  • hostContains

    ciąg znaków opcjonalny

    Dopasowanie, jeśli nazwa hosta adresu URL zawiera określony ciąg znaków. Aby sprawdzić, czy komponent nazwy hosta ma prefiks „foo”, użyj hostContains: „.foo”. Pasuje do „www.foobar.com” i „foo.com”, ponieważ na początku nazwy hosta dodawana jest domyślna kropka. Podobnie hostContains może służyć do dopasowywania sufiksu komponentu („foo.”) i dokładnego dopasowywania komponentów („.foo.”). Dopasowanie sufiksu i dopasowanie ścisłe w przypadku ostatnich komponentów należy wykonać osobno za pomocą hostSuffix, ponieważ na końcu nazwy hosta nie jest dodawana kropka.

  • hostEquals

    ciąg znaków opcjonalny

    Dopasowanie występuje, gdy nazwa hosta w adresie URL jest równa określonemu ciągowi znaków.

  • hostPrefix

    ciąg znaków opcjonalny

    Dopasowanie, jeśli nazwa hosta adresu URL zaczyna się od określonego ciągu znaków.

  • hostSuffix

    ciąg znaków opcjonalny

    Dopasowanie występuje, jeśli nazwa hosta adresu URL kończy się określonym ciągiem znaków.

  • originAndPathMatches

    ciąg znaków opcjonalny

    Dopasowanie występuje, gdy 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 są zgodne z domyślnym numerem portu. Wyrażenia regularne używają składni RE2.

  • pathContains

    ciąg znaków opcjonalny

    Dopasowanie występuje, jeśli segment ścieżki adresu URL zawiera określony ciąg znaków.

  • pathEquals

    ciąg znaków opcjonalny

    Dopasowanie występuje, gdy segment ścieżki adresu URL jest równy określonemu ciągowi znaków.

  • pathPrefix

    ciąg znaków opcjonalny

    Dopasowanie, jeśli segment ścieżki adresu URL zaczyna się od określonego ciągu znaków.

  • pathSuffix

    ciąg znaków opcjonalny

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

  • ports

    (number | number[])[] opcjonalny

    Dopasowanie, jeśli port adresu URL znajduje się na dowolnej z podanych list portów. Na przykład [80, 443, [1000, 1200]] pasuje do wszystkich żądań na portach 80, 443 i w zakresie 1000–1200.

  • queryContains

    ciąg znaków opcjonalny

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

  • queryEquals

    ciąg znaków opcjonalny

    Dopasowanie występuje, gdy segment zapytania w adresie URL jest równy określonemu ciągowi znaków.

  • queryPrefix

    ciąg znaków opcjonalny

    Dopasowanie, jeśli segment zapytania adresu URL zaczyna się od określonego ciągu znaków.

  • querySuffix

    ciąg znaków opcjonalny

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

  • schematy

    string[] opcjonalne

    Dopasowanie, jeśli schemat adresu URL jest taki sam jak którykolwiek ze schematów określonych w tablicy.

  • urlContains

    ciąg znaków opcjonalny

    Dopasowanie, jeśli adres URL (bez identyfikatora fragmentu) zawiera określony ciąg znaków. Numery portów są usuwane z adresu URL, jeśli są zgodne z domyślnym numerem portu.

  • urlEquals

    ciąg znaków opcjonalny

    Reguła jest spełniona, 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 są zgodne z domyślnym numerem portu.

  • urlMatches

    ciąg znaków opcjonalny

    Warunek jest spełniony, jeśli adres URL (bez identyfikatora fragmentu) pasuje do określonego wyrażenia regularnego. Numery portów są usuwane z adresu URL, jeśli są zgodne z domyślnym numerem portu. Wyrażenia regularne używają składni RE2.

  • urlPrefix

    ciąg znaków opcjonalny

    Dopasowanie, jeśli adres URL (bez identyfikatora fragmentu) zaczyna się od określonego ciągu znaków. Numery portów są usuwane z adresu URL, jeśli są zgodne z domyślnym numerem portu.

  • urlSuffix

    ciąg znaków opcjonalny

    Dopasowanie, jeśli adres URL (bez identyfikatora fragmentu) kończy się określonym ciągiem znaków. Numery portów są usuwane z adresu URL, jeśli są zgodne z domyślnym numerem portu.