chrome.events

Description

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 chrome.alarms.onAlarm pour être averti à la fin d'une alarme:

chrome.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 dépendent de l'événement que vous gérez. Consultez la documentation de alarms.onAlarm. vous pouvez voir que la fonction comporte un seul paramètre: un objet alarms.Alarm dont les détails sur l'alarme écoulée.

Exemples d'API utilisant des événements: alarms, i18n, identity, runtime. La plupart des chromes les API.

Gestionnaires d'événements déclaratifs

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

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

Règles

La règle la plus simple est constituée d'une ou de 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é permettant de définir des priorités 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 commande. Les actions sont exécutées dans l'ordre décroissant de la 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 "Événement"

Les objets "Événement" peuvent être compatibles avec les règles. Ces objets d'événement n'appellent pas de fonction de rappel lorsque événements se produisent, mais vérifiez si une règle enregistrée a au moins une condition remplie et exécutez les actions associées à cette règle. Les objets d'événement qui prennent en charge 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 événement. Il prend un tableau d'instances de règle comme premier paramètre et une fonction de rappel appelée à la fin.

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 de règles insérées. apparaissent dans le même ordre que dans l'élément 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éfini lorsque la fonction de rappel est appelée. Chaque règle dans rule_list doit contenir un seul qui n'est pas déjà utilisé par une autre règle ou un identifiant vide.

Supprimer la règle

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

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

Si rule_ids est un tableau d'identifiants, toutes les règles ayant des identifiants listés dans le tableau sont supprimés. Si rule_ids répertorie un identifiant, cet identifiant est ignoré sans notification. Si rule_ids est défini sur undefined. Toutes les règles enregistrées de cette extension sont supprimées. callback() est appelée lorsque les règles ont été supprimées.

Récupérer les 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 comprenant des paramètres facultatifs renseignés.

Performances

Pour obtenir des performances optimales, tenez compte des consignes suivantes.

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

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

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

Privilégiez la correspondance de sous-chaîne aux expressions régulières dans un élément events.UrlFilter. La correspondance basée sur des sous-chaînes est extrêmement rapide.

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

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

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

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

É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 qu'ils qui vous intéressent. Un écouteur qui utilise un filtre ne sera pas appelé pour les événements qui ne transmettent pas la valeur ce qui rend le code d'écoute plus déclaratif et efficace. Les besoins d'un service worker ne pas être réveillé(e) pour gérer les événements dont il n’a pas besoin.

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

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

Les événements sont compatibles avec des filtres spécifiques pertinents pour cet événement. La liste des filtres appliqués à un événement sont répertoriés dans la documentation pour cet événement, dans la section "filtres" .

Lorsque les URL sont mises en correspondance (comme dans l'exemple ci-dessus), les filtres d'événement acceptent la même correspondance peuvent être exprimées avec events.UrlFilter, à l'exception de la mise en correspondance de schéma et de port.