chrome.events

Beschreibung

Der Namespace chrome.events enthält gängige Typen, die von APIs verwendet werden, die Ereignisse auslösen, um Sie über interessante Ereignisse zu informieren.

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.

anstelle von
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
Bevorzugt
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.

anstelle von
const match = new chrome.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Bevorzugt
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.

anstelle von
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]);
Bevorzugt
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.

anstelle von
chrome.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Bevorzugt
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.

Typen

Event

Ein Objekt, mit dem Listener für ein Chrome-Ereignis hinzugefügt oder entfernt werden können.

Attribute

  • addListener

    voidm

    Registriert einen Event-Listener-Callback für ein Ereignis.

    Die Funktion addListener sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (callback: H) => {...}

    • callback

      H

      Wird aufgerufen, wenn ein Ereignis eintritt. Die Parameter dieser Funktion hängen vom Ereignistyp ab.

  • addRules

    voidm

    Registriert Regeln zur Verarbeitung von Ereignissen.

    Die Funktion addRules sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (rules: Rule<anyany>[], callback?: function) => {...}

    • Regeln

      Regel<beliebig>[]

      Regeln, die registriert werden sollen. Diese ersetzen keine zuvor registrierten Regeln.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

      (rules: Rule<anyany>[]) => void

      • Regeln

        Regel<beliebig>[]

        Regeln, die registriert wurden. Die optionalen Parameter werden mit Werten gefüllt.

  • getRules

    voidm

    Gibt aktuell registrierte Regeln zurück.

    Die Funktion getRules sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

      string[] optional

      Wenn ein Array übergeben wird, werden nur Regeln mit IDs zurückgegeben, die in diesem Array enthalten sind.

    • callback

      Funktion

      Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

      (rules: Rule<anyany>[]) => void

      • Regeln

        Regel<beliebig>[]

        Regeln, die registriert wurden. Die optionalen Parameter werden mit Werten gefüllt.

  • hasListener

    voidm

    Die Funktion hasListener sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (callback: H) => {...}

    • callback

      H

      Listener, dessen Registrierungsstatus getestet werden soll

    • Gibt zurück

      boolean

      Dieser Wert ist „True“, wenn der Callback für das Ereignis registriert ist.

  • hasListeners

    voidm

    Die Funktion hasListeners sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => {...}

    • Gibt zurück

      boolean

      "True", wenn Ereignis-Listener für das Ereignis registriert sind.

  • removeListener

    voidm

    Hebt die Registrierung eines Event-Listener-Callbacks von einem Ereignis auf.

    Die Funktion removeListener sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (callback: H) => {...}

    • callback

      H

      Listener, der abgemeldet werden soll.

  • removeRules

    voidm

    Hebt die Registrierung von derzeit registrierten Regeln auf.

    Die Funktion removeRules sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • ruleIdentifiers

      string[] optional

      Wenn ein Array übergeben wird, werden nur Regeln mit Kennungen entfernt, die in diesem Array enthalten sind.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

      () => void

Rule

Beschreibung einer deklarativen Regel zur Verarbeitung von Ereignissen.

Attribute

  • Aktionen

    Beliebig[]

    Liste der Aktionen, die ausgelöst werden, wenn eine der Bedingungen erfüllt ist.

  • Bedingungen

    Beliebig[]

    Liste der Bedingungen, die die Aktionen auslösen können.

  • id

    String optional

    Optionale Kennung, mit der auf diese Regel verwiesen werden kann.

  • priorität

    Zahl optional

    Optionale Priorität dieser Regel. Die Standardeinstellung ist 100.

  • Tags

    string[] optional

    Mit Tags können Sie Regeln annotieren und Vorgänge für Regelsätze ausführen.

UrlFilter

Filtert URLs nach verschiedenen Kriterien. Siehe Ereignisfilterung. Bei allen Kriterien wird zwischen Groß- und Kleinschreibung unterschieden.

