browser.events

Description

L'espace de noms chrome.events contient les types courants utilisés par les API qui envoient des événements pour vous avertir lorsqu'un événement intéressant se produit.

Concepts et utilisation

Un Event est un objet qui vous permet d'être averti 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 s'est écoulée :

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

Comme le montre l'exemple, vous vous inscrivez pour recevoir des 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 n'a qu'un seul paramètre : un objet alarms.Alarm qui contient des détails 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 les latences d'aller-retour et permet une efficacité très élevée.

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 de plusieurs conditions, et d'une ou de 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 la désinscription des règles précédemment enregistrées, ainsi qu'une priorité pour définir l'ordre de priorité 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 accepter des règles. Ces objets d'événement n'appellent pas de fonction de rappel lorsque des événements se produisent, mais vérifient si une règle enregistrée remplit au moins une condition et exécutent les actions associées à cette règle. Les objets d'événement compatibles avec l'API déclarative disposent de 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. Elle utilise un tableau d'instances de règles comme premier paramètre et une fonction de rappel appelée à la fin de l'opération.

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

Si les règles ont bien été insérées, le paramètre details contient un tableau des règles insérées, qui s'affichent dans le même ordre que dans le paramètre rule_list transmis, où les paramètres facultatifs id et priority ont été renseignés 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 ou un identifiant vide.

Supprimer des règles

Pour supprimer des règles, appelez la fonction removeRules(). Elle accepte un tableau facultatif d'identifiants de règle 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 sont listés 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(). Elle accepte un tableau facultatif d'identifiants de règle 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 optimales, gardez à l'esprit les consignes suivantes.

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

au lieu de
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);
Vos préférences
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Privilégiez la correspondance de sous-chaîne plutôt que les expressions régulières dans un events.UrlFilter. La mise en correspondance basée sur les sous-chaînes est extrêmement rapide.

au lieu de
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Vos préférences
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.

au lieu de
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]);
Vos préférences
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. Il n'est pas nécessaire de réveiller un service worker pour gérer des événements qui ne le concernent pas.

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

au lieu de
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Vos préférences
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 pertinents. La liste des filtres compatibles avec un événement est indiquée dans la documentation de cet événement, dans la section "Filtres".

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

Types

Event

Objet permettant d'ajouter et de supprimer des écouteurs pour un événement Chrome.

Propriétés

  • addListener

    vide

    Enregistre un rappel d'écouteur d'événements pour un événement.

    La fonction addListener se présente comme suit : 

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

    • callback

      H

      Appelé lorsqu'un événement se produit. Les paramètres de cette fonction dépendent du type d'événement.

  • addRules

    vide

    Enregistre des règles pour gérer les événements.

    La fonction addRules se présente comme suit : 

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

    • règles

      Règle<anyany>[]

      Règles à enregistrer. Elles ne remplacent pas les règles enregistrées précédemment.

    • callback

      function facultatif

      Le paramètre callback se présente comme suit : 

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

      • règles

        Règle<anyany>[]

        Règles enregistrées, les paramètres facultatifs sont renseignés avec des valeurs.

  • getRules

    vide

    Renvoie les règles actuellement enregistrées.

    La fonction getRules se présente comme suit : 

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

    • ruleIdentifiers

      string[] facultatif

      Si un tableau est transmis, seules les règles dont les identifiants sont contenus dans ce tableau sont renvoyées.

    • callback

      fonction

      Le paramètre callback se présente comme suit : 

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

      • règles

        Règle<anyany>[]

        Règles enregistrées, les paramètres facultatifs sont renseignés avec des valeurs.

  • hasListener

    vide

    La fonction hasListener se présente comme suit : 

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

    • callback

      H

      Écouteur dont l'état d'enregistrement doit être testé.

    • Renvoie

      booléen

      "True" si callback est enregistré pour l'événement.

  • hasListeners

    vide

    La fonction hasListeners se présente comme suit : 

    () => {...}

    • Renvoie

      booléen

      "True" si des écouteurs d'événements sont enregistrés pour l'événement.

  • removeListener

    vide

    Annule l'enregistrement d'un rappel d'écouteur d'événements pour un événement.

    La fonction removeListener se présente comme suit : 

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

    • callback

      H

      Écouteur dont l'enregistrement doit être annulé.

  • removeRules

    vide

    Annule l'enregistrement des règles actuellement enregistrées.

    La fonction removeRules se présente comme suit : 

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

    • ruleIdentifiers

      string[] facultatif

      Si un tableau est transmis, seules les règles dont les identifiants sont contenus dans ce tableau sont désenregistrées.

    • callback

      function facultatif

      Le paramètre callback se présente comme suit : 

      () => void

Rule

Description d'une règle déclarative pour la gestion des événements.

