chrome.evenementen

Beschrijving

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

Concepten en gebruik

Een Event is een object waarmee u op de hoogte kunt worden gesteld wanneer er iets interessants gebeurt. Hier is een voorbeeld van het gebruik van de gebeurtenis chrome.alarms.onAlarm om een ​​melding te krijgen wanneer een alarm is verstreken:

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

Zoals het voorbeeld laat zien, registreert u zich voor melding met addListener() . Het argument voor addListener() is altijd een functie die u definieert om de gebeurtenis af te handelen, maar de parameters voor de functie zijn afhankelijk van de gebeurtenis die u afhandelt. Als u de documentatie voor alarms.onAlarm bekijkt, ziet u dat de functie één enkele parameter heeft: een alarms.Alarm -object dat details bevat over het verstreken alarm.

Voorbeeld-API's die gebruikmaken van gebeurtenissen: alarms , i18n , Identity , runtime . De meeste Chrome-API's doen dat.

Declaratieve gebeurtenishandlers

De declaratieve gebeurtenishandlers bieden een middel om regels te definiëren die bestaan ​​uit declaratieve voorwaarden en acties. De omstandigheden worden geëvalueerd in de browser in plaats van in de JavaScript-engine, waardoor de roundtrip-latency wordt verminderd en een zeer hoge efficiëntie mogelijk is.

Declaratieve gebeurtenishandlers worden bijvoorbeeld gebruikt in de Declarative Content API . Deze pagina beschrijft de onderliggende concepten van alle declaratieve gebeurtenishandlers.

Regels

De eenvoudigst mogelijke regel bestaat uit een of meer voorwaarden en een of meer acties:

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

Als aan één van de voorwaarden is voldaan, worden alle acties uitgevoerd.

Naast voorwaarden en acties kunt u elke regel een ID geven, wat het ongedaan maken van eerder geregistreerde regels vereenvoudigt, en een prioriteit om prioriteit tussen regels te definiëren. Er wordt alleen rekening gehouden met prioriteiten als regels met elkaar in strijd zijn of in een specifieke volgorde moeten worden uitgevoerd. Acties worden uitgevoerd in aflopende volgorde van de prioriteit van hun 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 callback-functie aan wanneer er gebeurtenissen plaatsvinden, maar testen of een geregistreerde regel aan ten minste één voorwaarde voldoet en voeren de acties uit die aan deze regel zijn gekoppeld. Gebeurtenisobjecten die de declaratieve API ondersteunen, hebben drie relevante methoden: events.Event.addRules() , events.Event.removeRules() en events.Event.getRules() .

Regels toevoegen

Om regels toe te voegen, roept u de functie addRules() van het gebeurtenisobject op. Het heeft een array van regelinstanties nodig als eerste parameter en een callback-functie die na voltooiing wordt aangeroepen.

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

Als de regels met succes zijn ingevoegd, bevat de parameter details een array van ingevoegde regels die in dezelfde volgorde verschijnen als in de doorgegeven rule_list waar de optionele parameters id en priority zijn gevuld met de gegenereerde waarden. Als een regel ongeldig is, bijvoorbeeld omdat deze een ongeldige voorwaarde of actie bevat, wordt geen van de regels toegevoegd en wordt de variabele runtime.lastError ingesteld wanneer de callback-functie wordt aangeroepen. Elke regel in rule_list moet een unieke ID bevatten die nog niet door een andere regel wordt gebruikt, of een lege ID.

Regels verwijderen

Om regels te verwijderen, roept u de functie removeRules() op. Het accepteert een optionele reeks regel-ID's als eerste parameter en een callback-functie als tweede parameter.

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

Als rule_ids een array van identifiers is, worden alle regels met identifiers in de array verwijderd. Als rule_ids een identificatie vermeldt die onbekend is, wordt deze identificatie stilzwijgend genegeerd. Als rule_ids undefined is, worden alle geregistreerde regels van deze extensie verwijderd. De callback() functie wordt aangeroepen toen de regels werden verwijderd.

Regels ophalen

Om een ​​lijst met geregistreerde regels op te halen, roept u de functie getRules() aan. Het accepteert een optionele reeks regel-ID's met dezelfde semantiek als removeRules() en een callback-functie.

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

De parameter details die wordt doorgegeven aan de functie callback() verwijst naar een reeks regels inclusief gevulde optionele parameters.

Prestatie

Om maximale prestaties te bereiken, moet u de volgende richtlijnen in gedachten houden.

Regels bulksgewijs registreren en afmelden. Na elke registratie of uitschrijving moet Chrome de interne gegevensstructuren updaten. Deze update is een dure operatie.

In plaats van
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
De voorkeur geven aan
const rule1 = {...};
const rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Geef de voorkeur aan het matchen van subtekenreeksen boven reguliere expressies in een events.UrlFilter . Matchen op basis van substrings is extreem snel.

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

Als er veel regels zijn die dezelfde acties delen, voegt u de regels samen tot één regel. Regels activeren hun acties zodra aan een enkele voorwaarde is voldaan. Dit versnelt het matchen en vermindert het geheugengebruik voor dubbele actiesets.

In plaats van
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]);
De voorkeur geven aan
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]);

Gefilterde evenementen

