chrome.events

Beschreibung

Ein Event ist ein Objekt, über das Sie benachrichtigt werden, wenn etwas Interessantes passiert. Hier ist ein Beispiel für die Verwendung des Ereignisses chrome.alarms.onAlarm, um nach Ablauf eines Alarms benachrichtigt zu werden:

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 die Benachrichtigung. Das Argument für addListener() ist immer eine Funktion, die Sie zur Verarbeitung des Ereignisses definieren, aber die Parameter des hängen davon ab, welches Ereignis verarbeitet wird. Sehen Sie in der Dokumentation zu alarms.onAlarm nach: Sie sehen, dass die Funktion nur einen Parameter hat: ein alarms.Alarm-Objekt mit Details über den verstrichenen Alarm.

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

Deklarative Event-Handler

Mit deklarativen Ereignis-Handlern können Regeln definiert werden, die aus deklarativen Bedingungen bestehen. und Aktionen. Bedingungen werden im Browser und nicht im JavaScript-Modul ausgewertet, Roundtrip-Latenzen und ermöglicht eine sehr hohe Effizienz.

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

Regeln

Die einfachste Regel besteht aus einer oder mehreren Bedingungen und mindestens einer Aktion:

var rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Wenn eine der Bedingungen erfüllt ist, werden alle Aktionen ausgeführt.

Zusätzlich zu den Bedingungen und Aktionen können Sie jeder Regel eine Kennung zuweisen. Das vereinfacht die Aufheben der Registrierung zuvor registrierter Regeln und eine Priorität zum Definieren der Rangfolge zwischen Regeln Prioritäten werden nur berücksichtigt, wenn Regeln miteinander in Konflikt stehen oder in einer bestimmten Reihenfolge. Aktionen werden in absteigender Reihenfolge nach der Priorität der zugehörigen 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

Ereignisobjekte unterstützen möglicherweise Regeln. Diese Ereignisobjekte rufen keine Callback-Funktion auf, wenn Ereignisse auftreten, aber testen Sie, ob eine registrierte Regel mindestens eine erfüllte Bedingung hat, und führen Sie sie aus. Aktionen, die mit dieser Regel verknüpft sind. 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 benötigt eine Reihe von Regelinstanzen, als ersten Parameter und eine Callback-Funktion, 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 eingefügten Regeln. erscheinen in derselben Reihenfolge wie in der übergebenen rule_list, wobei die optionalen Parameter id und priority wurden mit den generierten Werten gefüllt. Wenn eine Regel ungültig ist, z.B. weil sie Ungültige Bedingung oder Aktion ist, wird keine der Regeln hinzugefügt und die Variable runtime.lastError wird beim Aufrufen der Callback-Funktion festgelegt. Jede Regel in rule_list muss eine eindeutige Kennung, die derzeit nicht von einer anderen Regel verwendet wird, oder eine leere Kennung.

Regeln entfernen

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

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

Wenn rule_ids ein Array von Kennungen ist, werden alle Regeln mit aufgeführten Kennungen entfernt. Wenn rule_ids eine unbekannte Kennung auflistet, wird sie ignoriert. Wenn rule_ids ist undefined. Alle registrierten Regeln dieser Erweiterung werden entfernt. Das callback() wird aufgerufen, wenn die Regeln entfernt wurden.

Regeln abrufen

Wenn Sie eine Liste der aktuell registrierten Regeln abrufen möchten, rufen Sie die Funktion getRules() auf. Sie akzeptiert ein Optionales Array von Regelkennungen mit derselben Semantik wie removeRules und einer Callback-Funktion.

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

Der an die Funktion callback() übergebene Parameter details bezieht sich auf ein Array von Regeln, optionale Parameter gefüllt.

Leistung

Beachten Sie die folgenden Richtlinien, um die bestmögliche Leistung zu erzielen.

Mehrere Regeln gleichzeitig registrieren und ihre Registrierung aufheben Nach jeder Registrierung oder Abmeldung muss Chrome interne Datenstrukturen zu aktualisieren. Diese Aktualisierung ist ein teurer 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]);

Bevorzugen Sie in events.UrlFilter den Abgleich von Teilstrings gegenüber regulären Ausdrücken. Der auf Teilstrings basierende Abgleich 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 mehrere Regeln die gleichen Aktionen umfassen, führen Sie die Regeln zu einer zusammen. Regeln lösen ihre Aktionen aus, sobald eine bestimmte Bedingung erfüllt ist. Dadurch wird der und reduziert den Arbeitsspeicherverbrauch für doppelte Aktionssätze.

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 der Ereignisse angeben können, an denen Sie interessiert sind. Ein Listener, der einen Filter verwendet, wird nicht für Ereignisse aufgerufen, die den -Filter, wodurch der Überwachungscode deklarativer und effizienter wird. Ein Service Worker benötigt nicht für Ereignisse geweckt werden, die sie nicht interessieren.

Gefilterte Ereignisse sollen einen Übergang vom manuellen Filtercode wie den folgenden ermöglichen:

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

in diese Datei einfügen:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {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 für ein Ereignis werden in der Dokumentation zu diesem Ereignis unter „Filter“ aufgeführt. .

Beim Abgleich von URLs (wie im Beispiel oben) wird von Ereignisfiltern derselbe URL-Abgleich unterstützt. Funktionen wie mit einem events.UrlFilter auszudrücken, ausgenommen Schema- und Portabgleich.