Opis
Przestrzeń nazw chrome.events
zawiera typowe typy używane przez interfejsy API wysyłające zdarzenia w celu powiadamiania o interesujących wydarzeniach.
Event
to obiekt, który pozwala 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(function(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ść.
Deklaratywne moduły obsługi zdarzeń są używane na przykład w interfejsach deklaratywnego żądania internetowego i deklaratywnego 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:
var 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ł.
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 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
.
Dodawanie reguł
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.
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ł 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 akcję, ż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 obecnie 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 parametr – funkcję wywołania zwrotnego.
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
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ł.
Pobieranie reguł
Aby pobrać listę obecnie zarejestrowanych reguł, wywołaj funkcję getRules()
. Akceptuje opcjonalną tablicę identyfikatorów reguł o tej samej semantyce co element removeRules
i funkcję wywołania zwrotnego.
var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(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.
Zamiast:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
preferuj:
var rule1 = {...};
var 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.
Zamiast:
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {urlMatches: "example.com/[^?]*foo" } });
preferuj:
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, gdy tylko zostanie spełniony jeden warunek. Przyspiesza to dopasowywanie i zmniejsza zużycie pamięci przez zduplikowane zestawy 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]);
preferuj:
var 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 w ten sposób:
chrome.webNavigation.onCommitted.addListener(function(e) {
if (hasHostSuffix(e.url, 'google.com') ||
hasHostSuffix(e.url, 'google.com.au')) {
// ...
}
});
do tego:
chrome.webNavigation.onCommitted.addListener(function(e) {
// ...
}, {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.