Description
L'espace de noms chrome.events
contient des types courants utilisés par les API qui envoient des événements pour vous avertir lorsqu'il se passe quelque chose d'intéressant.
Un Event
est un objet qui vous permet d'être averti lorsqu'il se passe quelque chose d'intéressant. Voici un exemple d'utilisation de l'événement chrome.alarms.onAlarm
pour être averti chaque fois qu'une alarme se termine:
chrome.alarms.onAlarm.addListener(function(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 constater que la fonction comporte un seul paramètre: un objet alarms.Alarm
contenant 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 aller-retour et offre une efficacité très élevée.
Les gestionnaires d'événements déclaratifs sont utilisés, par exemple, dans l'API Declarative Web Request et Declarative Content API. 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 est constituée d'une ou de plusieurs conditions et d'une ou plusieurs actions:
var 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 à chaque règle un identifiant, ce qui simplifie l'annulation de l'enregistrement des règles précédemment enregistrées, ainsi qu'une priorité pour 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 ordre spécifique. Les actions sont exécutées dans l'ordre décroissant de priorité de leurs règles.
var 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 a 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 sont associés à 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. Son premier paramètre est un tableau d'instances de règle, ainsi qu'une fonction de rappel appelée une fois l'opération terminée.
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
Si les règles ont bien été insérées, 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
étaient 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 actuellement utilisé par aucune autre règle ou un identifiant vide.
Suppression des règles
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 comme deuxième paramètre.
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
Si rule_ids
est un tableau d'identifiants, toutes les règles comportant des identifiants répertoriés dans le tableau sont supprimées. Si rule_ids
indique un identifiant inconnu, 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. 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 actuellement enregistrées, appelez la fonction getRules()
. Elle accepte un tableau facultatif d'identifiants de règles avec la même sémantique que removeRules
, ainsi qu'une fonction de rappel.
var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(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 optimiser les performances, tenez compte des consignes suivantes.
Enregistrez et annulez l'enregistrement de règles de manière groupée. Après chaque enregistrement ou désinscription, Chrome doit mettre à jour les structures de données internes. Cette mise à jour est une opération coûteuse.
À la place de :
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
préfèrent:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
Privilégiez la correspondance de sous-chaîne aux expressions régulières dans events.UrlFilter. La mise en correspondance basée sur une sous-chaîne est extrêmement rapide.
À la place de :
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {urlMatches: "example.com/[^?]*foo" } });
préfèrent:
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {hostSuffix: "example.com", pathContains: "foo"} });
Si plusieurs 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.
À la place de :
var condition1 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } });
var condition2 = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' } });
var rule1 = { conditions: [condition1],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
var rule2 = { conditions: [condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
préfèrent:
var 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 qui les intéressent. Un écouteur qui utilise un filtre n'est pas appelé pour les événements qui ne le transmettent pas, ce qui rend le code d'écoute plus déclaratif et efficace. Un service worker n'a pas besoin d'être activé pour gérer les événements dont il n'a pas besoin.
Les événements filtrés sont destinés à permettre la transition d'un code de filtrage manuel comme suit:
chrome.webNavigation.onCommitted.addListener(function(e) {
if (hasHostSuffix(e.url, 'google.com') ||
hasHostSuffix(e.url, 'google.com.au')) {
// ...
}
});
comme ceci:
chrome.webNavigation.onCommitted.addListener(function(e) {
// ...
}, {url: [{hostSuffix: 'google.com'},
{hostSuffix: 'google.com.au'}]});
Les événements acceptent les filtres spécifiques qui sont pertinents pour cet événement. La liste des filtres compatibles avec un événement est répertoriée dans la documentation de cet événement, dans la section "Filtres".
Lorsque vous faites correspondre des URL (comme dans l'exemple ci-dessus), les filtres d'événement prennent en charge les mêmes fonctionnalités de mise en correspondance d'URL que celles qui peuvent être exprimées avec un events.UrlFilter
, à l'exception de la mise en correspondance du schéma et des ports.
Types
Event
Objet permettant d'ajouter et de supprimer des écouteurs pour un événement Chrome.
Propriétés
-
addListener
void
Enregistre un rappel d'écouteur d'événements en tant qu'événement.
La fonction
addListener
se présente comme suit :(callback: H) => {...}
-
rappel
H
Appelée lorsqu'un événement se produit. Les paramètres de cette fonction dépendent du type d'événement.
-
-
addRules
void
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. Celles-ci ne remplacent pas les règles précédemment enregistrées.
-
rappel
fonction facultative
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 remplis de valeurs.
-
-
-
getRules
void
Affiche 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 avec des identifiants contenus dans ce tableau sont renvoyées.
-
rappel
function
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 remplis de valeurs.
-
-
-
hasListener
void
La fonction
hasListener
se présente comme suit :(callback: H) => {...}
-
rappel
H
Écouteur dont l'état d'enregistrement doit être testé.
-
retours
boolean
Vrai si un rappel est enregistré pour l'événement.
-
-
hasListeners
void
La fonction
hasListeners
se présente comme suit :() => {...}
-
retours
boolean
"True" si des écouteurs d'événements sont enregistrés pour l'événement.
-
-
removeListener
void
Annule l'enregistrement d'un rappel d'écouteur d'événements d'un événement.
La fonction
removeListener
se présente comme suit :(callback: H) => {...}
-
rappel
H
Paramètre "Listener" dont l'enregistrement sera annulé.
-
-
removeRules
void
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 contenant des identifiants dans ce tableau sont désenregistrées.
-
rappel
fonction facultative
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
-
correctives
tout[]
Liste des actions déclenchées si l'une des conditions est remplie.
-
conditions
tout[]
Liste des conditions pouvant déclencher les actions.
-
id
string facultatif
Identifiant facultatif permettant de référencer cette règle.
-
campagne
numéro facultatif
Priorité facultative de cette règle. La valeur par défaut est 100.
-
tags
string[] facultatif
Les tags peuvent servir à annoter des règles et à effectuer des opérations sur des ensembles de règles.
UrlFilter
Filtre les URL en fonction de différents critères. Voir Filtrage des événements. Tous les critères sont sensibles à la casse.
Propriétés
-
cidrBlocks
string[] facultatif
Chrome 123 et versions ultérieuresCorrespond si la partie hôte de l'URL est une adresse IP et est contenue dans l'un des blocs CIDR spécifiés dans le tableau.
-
hostContains
string facultatif
Correspond si le nom d'hôte de l'URL contient une chaîne spécifiée. Pour tester si un composant de nom d'hôte comporte le préfixe "foo", utilisez hostContains: ".foo". Cela 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 de composant ("foo.") et exactement avec les composants (".foo."). La mise en correspondance exacte et du suffixe des 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
string facultatif
Correspond si le nom d'hôte de l'URL est égal à une chaîne spécifiée.
-
hostPrefix
string facultatif
Correspond si le nom d'hôte de l'URL commence par une chaîne spécifiée.
-
hostSuffix
string facultatif
Correspond si le nom d'hôte de l'URL se termine par une chaîne spécifiée.
-
originAndPathMatches
string facultatif
Recherche une correspondance si l'URL sans segment de requête et 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
string facultatif
Correspond si le segment du chemin de l'URL contient une chaîne spécifiée.
-
pathEquals
string facultatif
Correspond si le segment du chemin de l'URL est égal à une chaîne spécifiée.
-
pathPrefix
string facultatif
Correspond si le segment du chemin de l'URL commence par une chaîne spécifiée.
-
pathSuffix
string facultatif
Correspond si le segment du chemin de l'URL se termine par une chaîne spécifiée.
-
ports
(numéro | nombre[])[] facultatif
Recherche une correspondance si le port de l'URL figure dans l'une des listes de ports spécifiées. Par exemple,
[80, 443, [1000, 1200]]
correspond à toutes les requêtes effectuées sur les ports 80, 443 et dans la plage 1 000-1 200. -
queryContains
string facultatif
Correspond si le segment de requête de l'URL contient une chaîne spécifiée.
-
queryEquals
string facultatif
Correspond si le segment de requête de l'URL est égal à une chaîne spécifiée.
-
queryPrefix
string facultatif
Correspond si le segment de requête de l'URL commence par une chaîne spécifiée.
-
querySuffix
string facultatif
Correspond si le segment de requête de l'URL se termine par une chaîne spécifiée.
-
schemes
string[] facultatif
Correspond si le schéma de l'URL est égal à l'un des schémas spécifiés dans le tableau.
-
urlContains
string facultatif
Correspond si l'URL (sans identifiant 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
string facultatif
Correspond si l'URL (sans identifiant 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
string facultatif
Recherche une correspondance si l'URL (sans 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.
-
urlPrefix
string 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
string 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.