Beschreibung
Der chrome.events
-Namespace enthält gängige Typen, die von APIs verwendet werden, um Sie über interessante Ereignisse zu benachrichtigen.
Konzepte und Nutzung
Ein Event
ist ein Objekt, über das du benachrichtigt wirst, wenn etwas Interessantes passiert. Hier ein Beispiel für die Verwendung des Ereignisses chrome.alarms.onAlarm
, mit dem immer dann benachrichtigt wird, wenn ein Alarm abgelaufen ist:
chrome.alarms.onAlarm.addListener((alarm) => {
appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});
Wie im Beispiel gezeigt, registrieren Sie sich mit addListener()
für Benachrichtigungen. Das Argument für addListener()
ist immer eine Funktion, die Sie zum Verarbeiten des Ereignisses definieren. Die Parameter der Funktion hängen jedoch davon ab, welches Ereignis Sie verarbeiten. In der Dokumentation zu alarms.onAlarm
sehen Sie, dass die Funktion einen einzelnen Parameter hat: ein alarms.Alarm
-Objekt, das Details zum abgelaufenen Alarm enthält.
Beispiel-APIs mit Ereignissen: alarms, i18n, identity, runtime. Die meisten Chrome APIs tun das.
Deklarative Event-Handler
Die deklarativen Event-Handler bieten die Möglichkeit, Regeln zu definieren, die aus deklarativen Bedingungen und Aktionen bestehen. Bedingungen werden im Browser und nicht in der JavaScript-Engine ausgewertet. Dadurch werden Roundtrip-Latenzen verringert und eine sehr hohe Effizienz ermöglicht.
Deklarative Event-Handler werden beispielsweise in der deklarativen Content API verwendet. Auf dieser Seite werden die zugrunde liegenden Konzepte aller deklarativen Event-Handler beschrieben.
Regeln
Die einfachste mögliche Regel besteht aus einer oder mehreren Bedingungen und einer oder mehreren Aktionen:
const rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Wenn eine der Bedingungen erfüllt ist, werden alle Aktionen ausgeführt.
Zusätzlich zu Bedingungen und Aktionen können Sie jeder Regel eine Kennung zuweisen, um das Aufheben der Registrierung zuvor registrierter Regeln zu vereinfachen. Außerdem haben Sie die Möglichkeit, Prioritäten für Regeln festzulegen. Prioritäten werden nur dann berücksichtigt, wenn Regeln miteinander in Konflikt stehen oder in einer bestimmten Reihenfolge ausgeführt werden müssen. Aktionen werden in absteigender Reihenfolge nach der Priorität ihrer Regeln ausgeführt.
const rule = {
id: "my rule", // optional, will be generated if not set.
priority: 100, // optional, defaults to 100.
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Ereignisobjekte
Ereignisobjekte unterstützen möglicherweise Regeln. Diese Ereignisobjekte rufen keine Callback-Funktion auf, wenn Ereignisse eintreten, sondern testen, ob eine registrierte Regel mindestens eine erfüllte Bedingung hat, und führen die mit dieser Regel verknüpften Aktionen aus. Ereignisobjekte, die die deklarative API unterstützen, haben drei relevante Methoden: events.Event.addRules()
, events.Event.removeRules()
und events.Event.getRules()
.
Regeln hinzufügen
Rufen Sie zum Hinzufügen von Regeln die Funktion addRules()
des Ereignisobjekts auf. Der erste Parameter ist ein Array von Regelinstanzen und eine Callback-Funktion, die nach Abschluss aufgerufen wird.
const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});
Wenn die Regeln erfolgreich eingefügt wurden, enthält der Parameter details
ein Array eingefügter Regeln, die in derselben Reihenfolge wie im übergebenen rule_list
erscheinen, wobei die optionalen Parameter id
und priority
mit den generierten Werten gefüllt wurden. Wenn eine Regel ungültig ist, z. B. weil sie eine ungültige Bedingung oder Aktion enthielt, wird beim Aufruf der Callback-Funktion keine der Regeln hinzugefügt und die Variable runtime.lastError wird festgelegt. Jede Regel in rule_list
muss eine eindeutige Kennung enthalten, die noch nicht von einer anderen Regel verwendet wird, oder eine leere Kennung.
Regeln entfernen
Rufen Sie die Funktion removeRules()
auf, um Regeln zu entfernen. Als erster Parameter ist ein optionales Array mit Regelkennungen und als zweiter Parameter eine Callback-Funktion zulässig.
const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});
Wenn rule_ids
ein Array von Kennungen ist, werden alle Regeln mit im Array aufgeführten Kennungen entfernt. Wenn rule_ids
eine unbekannte Kennung aufführt, wird sie ignoriert. Wenn rule_ids
den Wert undefined
hat, werden alle registrierten Regeln dieser Erweiterung entfernt. Die Funktion callback()
wird aufgerufen, nachdem die Regeln entfernt wurden.
Regeln abrufen
Rufen Sie die Funktion getRules()
auf, um eine Liste der registrierten Regeln abzurufen. Sie akzeptiert ein optionales Array von Regelkennungen mit derselben Semantik wie removeRules()
und eine Callback-Funktion.
const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});
Der an die Funktion callback()
übergebene Parameter details
verweist auf ein Regelarray, das gefüllte optionale Parameter enthält.
Leistung
Um die Leistung zu maximieren, sollten Sie die folgenden Richtlinien beachten.
Mehrere Regeln gleichzeitig registrieren und ihre Registrierung aufheben Nach jeder Registrierung oder Aufhebung muss Chrome interne Datenstrukturen aktualisieren. Diese Aktualisierung ist ein kostspieliger Vorgang.
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1]); chrome.declarativeWebRequest.onRequest.addRules([rule2]);
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
Bevorzugen einen Teilstringabgleich regulären Ausdrücken in einem events.UrlFilter. Der Abgleich auf Teilstrings ist extrem schnell.
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {urlMatches: "example.com/[^?]*foo" } });
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {hostSuffix: "example.com", pathContains: "foo"} });
Wenn es mehrere Regeln mit denselben Aktionen gibt, führen Sie die Regeln zusammen. Regeln lösen ihre Aktionen aus, sobald eine bestimmte Bedingung erfüllt ist. Dies beschleunigt den Abgleich und reduziert den Arbeitsspeicherverbrauch für doppelte Aktionsgruppen.
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]);
Gefilterte Ereignisse
Gefilterte Ereignisse sind ein Mechanismus, mit dem Listener eine Teilmenge der Ereignisse angeben können, an denen sie interessiert sind. Ein Listener, der einen Filter verwendet, wird bei Ereignissen, die den Filter nicht bestehen, nicht aufgerufen. Dadurch wird der Überwachungscode deklarativer und effizienter. Ein Service Worker muss nicht mit Ereignissen geweckt werden, die für ihn irrelevant sind.
Gefilterte Ereignisse sollen einen Übergang vom manuellen Filtern von Code ermöglichen.
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'}]});
Ereignisse unterstützen bestimmte Filter, die für dieses Ereignis relevant sind. Die Liste der von einem Ereignis unterstützten Filter ist in der Dokumentation des Ereignisses im Bereich „Filter“ aufgeführt.
Beim Abgleich von URLs (wie im Beispiel oben) unterstützen Ereignisfilter dieselben Funktionen für den URL-Abgleich, die auch mit einem events.UrlFilter
ausgedrückt werden können, mit Ausnahme des Schema- und Portabgleichs.
Typen
Event
Ein Objekt, das das Hinzufügen und Entfernen von Listenern für ein Chrome-Ereignis ermöglicht.
Attribute
-
addListener
void
Registriert einen Event-Listener-Callback für ein Ereignis.
Die Funktion
addListener
sieht so aus:(callback: H) => {...}
-
callback
H
Wird aufgerufen, wenn ein Ereignis eintritt. Die Parameter dieser Funktion hängen vom Ereignistyp ab.
-
-
addRules
void
Registriert Regeln zur Verarbeitung von Ereignissen.
Die Funktion
addRules
sieht so aus:(rules: Rule<anyany>[], callback?: function) => {...}
-
Regeln
Regel<beliebig>[]
Zu registrierende Regeln. Bereits registrierte Regeln werden dadurch nicht ersetzt.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(rules: Rule<anyany>[]) => void
-
Regeln
Regel<beliebig>[]
Regeln, die registriert wurden; die optionalen Parameter werden mit Werten gefüllt.
-
-
-
getRules
void
Gibt aktuell registrierte Regeln zurück.
Die Funktion
getRules
sieht so aus:(ruleIdentifiers?: string[], callback: function) => {...}
-
ruleIdentifiers
string[] optional
Wenn ein Array übergeben wird, werden nur Regeln mit Kennungen zurückgegeben, die in diesem Array enthalten sind.
-
callback
Funktion
Der Parameter
callback
sieht so aus:(rules: Rule<anyany>[]) => void
-
Regeln
Regel<beliebig>[]
Regeln, die registriert wurden; die optionalen Parameter werden mit Werten gefüllt.
-
-
-
hasListener
void
Die Funktion
hasListener
sieht so aus:(callback: H) => {...}
-
callback
H
Listener, dessen Registrierungsstatus getestet werden soll.
-
Gibt zurück
boolean
Dieser Wert ist „True“, wenn callback für das Ereignis registriert ist.
-
-
hasListeners
void
Die Funktion
hasListeners
sieht so aus:() => {...}
-
Gibt zurück
boolean
Dieser Wert ist „True“, wenn Event-Listener für das Ereignis registriert sind.
-
-
removeListener
void
Hebt die Registrierung eines Event-Listener-Callbacks aus einem Ereignis auf.
Die Funktion
removeListener
sieht so aus:(callback: H) => {...}
-
callback
H
Listener, der nicht registriert werden soll.
-
-
removeRules
void
Hebt die Registrierung derzeit registrierter Regeln auf
Die Funktion
removeRules
sieht so aus:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] optional
Wenn ein Array übergeben wird, werden nur Regeln mit Kennungen, die in diesem Array enthalten sind, nicht registriert.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
-
Rule
Beschreibung einer deklarativen Regel für die Verarbeitung von Ereignissen.
Attribute
-
Aktionen
beliebige[]
Liste der Aktionen, die ausgelöst werden, wenn eine der Bedingungen erfüllt ist.
-
conditions
beliebige[]
Liste der Bedingungen, die die Aktionen auslösen können.
-
id
String optional
Optionale Kennung, mit der auf diese Regel verwiesen werden kann.
-
priorität
Nummer optional
Optionale Priorität dieser Regel. Die Standardeinstellung ist 100.
-
Tags
string[] optional
Mit Tags können Regeln annotiert und Vorgänge für Regelsätze ausgeführt werden.
UrlFilter
Filtert URLs nach verschiedenen Kriterien. Siehe Ereignisfilterung. Bei allen Kriterien wird zwischen Groß- und Kleinschreibung unterschieden.
Attribute
-
cidrBlocks
string[] optional
Chrome 123 oder höherStimmt überein, wenn der Hostteil der URL eine IP-Adresse ist und in einem der CIDR-Blöcke enthalten ist, die im Array angegeben sind.
-
hostContains
String optional
Stimmt überein, wenn der Hostname der URL einen bestimmten String enthält. Um zu testen, ob eine Hostnamenkomponente das Präfix „foo“ hat, verwenden Sie hostEnthält: „.foo“. Dies stimmt mit „www.foobar.com“ und „foo.com“ überein, da am Anfang des Hostnamens ein impliziter Punkt hinzugefügt wird. In ähnlicher Weise kann „hostEnthält“ für den Abgleich mit dem Komponentensuffix („foo.“) und für einen genauen Abgleich mit Komponenten („.foo.“) verwendet werden. Suffix- und genaue Übereinstimmungen für die letzten Komponenten müssen separat mithilfe von hostSuffix vorgenommen werden, da kein impliziter Punkt am Ende des Hostnamens hinzugefügt wird.
-
hostEquals
String optional
Stimmt überein, wenn der Hostname der URL einem angegebenen String entspricht.
-
hostPrefix
String optional
Stimmt überein, wenn der Hostname der URL mit einem angegebenen String beginnt.
-
hostSuffix
String optional
Stimmt überein, wenn der Hostname der URL mit einem angegebenen String endet.
-
originAndPathMatches
String optional
Stimmt überein, wenn die URL ohne Abfragesegment und Fragment-ID mit einem angegebenen regulären Ausdruck übereinstimmt. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen. Die regulären Ausdrücke verwenden die RE2-Syntax.
-
pathContains
String optional
Stimmt überein, wenn das Pfadsegment der URL einen bestimmten String enthält.
-
pathEquals
String optional
Stimmt überein, wenn das Pfadsegment der URL einem angegebenen String entspricht.
-
pathPrefix
String optional
Stimmt überein, wenn das Pfadsegment der URL mit einem angegebenen String beginnt.
-
pathSuffix
String optional
Stimmt überein, wenn das Pfadsegment der URL mit einem angegebenen String endet.
-
ports
(Zahl | Zahl[])[] optional
Stimmt überein, wenn der Port der URL in einer der angegebenen Portlisten enthalten ist.
[80, 443, [1000, 1200]]
stimmt beispielsweise mit allen Anfragen an Port 80, 443 und im Bereich 1000–1200 überein. -
queryContains
String optional
Stimmt überein, wenn das Suchanfragensegment der URL einen bestimmten String enthält.
-
queryEquals
String optional
Stimmt überein, wenn das Suchanfragensegment der URL mit einem angegebenen String übereinstimmt.
-
queryPrefix
String optional
Stimmt überein, wenn das Suchanfragensegment der URL mit einem angegebenen String beginnt.
-
querySuffix
String optional
Stimmt überein, wenn das Suchanfragensegment der URL mit einem angegebenen String endet.
-
schemes
string[] optional
Stimmt überein, wenn das Schema der URL einem der im Array angegebenen Schemas entspricht.
-
urlContains
String optional
Stimmt überein, wenn die URL (ohne Fragment-ID) einen angegebenen String enthält. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.
-
urlEquals
String optional
Stimmt überein, wenn die URL (ohne Fragment-ID) einem angegebenen String entspricht. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.
-
urlMatches
String optional
Stimmt überein, wenn die URL (ohne Fragment-ID) mit einem angegebenen regulären Ausdruck übereinstimmt. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen. Die regulären Ausdrücke verwenden die RE2-Syntax.
-
urlPrefix
String optional
Stimmt überein, wenn die URL (ohne Fragment-ID) mit einem angegebenen String beginnt. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.
-
urlSuffix
String optional
Stimmt überein, wenn die URL (ohne Fragment-ID) mit einem angegebenen String endet. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.