browser.events

Beschrijving

Concepten en gebruik

Een Event is een object waarmee je een melding kunt ontvangen wanneer er iets interessants gebeurt. Hier is een voorbeeld van het gebruik van de browser.alarms.onAlarm -gebeurtenis om een ​​melding te ontvangen wanneer een alarm is afgelopen:

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

Zoals het voorbeeld laat zien, registreer je je voor notificaties met behulp van addListener() . Het argument van addListener() is altijd een functie die je definieert om de gebeurtenis af te handelen, maar de parameters van de functie zijn afhankelijk van de gebeurtenis die je afhandelt. Als je de documentatie voor alarms.onAlarm bekijkt, zie je dat de functie één parameter heeft: een alarms.Alarm object met details over het verlopen alarm.

Voorbeelden van API's die gebruikmaken van gebeurtenissen: alarmen , i18n , identiteit , runtime . De meeste Chrome-API's doen dat.

Declaratieve gebeurtenisafhandelaars

Declaratieve gebeurtenisafhandelaars bieden een manier om regels te definiëren die bestaan ​​uit declaratieve voorwaarden en acties. Voorwaarden worden in de browser geëvalueerd in plaats van in de JavaScript-engine, wat de latentie vermindert en een zeer hoge efficiëntie mogelijk maakt.

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

Regels

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

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

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

Naast voorwaarden en acties kunt u elke regel een identificatiecode geven, wat het verwijderen van eerder geregistreerde regels vereenvoudigt, en een prioriteit om de voorrang van regels te definiëren. Prioriteiten worden alleen in overweging genomen als regels met elkaar conflicteren of in een specifieke volgorde moeten worden uitgevoerd. Acties worden uitgevoerd in aflopende volgorde van de prioriteit van de bijbehorende 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 wanneer er gebeurtenissen plaatsvinden, maar testen of een geregistreerde regel ten minste één vervulde voorwaarde heeft 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, roep je de functie addRules() van het `event`-object aan. Deze functie neemt een array met regelinstanties als eerste parameter en een callback-functie die na voltooiing wordt aangeroepen.

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

Als de regels succesvol zijn ingevoegd, bevat de parameter details een array met de ingevoegde regels in dezelfde volgorde 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 wanneer de callbackfunctie wordt aangeroepen. Elke regel in rule_list moet een unieke identificatiecode bevatten die nog niet door een andere regel wordt gebruikt, of een lege identificatiecode.

Verwijder regels

Om regels te verwijderen, roep je de functie removeRules() aan. Deze functie accepteert een optionele array met 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 identificatoren is, worden alle regels met identificatoren uit de array verwijderd. Als rule_ids een onbekende identificator bevat, wordt deze identificator stilzwijgend genegeerd. Als rule_ids undefined is, worden alle geregistreerde regels van deze extensie verwijderd. De functie callback() wordt aangeroepen wanneer de regels zijn verwijderd.

Regels ophalen

Om een ​​lijst met geregistreerde regels op te halen, roept u de functie getRules() aan. Deze functie accepteert een optionele array met 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 aan de callback() functie wordt doorgegeven, verwijst naar een array van regels, inclusief ingevulde optionele parameters.

Prestatie

Om maximale prestaties te bereiken, dient u de volgende richtlijnen in acht te nemen.

Regels kunnen in bulk worden geregistreerd en gederegistreerd. Na elke registratie of deregistratie moet Chrome de interne datastructuren bijwerken. Deze update is een kostbare bewerking.

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

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

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

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

Als er veel regels zijn die dezelfde acties delen, voeg ze dan samen tot één regel. Regels activeren hun acties zodra aan één enkele voorwaarde is voldaan. Dit versnelt het matchen en vermindert het geheugenverbruik voor dubbele actiesets.

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]);

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 evenementen

Gefilterde gebeurtenissen zijn een mechanisme waarmee luisteraars een subset van gebeurtenissen kunnen specificeren waarin ze geïnteresseerd zijn. Een luisteraar die een filter gebruikt, wordt niet aangeroepen voor gebeurtenissen die niet aan het filter voldoen, waardoor de luistercode declaratiever en efficiënter wordt. Een service worker hoeft niet te worden gewekt om gebeurtenissen af ​​te handelen waar hij geen interesse in heeft.

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

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Voor bepaalde gebeurtenissen zijn specifieke filters beschikbaar die relevant zijn voor die gebeurtenis. De lijst met filters die een gebeurtenis ondersteunt, staat vermeld in de documentatie van 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 welke kunnen worden uitgedrukt met een events.UrlFilter , met uitzondering van het matchen van schema en poort.