browser.events

Beschrijving

De naamruimte chrome.events bevat veelvoorkomende typen die worden gebruikt door API's die gebeurtenissen verzenden om je op de hoogte te stellen als er iets interessants gebeurt.

Concepten en gebruik

Een Event is een object waarmee je een melding krijgt als er iets interessants gebeurt. Hier is een voorbeeld van het gebruik van de gebeurtenis browser.alarms.onAlarm om een melding te krijgen wanneer een wekker is afgelopen:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Zoals het voorbeeld laat zien, registreert u zich voor meldingen met addListener(). Het argument voor addListener() is altijd een functie die je definieert om de gebeurtenis te verwerken, maar de parameters voor de functie zijn afhankelijk van de gebeurtenis die je verwerkt. Als je de documentatie voor alarms.onAlarm checkt, zie je dat de functie één parameter heeft: een alarms.Alarm-object met informatie over het verstreken alarm.

Voorbeelden van API's die gebeurtenissen gebruiken: alarms, i18n, identity, runtime. De meeste chrome-API's wel.

Declaratieve gebeurtenishandlers

De declaratieve gebeurtenishandlers bieden een manier om regels te definiëren die bestaan uit declaratieve voorwaarden en acties. Voorwaarden worden geëvalueerd in de browser in plaats van de JavaScript-engine, waardoor de vertragingen voor de retourzending worden verminderd en een zeer hoge efficiëntie mogelijk is.

Declaratieve gebeurtenishandlers worden bijvoorbeeld gebruikt in de Declarative Content API. Op deze pagina worden de onderliggende concepten van alle declaratieve gebeurtenis-handlers beschreven.

Regels

De eenvoudigste regel bestaat uit een of meer voorwaarden en een of meer acties:

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

Als aan een van de voorwaarden wordt voldaan, worden alle acties uitgevoerd.

Naast voorwaarden en acties kun je elke regel een ID geven, zodat je de registratie van eerder geregistreerde regels makkelijker ongedaan kunt maken, en een prioriteit om de prioriteit van regels te definiëren. Prioriteiten worden alleen overwogen als regels met elkaar conflicteren of in een specifieke volgorde moeten worden uitgevoerd. Acties worden uitgevoerd in aflopende volgorde van de prioriteit van de regels.

const rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Gebeurtenisobjecten

Gebeurtenisobjecten kunnen regels ondersteunen. Deze gebeurtenisobjecten roepen geen callbackfunctie aan als er gebeurtenissen plaatsvinden, maar testen of een geregistreerde regel ten minste één voldane voorwaarde heeft en voeren de acties uit die aan deze regel zijn gekoppeld. Gebeurtenisobjecten die de declaratieve API ondersteunen, hebben 3 relevante methoden: events.Event.addRules(), events.Event.removeRules() en events.Event.getRules().

Regels toevoegen

Als u regels wilt toevoegen, roept u de functie addRules() van het gebeurtenisobject aan. De functie gebruikt een array van regelinstanties als eerste parameter en een callbackfunctie die wordt aangeroepen na voltooiing.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Als de regels zijn ingevoegd, bevat de parameter details een matrix met ingevoegde regels die in dezelfde volgorde verschijnen als in de doorgegeven rule_list, waarbij de optionele parameters id en priority zijn ingevuld met de gegenereerde waarden. Als een regel ongeldig is, bijvoorbeeld omdat deze een ongeldige voorwaarde of actie bevat, worden er geen regels toegevoegd en wordt de variabele runtime.lastError ingesteld als de callbackfunctie wordt aangeroepen. Elke regel in rule_list moet een unieke ID bevatten die nog niet wordt gebruikt door een andere regel of een lege ID.

Regels verwijderen

Roep de functie removeRules() aan om regels te verwijderen. De functie accepteert een optionele matrix van regel-ID's als eerste parameter en een callbackfunctie als tweede parameter.

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

Als rule_ids een array van ID's is, worden alle regels met ID's die in de array staan, verwijderd. Als rule_ids een ID vermeldt die onbekend is, wordt deze ID genegeerd. Als rule_ids undefined is, worden alle geregistreerde regels van deze extensie verwijderd. De functie callback() wordt aangeroepen als de regels zijn verwijderd.

Regels ophalen

Roep de functie getRules() aan om een lijst met geregistreerde regels op te halen. De methode accepteert een optionele matrix van regel-ID's met dezelfde semantiek als removeRules() en een callbackfunctie.

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

De parameter details die is doorgegeven aan de functie callback() verwijst naar een matrix van regels, waaronder ingevulde optionele parameters.

Prestaties

Houd rekening met de volgende richtlijnen om maximale prestaties te behalen.

Regels bulksgewijs registreren en de registratie ongedaan maken. Na elke registratie of ongedaan gemaakte registratie moet Chrome de interne gegevensstructuren updaten. Deze update is een dure bewerking.

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