Propriétés

  • actions

    any[]

    Liste des actions déclenchées si l'une des conditions est remplie.

  • conditions

    any[]

    Liste des conditions pouvant déclencher les actions.

  • id

    chaîne facultatif

    Identifiant facultatif permettant de référencer cette règle.

  • priorité

    number facultatif

    Priorité facultative de cette règle. La valeur par défaut est 100.

  • tags

    string[] facultatif

    Les tags peuvent être utilisés pour annoter des règles et effectuer des opérations sur des ensembles de règles.

UrlFilter

Filtre les URL selon différents critères. Consultez la section Filtrage des événements. Tous les critères sont sensibles à la casse.

Propriétés

  • cidrBlocks

    string[] facultatif

    Chrome 123+ browser.* depuis Chrome 148

    Correspond si la partie hôte de l'URL est une adresse IP et qu'elle est contenue dans l'un des blocs CIDR spécifiés dans le tableau.

  • hostContains

    chaîne facultatif

    Correspond si le nom d'hôte de l'URL contient une chaîne spécifiée. Pour vérifier si un composant de nom d'hôte comporte le préfixe "foo", utilisez hostContains: ".foo". Cette expression correspond à "www.foobar.com" et "foo.com", car un point implicite est ajouté au début du nom d'hôte. De même, hostContains peut être utilisé pour établir une correspondance avec le suffixe du composant ("foo.") et pour établir une correspondance exacte avec les composants (".foo."). La correspondance exacte et par suffixe pour les derniers composants doit être effectuée séparément à l'aide de hostSuffix, car aucun point implicite n'est ajouté à la fin du nom d'hôte.

  • hostEquals

    chaîne facultatif

    Correspond si le nom d'hôte de l'URL est égal à une chaîne spécifiée.

  • hostPrefix

    chaîne facultatif

    Correspond si le nom d'hôte de l'URL commence par une chaîne spécifiée.

  • hostSuffix

    chaîne facultatif

    Correspond si le nom d'hôte de l'URL se termine par une chaîne spécifiée.

  • originAndPathMatches

    chaîne facultatif

    Correspond si l'URL sans segment de requête ni identifiant de fragment correspond à une expression régulière spécifiée. Les numéros de port sont supprimés de l'URL s'ils correspondent au numéro de port par défaut. Les expressions régulières utilisent la syntaxe RE2.

  • pathContains

    chaîne facultatif

    Correspond si le segment de chemin d'accès de l'URL contient une chaîne spécifiée.

  • pathEquals

    chaîne facultatif

    Correspond si le segment de chemin de l'URL est égal à une chaîne spécifiée.

  • pathPrefix

    chaîne facultatif

    Correspond si le segment de chemin d'accès de l'URL commence par une chaîne spécifiée.

  • pathSuffix

    chaîne facultatif

    Correspond si le segment de chemin de l'URL se termine par une chaîne spécifiée.

  • ports

    (number | number[])[] facultatif

    Correspond si le port de l'URL est contenu dans l'une des listes de ports spécifiées. Par exemple, [80, 443, [1000, 1200]] correspond à toutes les requêtes sur les ports 80 et 443, et dans la plage 1000-1200.

  • queryContains

    chaîne facultatif

    Correspond si le segment de requête de l'URL contient une chaîne spécifiée.

  • queryEquals

    chaîne facultatif

    Correspond si le segment de requête de l'URL est égal à une chaîne spécifiée.

  • queryPrefix

    chaîne facultatif

    Correspond si le segment de requête de l'URL commence par une chaîne spécifiée.

  • querySuffix

    chaîne facultatif

    Correspond si le segment de requête de l'URL se termine par une chaîne spécifiée.

  • schémas

    string[] facultatif

    Correspond si le schéma de l'URL est égal à l'un des schémas spécifiés dans le tableau.

  • urlContains

    chaîne facultatif

    Correspond si l'URL (sans identificateur de fragment) contient une chaîne spécifiée. Les numéros de port sont supprimés de l'URL s'ils correspondent au numéro de port par défaut.

  • urlEquals

    chaîne facultatif

    Correspond si l'URL (sans identificateur de fragment) est égale à une chaîne spécifiée. Les numéros de port sont supprimés de l'URL s'ils correspondent au numéro de port par défaut.

  • urlMatches

    chaîne facultatif

    Correspond si l'URL (sans identificateur de fragment) correspond à une expression régulière spécifiée. Les numéros de port sont supprimés de l'URL s'ils correspondent au numéro de port par défaut. Les expressions régulières utilisent la syntaxe RE2.

  • urlPrefix

    chaîne facultatif

    Correspond si l'URL (sans identifiant de fragment) commence par une chaîne spécifiée. Les numéros de port sont supprimés de l'URL s'ils correspondent au numéro de port par défaut.

  • urlSuffix

    chaîne facultatif

    Correspond si l'URL (sans identifiant de fragment) se termine par une chaîne spécifiée. Les numéros de port sont supprimés de l'URL s'ils correspondent au numéro de port par défaut.