chrome.events

Beschreibung

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.