Chrome unterstützt jetzt den standardisierten Namespace browser.* (verfügbar ab Chrome 148). Wir aktualisieren die Dokumentation schrittweise. Weitere Informationen finden Sie in unserem Leitfaden zur Umstellung.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

browser.events

Beschreibung

Der Namespace chrome.events enthält gängige Typen, die von APIs verwendet werden, die Ereignisse senden, um Sie zu benachrichtigen, wenn etwas Interessantes passiert.

Konzepte und Verwendung

Ein Event ist ein Objekt, mit dem Sie benachrichtigt werden können, wenn etwas Interessantes passiert. Hier ist ein Beispiel für die Verwendung des Ereignisses browser.alarms.onAlarm, um benachrichtigt zu werden, wenn ein Alarm abgelaufen ist:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Wie das Beispiel zeigt, registrieren Sie sich mit addListener() für Benachrichtigungen. Das Argument für addListener() ist immer eine Funktion, die Sie zur Verarbeitung des Ereignisses definieren. Die Parameter für die 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 mit Details zum abgelaufenen Alarm.

Beispiel-APIs, die Ereignisse verwenden: alarms, i18n, identity, runtime. Die meisten Chrome APIs tun dies.

Deklarative Event-Handler

Mit den deklarativen Event-Handlern können Sie Regeln definieren, die aus deklarativen Bedingungen und Aktionen bestehen. Bedingungen werden im Browser und nicht in der JavaScript-Engine ausgewertet. Das reduziert die Roundtrip-Latenz und ermöglicht eine sehr hohe Effizienz.

Deklarative Event-Handler werden beispielsweise in der Declarative Content API verwendet. Auf dieser Seite werden die zugrunde liegenden Konzepte aller deklarativen Event-Handler beschrieben.

Regeln

Die einfachste 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 die Abmeldung zuvor registrierter Regeln zu vereinfachen, und eine Priorität, um die Rangfolge der Regeln festzulegen. Prioritäten werden nur berücksichtigt, wenn Regeln miteinander in Konflikt stehen oder in einer bestimmten Reihenfolge ausgeführt werden müssen. Aktionen werden in absteigender Reihenfolge 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 können Regeln unterstützen. Diese Ereignisobjekte rufen keine Callback-Funktion auf, wenn Ereignisse auftreten. Stattdessen wird geprüft, ob bei einer registrierten Regel mindestens eine Bedingung erfüllt ist, und die mit dieser Regel verknüpften Aktionen werden ausgeführt. Ereignisobjekte, die die deklarative API unterstützen, haben drei relevante Methoden: events.Event.addRules(), events.Event.removeRules() und events.Event.getRules().

Regeln hinzufügen

Wenn Sie Regeln hinzufügen möchten, rufen Sie die Funktion addRules() des Ereignisobjekts auf. Sie verwendet ein Array von Regelinstanzen als ersten Parameter 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 der eingefügten Regeln in derselben Reihenfolge wie im übergebenen rule_list, 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 enthält, wird keine der Regeln hinzugefügt und die Variable runtime.lastError wird festgelegt, wenn die Callback-Funktion aufgerufen wird. Jede Regel in rule_list muss eine eindeutige Kennung enthalten, die nicht bereits von einer anderen Regel verwendet wird, oder eine leere Kennung.

Regeln entfernen

Wenn Sie Regeln entfernen möchten, rufen Sie die Funktion removeRules() auf. Sie akzeptiert ein optionales Array von Regelkennungen als ersten Parameter und eine Callback-Funktion als zweiten Parameter.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

Wenn rule_ids ein Array von Kennungen ist, werden alle Regeln entfernt, deren Kennungen im Array aufgeführt sind. Wenn in rule_ids eine unbekannte Kennung aufgeführt ist, wird diese Kennung ignoriert. Wenn rule_ids den Wert undefined hat, werden alle registrierten Regeln dieser Erweiterung entfernt. Die Funktion callback() wird aufgerufen, wenn 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 bezieht sich auf ein Array von Regeln, einschließlich ausgefüllter optionaler Parameter.

