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.

Opmerking: regels zijn blijvend tijdens browsersessies. Daarom moet u tijdens de installatie van de extensie regels installeren met behulp van de gebeurtenis runtime.onInstalled . Houd er rekening mee dat deze gebeurtenis ook wordt geactiveerd wanneer een extensie wordt bijgewerkt. Daarom moet u eerst eerder geïnstalleerde regels wissen en vervolgens nieuwe regels registreren.

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.