Geef de voorkeur aan substringovereenkomsten boven reguliere expressies in een events.UrlFilter. Overeenkomsten op basis van subtekenreeksen zijn extreem snel.

In plaats van
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Voorkeuren
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

Als er veel regels zijn met dezelfde acties, voegt u de regels samen tot één regel. Regels activeren hun acties zodra aan één voorwaarde is voldaan. Zo gaat de overeenkomst sneller en wordt het geheugengebruik voor dubbele actiesets verminderd.

In plaats van
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]);
Voorkeuren
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]);

Gefilterde gebeurtenissen

Gefilterde gebeurtenissen zijn een mechanisme waarmee listeners een subset van gebeurtenissen kunnen specificeren waarin ze geïnteresseerd zijn. Een listener die een filter gebruikt, wordt niet aangeroepen voor gebeurtenissen die niet door het filter komen. Hierdoor wordt de luistercode declaratiever en efficiënter. Een servicemedewerker hoeft niet te worden geactiveerd om gebeurtenissen te verwerken die niet relevant zijn.

Gefilterde gebeurtenissen zijn bedoeld om een overgang van handmatige filtercode mogelijk te maken.

In plaats van
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Voorkeuren
browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Gebeurtenissen ondersteunen specifieke filters die relevant zijn voor die gebeurtenis. De lijst met filters die een gebeurtenis ondersteunt, staat in de documentatie voor die gebeurtenis in het gedeelte Filters.

Als u URL's vergelijkt (zoals in het voorbeeld hierboven), ondersteunen gebeurtenisfilters dezelfde mogelijkheden voor URL-overeenkomsten als die kunnen worden uitgedrukt met een events.UrlFilter, behalve voor schema- en poortovereenkomsten.

Typen

Event

Een object waarmee listeners voor een Chrome-gebeurtenis kunnen worden toegevoegd en verwijderd.

Eigenschappen

  • addListener

    ongeldig

    Registreert een callback van een gebeurtenislistener voor een gebeurtenis.

    De functie addListener ziet er zo uit: 

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

    • callback

      H

      Wordt aangeroepen als er een gebeurtenis plaatsvindt. De parameters van deze functie zijn afhankelijk van het type gebeurtenis.

  • addRules

    ongeldig

    Registreert regels om gebeurtenissen te verwerken.

    De functie addRules ziet er zo uit: 

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

    • regels

      Regel<anyany>[]

      Regels die moeten worden geregistreerd. Deze vervangen geen eerder geregistreerde regels.

    • callback

      functie optioneel

      De parameter callback ziet er zo uit: 

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

      • regels

        Regel<anyany>[]

        Regels die zijn geregistreerd, de optionele parameters zijn ingevuld met waarden.

  • getRules

    ongeldig

    Retourneert de momenteel geregistreerde regels.

    De functie getRules ziet er zo uit: 

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

    • ruleIdentifiers

      string[] optioneel

      Als er een matrix wordt doorgegeven, worden alleen regels met ID's in deze matrix geretourneerd.

    • callback

      functie

      De parameter callback ziet er zo uit: 

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

      • regels

        Regel<anyany>[]

        Regels die zijn geregistreerd, de optionele parameters zijn ingevuld met waarden.

  • hasListener

    ongeldig

    De functie hasListener ziet er zo uit: 

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

    • callback

      H

      Listener waarvan de registratiestatus moet worden getest.

    • returns

      booleaans

      Waar als callback is geregistreerd voor de gebeurtenis.

  • hasListeners

    ongeldig

    De functie hasListeners ziet er zo uit: 

    () => {...}

    • returns

      booleaans

      Waar als er event-listeners zijn geregistreerd voor de gebeurtenis.

  • removeListener

    ongeldig

    Hiermee wordt de registratie van een callback van een gebeurtenislistener ongedaan gemaakt voor een gebeurtenis.

    De functie removeListener ziet er zo uit: 

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

    • callback

      H

      De listener waarvan de registratie ongedaan moet worden gemaakt.

  • removeRules

    ongeldig

    Maakt de registratie van momenteel geregistreerde regels ongedaan.

    De functie removeRules ziet er zo uit: 

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

    • ruleIdentifiers

      string[] optioneel

      Als er een array wordt doorgegeven, wordt de registratie van alleen regels met ID's in deze array ongedaan gemaakt.

    • callback

      functie optioneel

      De parameter callback ziet er zo uit: 

      () => void

Rule

Beschrijving van een declaratieve regel voor de verwerking van gebeurtenissen.

Eigenschappen

  • acties

    any[]

    Lijst met acties die worden geactiveerd als aan een van de voorwaarden wordt voldaan.

  • voorwaarden

    any[]

    Lijst met voorwaarden die de acties kunnen triggeren.

  • id

    tekenreeks optioneel

    Optionele ID waarmee naar deze regel kan worden verwezen.

  • prioriteit

    number optioneel

    Optionele prioriteit van deze regel. De standaardinstelling is 100.

  • tags

    string[] optioneel

    Tags kunnen worden gebruikt om regels te annoteren en bewerkingen uit te voeren op sets regels.

