chrome.events

Aktualisierungsdatum: 2026-09-25 robots: noindex

Beschreibung

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

chrome.alarms.onAlarm.addListener(function(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 definieren, um das Ereignis zu verarbeiten. 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.

Deklarative Event-Handler

Die deklarativen Ereignishandler bieten eine 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 reduziert und eine sehr hohe Effizienz ermöglicht.

Deklarative Ereignishandler werden beispielsweise in der Declarative Web Request API und der Declarative Content API verwendet. Auf dieser Seite werden die zugrunde liegenden Konzepte aller deklarativen Ereignishandler beschrieben.

Regeln

Die einfachste Regel besteht aus einer oder mehreren Bedingungen und einer oder mehreren Aktionen:

var 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, die das Aufheben der Registrierung zuvor registrierter Regeln vereinfacht, sowie eine Priorität, um die Vorrangstellung zwischen Regeln zu definieren. 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.

var rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Ereignisobjekte

Für Ereignisobjekte sind möglicherweise Regeln verfügbar. Bei diesen Ereignisobjekten wird keine Callback-Funktion aufgerufen, wenn Ereignisse eintreten. Stattdessen wird geprüft, ob für eine registrierte 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

Rufen Sie die Funktion addRules() des Ereignisobjekts auf, um Regeln hinzuzufügen. Als ersten Parameter wird ein Array mit Regelinstanzen und als zweiten Parameter eine Callback-Funktion übergeben, die nach Abschluss aufgerufen wird.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

Wenn die Regeln erfolgreich eingefügt wurden, enthält der Parameter details ein Array mit den eingefügten Regeln in derselben Reihenfolge wie im übergebenen rule_list. Die optionalen Parameter id und priority wurden mit den generierten Werten gefüllt. Wenn eine Regel ungültig ist, z.B. weil sie eine ungültige Bedingung oder Aktion enthält, werden 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 ID enthalten, die derzeit nicht von einer anderen Regel verwendet wird, oder eine leere ID.

Regeln entfernen

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

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

Wenn rule_ids ein Array von Kennungen ist, werden alle Regeln mit Kennungen, die im Array aufgeführt sind, entfernt. Wenn in rule_ids eine unbekannte Kennung aufgeführt ist, wird sie ignoriert. Wenn rule_ids gleich undefined ist, 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 aktuell registrierten Regeln abzurufen. Sie akzeptiert ein optionales Array von Regelkennungen mit derselben Semantik wie removeRules und eine Callback-Funktion.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});

Der Parameter details, der an die Funktion callback() übergeben wird, verweist auf ein Array von Regeln, einschließlich ausgefüllter optionaler Parameter.

Leistung

Damit Sie die maximale Leistung erzielen, sollten Sie die folgenden Richtlinien beachten.

Regeln im Bulk registrieren und ihre Registrierung aufheben: Nach jeder Registrierung oder Deregistrierung müssen interne Datenstrukturen in Chrome aktualisiert werden. Diese Aktualisierung ist ein kostspieliger Vorgang.

Anstelle von:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

Bevorzugt:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Teilstring-Abgleich gegenüber regulären Ausdrücken in einem events.UrlFilter bevorzugen Der Abgleich auf Grundlage von Teilstrings ist extrem schnell.

Anstelle von:

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

Bevorzugt:

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

Wenn viele Regeln dieselben Aktionen haben, sollten Sie sie in einer Regel zusammenführen. Regeln lösen ihre Aktionen aus, sobald eine einzelne Bedingung erfüllt ist. Dadurch wird der Abgleich beschleunigt und der Speicherverbrauch für doppelte Aktionsgruppen reduziert.

Anstelle von:

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

Bevorzugt:

  var 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 von Ereignissen angeben können, die für sie von Interesse sind. Ein Listener, der einen Filter verwendet, wird nicht für Ereignisse aufgerufen, die den Filter nicht bestehen. Dadurch wird der Listening-Code deklarativer und effizienter. Ein Service Worker muss nicht aktiviert werden, um Ereignisse zu verarbeiten, die ihn nicht betreffen.

Gefilterte Ereignisse sollen die Umstellung von manuellem Filtercode wie diesem ermöglichen:

chrome.webNavigation.onCommitted.addListener(function(e) {
  if (hasHostSuffix(e.url, 'google.com') ||
      hasHostSuffix(e.url, 'google.com.au')) {
    // ...
  }
});

in Folgendes ändern:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

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