browser.events

Beschreibung

Konzepte und Nutzung

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 browser.alarms.onAlarm-Ereignisses, um benachrichtigt zu werden, wenn ein Alarm abgelaufen ist:

browser.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 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 schon.

Deklarative Event-Handler

Mit den deklarativen Ereignishandlern können Sie Regeln 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 Event-Handler werden beispielsweise in 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:

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, 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.

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 prüfen, ob für eine registrierte Regel mindestens eine Bedingung erfüllt ist, 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 die Funktion addRules() des Ereignisobjekts auf, um Regeln hinzuzufügen. Als ersten Parameter wird ein Array von Regelinstanzen und als zweiten Parameter eine Callback-Funktion übergeben, 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 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 nicht bereits von einer anderen Regel verwendet wird, oder eine leere ID.

Regeln entfernen

Rufen Sie die Funktion removeRules() auf, um Regeln zu entfernen. Als ersten Parameter wird ein optionales Array von Regel-IDs und als zweiten Parameter eine Callback-Funktion akzeptiert.

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

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 diese Kennung 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 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 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 in Chrome interne Datenstrukturen aktualisiert werden. Diese Aktualisierung ist ein kostspieliger Vorgang.

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

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

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

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

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

Wenn es viele Regeln mit denselben Aktionen gibt, sollten Sie sie in einer Regel zusammenfassen. 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 wird reduziert.

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

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, 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.

Mit gefilterten Ereignissen soll ein Übergang von manuellem Filtercode ermöglicht werden.

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

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {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 dieses 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.