UrlFilter

Filtert URL's op verschillende criteria. Ga naar Gebeurtenissen filteren. Alle criteria zijn hoofdlettergevoelig.

Eigenschappen

  • cidrBlocks

    string[] optioneel

    Chrome 123 of hoger browser.* sinds Chrome 148

    Komt overeen als het hostgedeelte van de URL een IP-adres is en is opgenomen in een van de CIDR-blokken die in de matrix zijn opgegeven.

  • hostContains

    tekenreeks optioneel

    Komt overeen als de hostnaam van de URL een opgegeven tekenreeks bevat. Gebruik hostContains: '.foo' om te testen of een hostnaamcomponent het voorvoegsel 'foo' heeft. Dit komt overeen met www.foobar.com en foo.com, omdat er een impliciete punt wordt toegevoegd aan het begin van de hostnaam. Op dezelfde manier kan hostContains worden gebruikt om te matchen met het achtervoegsel van de component ('foo.') en om exact te matchen met componenten ('.foo.'). Achtervoegsel- en exacte overeenkomsten voor de laatste componenten moeten afzonderlijk worden uitgevoerd met hostSuffix, omdat er geen impliciete punt wordt toegevoegd aan het einde van de hostnaam.

  • hostEquals

    tekenreeks optioneel

    Komt overeen als de hostnaam van de URL gelijk is aan een opgegeven tekenreeks.

  • hostPrefix

    tekenreeks optioneel

    Komt overeen als de hostnaam van de URL begint met een opgegeven tekenreeks.

  • hostSuffix

    tekenreeks optioneel

    Komt overeen als de hostnaam van de URL eindigt op een opgegeven tekenreeks.

  • originAndPathMatches

    tekenreeks optioneel

    Komt overeen als de URL zonder querysegment en fragment-ID overeenkomt met een opgegeven reguliere expressie. Poortnummers worden uit de URL verwijderd als ze overeenkomen met het standaardpoortnummer. De reguliere expressies gebruiken de RE2-syntaxis.

  • pathContains

    tekenreeks optioneel

    Komt overeen als het padsegment van de URL een opgegeven tekenreeks bevat.

  • pathEquals

    tekenreeks optioneel

    Komt overeen als het padsegment van de URL gelijk is aan een opgegeven tekenreeks.

  • pathPrefix

    tekenreeks optioneel

    Komt overeen als het padsegment van de URL begint met een opgegeven tekenreeks.

  • pathSuffix

    tekenreeks optioneel

    Komt overeen als het padsegment van de URL eindigt met een opgegeven tekenreeks.

  • ports

    (number | number[])[] optioneel

    Komt overeen als de poort van de URL is opgenomen in een van de opgegeven poortlijsten. [80, 443, [1000, 1200]] komt bijvoorbeeld overeen met alle verzoeken op poort 80, 443 en in het bereik 1000-1200.

  • queryContains

    tekenreeks optioneel

    Komt overeen als het querysegment van de URL een opgegeven tekenreeks bevat.

  • queryEquals

    tekenreeks optioneel

    Komt overeen als het querysegment van de URL gelijk is aan een opgegeven tekenreeks.

  • queryPrefix

    tekenreeks optioneel

    Komt overeen als het querysegment van de URL begint met een opgegeven tekenreeks.

  • querySuffix

    tekenreeks optioneel

    Komt overeen als het querysegment van de URL eindigt met een opgegeven tekenreeks.

  • schema's

    string[] optioneel

    Komt overeen als het schema van de URL gelijk is aan een van de schema's die in de matrix zijn opgegeven.

  • urlContains

    tekenreeks optioneel

    Komt overeen als de URL (zonder fragment-ID) een opgegeven tekenreeks bevat. Poortnummers worden uit de URL verwijderd als ze overeenkomen met het standaardpoortnummer.

  • urlEquals

    tekenreeks optioneel

    Komt overeen als de URL (zonder fragment-ID) gelijk is aan een opgegeven tekenreeks. Poortnummers worden uit de URL verwijderd als ze overeenkomen met het standaardpoortnummer.

  • urlMatches

    tekenreeks optioneel

    Komt overeen als de URL (zonder fragment-ID) overeenkomt met een opgegeven reguliere expressie. Poortnummers worden uit de URL verwijderd als ze overeenkomen met het standaardpoortnummer. De reguliere expressies gebruiken de RE2-syntaxis.

  • urlPrefix

    tekenreeks optioneel

    Komt overeen als de URL (zonder fragment-ID) begint met een opgegeven tekenreeks. Poortnummers worden uit de URL verwijderd als ze overeenkomen met het standaardpoortnummer.

  • urlSuffix

    tekenreeks optioneel

    Komt overeen als de URL (zonder fragment-ID) eindigt op een opgegeven tekenreeks. Poortnummers worden uit de URL verwijderd als ze overeenkomen met het standaardpoortnummer.