browser.events

Description

Concepts et utilisation

Un Event est un objet qui vous permet de recevoir des notifications lorsqu'un événement intéressant se produit. Voici un exemple d'utilisation de l'événement browser.alarms.onAlarm pour être averti chaque fois qu'une alarme a sonné :

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

Comme le montre l'exemple, vous vous inscrivez aux notifications à l'aide de addListener(). L'argument de addListener() est toujours une fonction que vous définissez pour gérer l'événement, mais les paramètres de la fonction dépendent de l'événement que vous gérez. En consultant la documentation de alarms.onAlarm, vous pouvez voir que la fonction comporte un seul paramètre : un objet alarms.Alarm qui contient des informations sur l'alarme écoulée.

Exemples d'API utilisant des événements : alarms, i18n, identity, runtime. La plupart des API Chrome le font.

Gestionnaires d'événements déclaratifs

Les gestionnaires d'événements déclaratifs permettent de définir des règles composées de conditions et d'actions déclaratives. Les conditions sont évaluées dans le navigateur plutôt que dans le moteur JavaScript, ce qui réduit la latence aller-retour et permet une très grande efficacité.

Les gestionnaires d'événements déclaratifs sont utilisés, par exemple, dans l'API Declarative Content. Cette page décrit les concepts sous-jacents de tous les gestionnaires d'événements déclaratifs.

Règles

La règle la plus simple possible se compose d'une ou plusieurs conditions et d'une ou plusieurs actions :

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

Si l'une des conditions est remplie, toutes les actions sont exécutées.

En plus des conditions et des actions, vous pouvez attribuer un identifiant à chaque règle, ce qui simplifie l'annulation de l'enregistrement des règles précédemment enregistrées, ainsi qu'une priorité pour définir les précédences entre les règles. Les priorités ne sont prises en compte que si les règles sont en conflit ou doivent être exécutées dans un ordre spécifique. Les actions sont exécutées par ordre décroissant de priorité de leurs règles.

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

Objets d'événement

Les objets d'événement peuvent être compatibles avec les règles. Ces objets d'événement n'appellent pas de fonction de rappel lorsque des événements se produisent, mais testent si une règle enregistrée comporte au moins une condition remplie et exécutent les actions associées à cette règle. Les objets d'événement compatibles avec l'API déclarative comportent trois méthodes pertinentes : events.Event.addRules(), events.Event.removeRules() et events.Event.getRules().

Ajouter des règles

Pour ajouter des règles, appelez la fonction addRules() de l'objet d'événement. Il utilise un tableau d'instances de règles comme premier paramètre et une fonction de rappel qui est appelée à la fin.

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

Si les règles ont été insérées correctement, le paramètre details contient un tableau de règles insérées qui apparaissent dans le même ordre que dans le rule_list transmis, où les paramètres facultatifs id et priority ont été remplis avec les valeurs générées. Si une règle n'est pas valide (par exemple, parce qu'elle contient une condition ou une action non valide), aucune règle n'est ajoutée et la variable runtime.lastError est définie lorsque la fonction de rappel est appelée. Chaque règle de rule_list doit contenir un identifiant unique qui n'est pas déjà utilisé par une autre règle ni un identifiant vide.

Supprimer des règles

Pour supprimer des règles, appelez la fonction removeRules(). Il accepte un tableau facultatif d'identifiants de règles comme premier paramètre et une fonction de rappel comme deuxième paramètre.

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

Si rule_ids est un tableau d'identifiants, toutes les règles dont les identifiants figurent dans le tableau sont supprimées. Si rule_ids liste un identifiant inconnu, celui-ci est ignoré sans notification. Si rule_ids est défini sur undefined, toutes les règles enregistrées de cette extension sont supprimées. La fonction callback() est appelée lorsque les règles ont été supprimées.

Récupérer des règles

Pour récupérer la liste des règles enregistrées, appelez la fonction getRules(). Il accepte un tableau facultatif d'identifiants de règles avec la même sémantique que removeRules() et une fonction de rappel.

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

Le paramètre details transmis à la fonction callback() fait référence à un tableau de règles incluant des paramètres facultatifs renseignés.

Performances

Pour obtenir des performances maximales, vous devez garder à l'esprit les consignes suivantes.

Enregistrez et annulez l'enregistrement des règles de manière groupée. Après chaque enregistrement ou désenregistrement, Chrome doit mettre à jour les structures de données internes. Cette mise à jour est une opération coûteuse.

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

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

Préférez la correspondance de sous-chaîne aux expressions régulières dans un events.UrlFilter. La mise en correspondance basée sur les sous-chaînes est extrêmement rapide.

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

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

Si de nombreuses règles partagent les mêmes actions, fusionnez-les en une seule. Les règles déclenchent leurs actions dès qu'une seule condition est remplie. Cela accélère la mise en correspondance et réduit la consommation de mémoire pour les ensembles d'actions en double.

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

Événements filtrés

Les événements filtrés sont un mécanisme qui permet aux écouteurs de spécifier un sous-ensemble d'événements qui les intéressent. Un écouteur qui utilise un filtre ne sera pas appelé pour les événements qui ne passent pas le filtre, ce qui rend le code d'écoute plus déclaratif et efficace. Un service worker n'a pas besoin d'être réveillé pour gérer les événements qui ne l'intéressent pas.

Les événements filtrés sont destinés à permettre une transition à partir du code de filtrage manuel.

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

Les événements sont compatibles avec des filtres spécifiques qui leur sont propres. La liste des filtres compatibles avec un événement est indiquée dans la section "Filtres" de la documentation de cet événement.

Lors de la mise en correspondance des URL (comme dans l'exemple ci-dessus), les filtres d'événements sont compatibles avec les mêmes fonctionnalités de mise en correspondance des URL que celles exprimables avec un events.UrlFilter, à l'exception de la mise en correspondance du schéma et du port.