Attribute

  • cidrBlocks

    string[] optional

    Chrome 123 und höher

    Stimmt überein, wenn der Hostteil der URL eine IP-Adresse ist und in einem der im Array angegebenen CIDR-Blöcke enthalten ist.

  • hostContains

    String optional

    Stimmt überein, wenn der Hostname der URL eine angegebene Zeichenfolge enthält. Um zu testen, ob eine Hostnamenkomponente das Präfix "foo" hat, verwenden Sie hostEnthält: ".foo". Dies stimmt mit "www.foobar.com" überein. und "foo.com", da am Anfang des Hostnamens ein impliziter Punkt hinzugefügt wird. Auf ähnliche Weise kann hostEnthälts für den Abgleich mit Komponenten-Suffix ("foo.") und für einen genauen Abgleich mit Komponenten (".foo.") verwendet werden. Suffix- und exakter Abgleich für die letzten Komponenten müssen separat mit hostSuffix durchgeführt werden, da kein impliziter Punkt am Ende des Hostnamens hinzugefügt wird.

  • hostEquals

    String optional

    Stimmt überein, wenn der Hostname der URL einem angegebenen String entspricht.

  • hostPrefix

    String optional

    Stimmt überein, wenn der Hostname der URL mit einem angegebenen String beginnt.

  • hostSuffix

    String optional

    Stimmt überein, wenn der Hostname der URL mit einem angegebenen String endet.

  • originAndPathMatches

    String optional

    Stimmt überein, wenn die URL ohne Abfragesegment und Fragmentkennung mit einem angegebenen regulären Ausdruck übereinstimmt. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen. Für reguläre Ausdrücke wird die RE2-Syntax verwendet.

  • pathContains

    String optional

    Stimmt überein, wenn das Pfadsegment der URL eine angegebene Zeichenfolge enthält.

  • pathEquals

    String optional

    Stimmt überein, wenn das Pfadsegment der URL einem angegebenen String entspricht.

  • pathPrefix

    String optional

    Stimmt überein, wenn das Pfadsegment der URL mit einem angegebenen String beginnt.

  • pathSuffix

    String optional

    Stimmt überein, wenn das Pfadsegment der URL mit einem angegebenen String endet.

  • ports

    (Zahl | Zahl[])[] optional

    Stimmt überein, wenn der Port der URL in einer der angegebenen Portlisten enthalten ist. [80, 443, [1000, 1200]] entspricht beispielsweise allen Anfragen an Port 80, 443 und im Bereich 1000–1200.

  • queryContains

    String optional

    Stimmt überein, wenn das Abfragesegment der URL einen bestimmten String enthält.

  • queryEquals

    String optional

    Stimmt überein, wenn das Suchanfragensegment der URL einem angegebenen String entspricht.

  • queryPrefix

    String optional

    Stimmt überein, wenn das Suchanfragensegment der URL mit einem angegebenen String beginnt.

  • querySuffix

    String optional

    Stimmt überein, wenn das Suchanfragensegment der URL mit einem angegebenen String endet.

  • Schemata

    string[] optional

    Stimmt überein, wenn das Schema der URL einem der im Array angegebenen Schemas entspricht.

  • urlContains

    String optional

    Stimmt überein, wenn die URL (ohne Fragment-ID) eine angegebene Zeichenfolge enthält. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.

  • urlEquals

    String optional

    Stimmt überein, wenn die URL (ohne Fragment-ID) einem angegebenen String entspricht. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.

  • urlMatches

    String optional

    Stimmt überein, wenn die URL (ohne Fragmentkennung) mit einem angegebenen regulären Ausdruck übereinstimmt. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen. Für reguläre Ausdrücke wird die RE2-Syntax verwendet.

  • urlPrefix

    String optional

    Stimmt überein, wenn die URL (ohne Fragment-ID) mit einem angegebenen String beginnt. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.

  • urlSuffix

    String optional

    Stimmt überein, wenn die URL (ohne Fragment-ID) mit einem angegebenen String endet. Portnummern werden aus der URL entfernt, wenn sie mit der Standardportnummer übereinstimmen.