Leistung

Beachten Sie die folgenden Richtlinien, um die maximale Leistung zu erzielen.

Regeln im Bulk registrieren und Registrierung aufheben. Nach jeder Registrierung oder Abmeldung muss Chrome interne Datenstrukturen aktualisieren. Diese Aktualisierung ist ein aufwendiger Vorgang.

anstelle von

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

Bevorzugt

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

Verwenden Sie in einem events.UrlFilter lieber Teilstring-Abgleiche als reguläre Ausdrücke. Der Abgleich auf Basis von Teilstrings ist extrem schnell.

anstelle von

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

Bevorzugt

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

Wenn es viele Regeln mit denselben Aktionen gibt, fassen Sie die Regeln zu einer zusammen. Regeln lösen ihre Aktionen aus, sobald eine einzelne Bedingung erfüllt ist. Dadurch wird der Abgleich beschleunigt und der Speicherverbrauch für doppelte Aktionssätze reduziert.

anstelle von

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]);

Bevorzugt

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]);

Gefilterte Ereignisse

Gefilterte Ereignisse sind ein Mechanismus, mit dem Listener eine Teilmenge von Ereignissen angeben können, an denen sie interessiert sind. Ein Listener, der einen Filter verwendet, wird nicht für Ereignisse aufgerufen, die den Filter nicht passieren. Dadurch wird der Listener-Code deklarativer und effizienter. Ein Service Worker muss nicht aktiviert werden, um Ereignisse zu verarbeiten, die für ihn nicht relevant sind.

Gefilterte Ereignisse sollen den Übergang von manuellem Filtercode ermöglichen.

anstelle von

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

Bevorzugt

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Ereignisse unterstützen bestimmte Filter, die für das jeweilige Ereignis relevant sind. Die Liste der Filter, die ein Ereignis unterstützt, finden Sie in der Dokumentation für dieses Ereignis im Abschnitt „Filter“.

Beim Abgleich von URLs (wie im Beispiel oben) unterstützen Ereignisfilter dieselben URL-Abgleichsfunktionen, die mit einem events.UrlFilter ausgedrückt werden können, mit Ausnahme des Abgleichs von Schema und Port.

Typen

Event

Ein Objekt, mit dem Listener für ein Chrome-Ereignis hinzugefügt und entfernt werden können.

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 auftritt. 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
  
  Rule<anyany>[]
  
  Zu registrierende Regeln. Diese ersetzen keine zuvor registrierten Regeln.
- callback
  
  function optional
  
  Der Parameter callback sieht so aus:
```
(rules: Rule<anyany>[]) => void
```
  - Regeln
    
    Rule<anyany>[]
    
    Regeln, die registriert wurden. Die optionalen Parameter sind 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
    
    Rule<anyany>[]
    
    Regeln, die registriert wurden. Die optionalen Parameter sind 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
  
  „True“, wenn callback für das Ereignis registriert ist.
hasListeners

void

Die Funktion hasListeners sieht so aus:
```
() => {...}
```
- Gibt zurück
  boolean
  
  „True“, wenn Event-Listener für das Ereignis registriert sind.
removeListener

void

Meldet einen Callback für einen Event-Listener von einem Ereignis ab.

Die Funktion removeListener sieht so aus:
```
(callback: H) => {...}
```
- callback
  
  H
  
  Listener, dessen Registrierung aufgehoben werden soll.
removeRules

void

Hebt die Registrierung der derzeit registrierten 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, abgemeldet.
- callback
  
  function optional
  
  Der Parameter callback sieht so aus:
```
() => void
```

Rule

Beschreibung einer deklarativen Regel für die Verarbeitung von Ereignissen.

Attribute

Aktionen

any[]

