chrome.events

Beschreibung

Konzepte und Verwendung

Ein Event ist ein Objekt, das Sie benachrichtigen kann, 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((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 im Declarative 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:

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

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

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (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 eine 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 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. Ein optionales Array von Regelkennungen wird akzeptiert. 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 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

Rufen Sie die Funktion getRules() auf, um eine Liste registrierter Regeln abzurufen. Sie akzeptiert ein Optionales Array von Regelkennungen mit derselben Semantik wie removeRules() und einer 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, 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.

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 Sie in events.UrlFilter den Abgleich von Teilstrings gegenüber regulären Ausdrücken. Der auf Teilstrings basierende Abgleich 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 diese 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.

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