Gefilterde gebeurtenissen zijn een mechanisme waarmee luisteraars een subset van gebeurtenissen kunnen specificeren waarin zij geïnteresseerd zijn. Een luisteraar die een filter gebruikt, wordt niet aangeroepen voor gebeurtenissen die het filter niet passeren, waardoor de luistercode declaratiever en efficiënter wordt. . Een servicemedewerker hoeft niet wakker te worden gemaakt om gebeurtenissen af ​​te handelen die hem niet interesseren.

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

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

Gebeurtenissen ondersteunen specifieke filters die betekenisvol zijn voor die gebeurtenis. De lijst met filters die een gebeurtenis ondersteunt, wordt vermeld in de documentatie voor die gebeurtenis in de sectie 'filters'.

Bij het matchen van URL's (zoals in het bovenstaande voorbeeld) ondersteunen gebeurtenisfilters dezelfde mogelijkheden voor URL-matching als die kunnen worden uitgedrukt met events.UrlFilter , behalve voor het matchen van schema's en poorten.

Soorten

Event

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

Eigenschappen

  • addListener

    leegte

    Registreert een terugbelactie van een gebeurtenislistener naar een gebeurtenis.

    De addListener functie ziet er als volgt uit:

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

    • terugbellen

      H

      Wordt gebeld wanneer er een gebeurtenis plaatsvindt. De parameters van deze functie zijn afhankelijk van het type gebeurtenis.

  • regels toevoegen

    leegte

    Registreert regels voor het afhandelen van gebeurtenissen.

    De addRules functie ziet er als volgt uit:

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

    • regels

      Regel <anyany>[]

      Regels om te registreren. Deze vervangen geen eerder geregistreerde regels.

    • terugbellen

      functie optioneel

      De callback parameter ziet er als volgt uit:

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

      • regels

        Regel <anyany>[]

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

  • ontvangRegels

    leegte

    Retourneert momenteel geregistreerde regels.

    De getRules functie ziet er als volgt uit:

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

    • ruleIdentifiers

      tekenreeks[] optioneel

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

    • terugbellen

      functie

      De callback parameter ziet er als volgt uit:

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

      • regels

        Regel <anyany>[]

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

  • heeftListener

    leegte

    De hasListener functie ziet er als volgt uit:

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

    • terugbellen

      H

      Luisteraar wiens registratiestatus wordt getest.

    • retourneert

      Booleaans

      Waar als callback is geregistreerd bij de gebeurtenis.

  • heeft luisteraars

    leegte

    De hasListeners functie ziet er als volgt uit:

    () => {...}

    • retourneert

      Booleaans

      Waar als er gebeurtenislisteners bij de gebeurtenis zijn geregistreerd.

  • verwijderListener

    leegte

    Maakt de registratie van een terugbellen van een gebeurtenislistener bij een gebeurtenis ongedaan.

    De removeListener functie ziet er als volgt uit:

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

    • terugbellen

      H

      Luisteraar die niet is geregistreerd.

  • verwijderRegels

    leegte

    Maakt de registratie van momenteel geregistreerde regels ongedaan.

    De removeRules functie ziet er als volgt uit:

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

    • ruleIdentifiers

      tekenreeks[] optioneel

      Als een array wordt doorgegeven, worden alleen regels met ID's in deze array niet meer geregistreerd.

    • terugbellen

      functie optioneel

      De callback parameter ziet er als volgt uit:

      () => void

Rule

Beschrijving van een declaratieve regel voor het afhandelen van gebeurtenissen.

Eigenschappen

  • acties

    elk[]

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

  • voorwaarden

    elk[]

    Lijst met voorwaarden die de acties kunnen activeren.

  • Identiteitskaart

    tekenreeks optioneel

    Optionele ID waarmee naar deze regel kan worden verwezen.

  • prioriteit

    nummer optioneel

    Optionele prioriteit van deze regel. Standaard ingesteld op 100.

  • labels

    tekenreeks[] optioneel

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

UrlFilter

Filtert URL's op verschillende criteria. Zie gebeurtenisfiltering . Alle criteria zijn hoofdlettergevoelig.

Eigenschappen

  • cidrBlokken

    tekenreeks[] optioneel

    Chroom 123+

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

  • hostBevat

    tekenreeks optioneel

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

  • gastheerGelijk

    tekenreeks optioneel

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

  • hostvoorvoegsel

    tekenreeks optioneel

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

  • hostachtervoegsel

    tekenreeks optioneel

    Komt overeen als de hostnaam van de URL eindigt met 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 .

  • padBevat

    tekenreeks optioneel

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

  • padGelijk aan

    tekenreeks optioneel

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

  • padVoorvoegsel

    tekenreeks optioneel

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

  • padAchtervoegsel

    tekenreeks optioneel

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

  • havens

    (nummer | nummer[])[] optioneel

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

  • vraagBevat

    tekenreeks optioneel

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

  • vraagGelijk aan

    tekenreeks optioneel

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

  • queryPrefix

    tekenreeks optioneel

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

  • queryAchtervoegsel

    tekenreeks optioneel

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

  • schema's

    tekenreeks[] optioneel

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

  • urlBevat

    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.

  • urlGelijk aan

    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 .

  • urlVoorvoegsel

    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.

  • urlAchtervoegsel

    tekenreeks optioneel

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