chrome.evenementen

Beschrijving

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.

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

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.

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

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.

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

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.

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

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.