Liste der Aktionen, die ausgelöst werden, wenn eine der Bedingungen erfüllt ist.
Bedingungen

any[]

Liste der Bedingungen, die die Aktionen auslösen können.
id

String optional

Optionale Kennung, mit der auf diese Regel verwiesen werden kann.
priority

number optional

Optionale Priorität dieser Regel. Die Standardeinstellung ist 100.
Tags

string[] optional

Mit Tags können Sie Regeln annotieren und Vorgänge für Regelsätze ausführen.

UrlFilter

Filtert URLs nach verschiedenen Kriterien. Weitere Informationen finden Sie unter Ereignisfilterung. Bei allen Kriterien wird zwischen Groß- und Kleinschreibung unterschieden.

Attribute

cidrBlocks

string[] optional

Chrome 123 und höher browser.* seit Chrome 148

Stimmt überein, wenn der Hostteil der URL eine IP-Adresse ist und in einem der im Array angegebenen CIDR-Blöcke enthalten ist.
hostContains

String optional

Stimmt überein, wenn der Hostname der URL einen bestimmten String enthält. Wenn Sie testen möchten, ob eine Hostnamenkomponente das Präfix „foo“ hat, verwenden Sie „hostContains: ‚.foo‘“. Dies entspricht „www.foobar.com“ und „foo.com“, da am Anfang des Hostnamens ein impliziter Punkt hinzugefügt wird. Ebenso kann „hostContains“ verwendet werden, um einen Abgleich mit dem Komponentensuffix („foo.“) und einen genauen Abgleich mit Komponenten („.foo.“) durchzuführen. Suffix- und genaue Übereinstimmungen für die letzten Komponenten müssen separat mit „hostSuffix“ durchgeführt werden, da am Ende des Hostnamens kein impliziter Punkt hinzugefügt wird.
hostEquals

String optional

Stimmt überein, wenn der Hostname der URL mit einem angegebenen String übereinstimmt.
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 Fragmentbezeichner 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

Übereinstimmung, wenn das Pfadsegment der URL mit einem angegebenen String übereinstimmt.
pathPrefix

String optional

Übereinstimmung, wenn das Pfadsegment der URL mit einem bestimmten String beginnt.
pathSuffix

String optional

Stimmt überein, wenn das Pfadsegment der URL mit einem bestimmten String endet.
ports

(number | number[])[] optional

Stimmt überein, wenn der Port der URL in einer der angegebenen Portlisten enthalten ist. Beispiel: [80, 443, [1000, 1200]] entspricht allen Anfragen an Port 80, 443 und im Bereich 1000–1200.
queryContains

String optional

Stimmt überein, wenn das Abfragesegment der URL einen bestimmten String enthält.
queryEquals

String optional

Stimmt überein, wenn das Abfragesegment der URL mit einem angegebenen String übereinstimmt.
queryPrefix

String optional

Stimmt überein, wenn das Abfragesegment der URL mit einem bestimmten String beginnt.
querySuffix

String optional

Übereinstimmung, wenn das Abfragesegment der URL mit einem bestimmten String endet.
schemes

string[] optional

Stimmt überein, wenn das Schema der URL mit einem der im Array angegebenen Schemas übereinstimmt.
urlContains

String optional

Stimmt überein, wenn die URL (ohne Fragment-ID) einen bestimmten String enthält. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.
urlEquals

String optional

Trifft zu, wenn die URL (ohne Fragmentbezeichner) mit einem angegebenen String übereinstimmt. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.
urlMatches

String optional

Stimmt überein, wenn die URL (ohne Fragmentbezeichner) 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 Fragmentbezeichner) 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.

browser.events Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Beschreibung

Konzepte und Verwendung

Deklarative Event-Handler

Regeln

Ereignisobjekte

Regeln hinzufügen

Regeln entfernen

Regeln abrufen

Leistung

Gefilterte Ereignisse

Typen

Event

Attribute

Rule

Attribute

UrlFilter

Attribute

browser.events