Opis
Przestrzeń nazw chrome.events
zawiera typowe typy używane przez interfejsy API wysyłające zdarzenia w celu powiadamiania o interesujących wydarzeniach.
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.
Wydajność
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.
Typy
Event
Obiekt, który umożliwia dodawanie i usuwanie detektorów zdarzenia Chrome.
Właściwości
-
addListener
void
Rejestruje wywołanie zwrotne detektora zdarzeń.
Funkcja
addListener
wygląda tak:(callback: H) => {...}
-
wywołanie zwrotne
H
Wywoływane, gdy wystąpi zdarzenie. Parametry tej funkcji zależą od typu zdarzenia.
-
-
addRules
void
Rejestruje reguły do obsługi zdarzeń.
Funkcja
addRules
wygląda tak:(rules: Rule<anyany>[], callback?: function) => {...}
-
reguły
Reguła<dowolny>[]
Reguły do zarejestrowania. Nie zastępują one wcześniej zarejestrowanych reguł.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(rules: Rule<anyany>[]) => void
-
reguły
Reguła<dowolny>[]
Zarejestrowane reguły to parametry opcjonalne, które są wypełniane wartościami.
-
-
-
getRules
void
Zwraca obecnie zarejestrowane reguły.
Funkcja
getRules
wygląda tak:(ruleIdentifiers?: string[], callback: function) => {...}
-
ruleIdentifiers
string[] opcjonalny
Jeśli tablica jest przekazywana, 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<dowolny>[]
Zarejestrowane reguły to parametry opcjonalne, które są wypełniane wartościami.
-
-
-
hasListener
void
Funkcja
hasListener
wygląda tak:(callback: H) => {...}
-
wywołanie zwrotne
H
Nasłuchujący, którego stan rejestracji zostanie przetestowany.
-
returns
boolean
Prawda, jeśli wywołanie zwrotne jest zarejestrowane w zdarzeniu.
-
-
hasListeners
void
Funkcja
hasListeners
wygląda tak:() => {...}
-
returns
boolean
Wartość to „prawda”, jeśli w zdarzeniu są zarejestrowane detektory zdarzeń.
-
-
removeListener
void
Wyrejestrowuje ze zdarzenia wywołanie zwrotne detektora.
Funkcja
removeListener
wygląda tak:(callback: H) => {...}
-
wywołanie zwrotne
H
Detektor, który ma zostać niezarejestrowany.
-
-
removeRules
void
Wyrejestrowuje obecnie zarejestrowane reguły.
Funkcja
removeRules
wygląda tak:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] opcjonalny
Jeśli tablica jest przekazywana, wyrejestrowane są tylko reguły z identyfikatorami zawartymi w tej tablicy.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
-
Rule
Opis deklaratywnej reguły obsługi zdarzeń.
Właściwości
-
działania
każdy[]
Lista działań, które są wykonywane, gdy jeden z warunków zostanie spełniony.
-
conditions
każdy[]
Lista warunków, które mogą wywołać określone 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[] opcjonalny
Tagów można używać do dodawania adnotacji do reguł i wykonywania na nich operacji.
UrlFilter
Filtruje adresy URL na podstawie różnych kryteriów. Zobacz filtrowanie zdarzeń. We wszystkich kryteriach rozróżniana jest wielkość liter.
Właściwości
-
cidrBlocks
string[] opcjonalny
Chrome 123 i nowsze wersjeDopasowanie do hosta w adresie URL, które jest adresem IP i jest zawarte w dowolnym z bloków CIDR określonych w tablicy.
-
hostContains
ciąg znaków opcjonalny
Dopasowuje, jeśli nazwa hosta adresu URL zawiera określony ciąg znaków. Aby sprawdzić, czy składnik nazwy hosta ma prefiks „foo”, użyj polecenia hostContains: „.foo”. Dopasowuje ona wartości „www.foobar.com” i „foo.com”, ponieważ na początku nazwy hosta jest dodawana kropka. Tagu hostContains można też używać w celu dopasowania do sufiksu komponentu („foo.”) i dopasowania ścisłego do komponentów („.foo.”). Dopasowanie sufiksu i ścisłe dopasowanie ostatnich komponentów należy przeprowadzić oddzielnie przy użyciu hostaSsufiks, ponieważ na końcu nazwy hosta nie jest dodawana kropka.
-
hostEquals
ciąg znaków opcjonalny
Dopasowuje, jeśli nazwa hosta adresu URL jest równa określonemu ciągu.
-
hostPrefix
ciąg znaków opcjonalny
Dopasowuje, jeśli nazwa hosta adresu URL zaczyna się określonym ciągiem znaków.
-
hostSuffix
ciąg znaków opcjonalny
Dopasowuje, jeśli nazwa hosta adresu URL kończy się określonym ciągiem znaków.
-
originAndPathMatches
ciąg znaków opcjonalny
Dopasowuje, 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. W wyrażeniach regularnych używana jest składnia RE2.
-
pathContains
ciąg znaków opcjonalny
Dopasowuje się, jeśli segment ścieżki adresu URL zawiera określony ciąg znaków.
-
pathEquals
ciąg znaków opcjonalny
Dopasowuje, jeśli segment ścieżki adresu URL jest równy określonemu ciągowi.
-
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
Dopasowuje się, jeśli segment ścieżki adresu URL kończy się określonym ciągiem znaków.
-
ports
(liczba | liczba[])[] opcjonalny
Dopasowanie do tego, czy port danego adresu URL znajduje się na dowolnej z określonych list portów. Na przykład
[80, 443, [1000, 1200]]
dopasowuje wszystkie żądania na portach 80, 443 i w zakresie 1000–1200. -
queryContains
ciąg znaków opcjonalny
Dopasowane, jeśli segment zapytania adresu URL zawiera określony ciąg znaków.
-
queryEquals
ciąg znaków opcjonalny
Dopasowuje, jeśli segment zapytania adresu URL jest równy określonemu ciągowi.
-
queryPrefix
ciąg znaków opcjonalny
Dopasowuje, jeśli segment zapytania URL zaczyna się określonym ciągiem znaków.
-
querySuffix
ciąg znaków opcjonalny
Dopasowuje, jeśli segment zapytania adresu URL kończy się określonym ciągiem znaków.
-
schemes
string[] opcjonalny
Dopasowuje, jeśli schemat adresu URL jest równy jednemu z schematów określonych w tablicy.
-
urlContains
ciąg znaków opcjonalny
Dopasowuje, 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. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu.
-
urlMatches
ciąg znaków opcjonalny
Dopasowuje, 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. W wyrażeniach regularnych używana jest składnia RE2.
-
urlPrefix
ciąg znaków opcjonalny
Dopasowuje, jeśli adres URL (bez identyfikatora fragmentu) zaczyna się od określonego ciągu. Numery portów są usuwane z adresu URL, jeśli pasują do domyślnego numeru portu.
-
urlSuffix
ciąg znaków opcjonalny
Dopasowuje, 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 pasują do domyślnego numeru portu.