EventTarget.
Déclenche un événement sur un élément depuis le code. Avec CustomEvent, elle permet de créer vos propres événements avec des données supplémentaires.
- Renvoie
falsesi l’événement aveccancelable: truea été annulé parpreventDefault(), sinontrue.
Exemple
#const finish = document.querySelector('#finish')
const points = document.querySelector('#points')
document.addEventListener('lesson:complete', (event) => {
const total = Number(points.textContent) + event.detail.points
points.textContent = total
console.log(`${event.detail.title} : +${event.detail.points} pts, total ${total}`)
})
finish.addEventListener('click', () => {
const event = new CustomEvent('lesson:complete', {
bubbles: true,
detail: { title: 'Boucles', points: 30 }
})
finish.dispatchEvent(event)
})
finish.click()Le bouton annonce la fin de la leçon, et le compteur de points écoute sur document. L’événement y parvient grâce à bubbles: true. Chaque clic dans l’aperçu ajoutera 30 points de plus.
Définition et utilisation
#La méthode dispatchEvent() envoie à l’élément un objet événement préparé à l’avance, et le navigateur exécute toutes les fonctions de gestion enregistrées pour ce type. Cela se passe de façon synchrone : le code écrit après dispatchEvent() ne s’exécute qu’une fois que tous les écouteurs ont fini de s’exécuter.
Vous créez l’événement avec un constructeur, par ex. new Event("input"), new KeyboardEvent("keydown", { key: "Enter" }) ou new CustomEvent("nom", { detail }). CustomEvent sert à vos propres événements : dans le champ detail, vous passez des données quelconques, par ex. le nombre de points gagnés. Ainsi, une partie de l’application peut annoncer « leçon terminée », et d’autres peuvent y réagir sans rien savoir les unes des autres.
Un événement créé de cette façon ne bouillonne pas vers les parents par défaut, et ne peut pas être annulé. Les options bubbles: true et cancelable: true changent cela. La méthode renvoie false si un écouteur a appelé preventDefault() sur un événement avec cancelable: true, et true sinon.
Les événements déclenchés depuis le code ont event.isTrusted à false. En général, ils ne déclenchent pas non plus les actions par défaut du navigateur : un keydown artificiel n’insère pas de caractère dans un champ, et un événement submit n’envoie pas le formulaire. Pour simuler un clic, le plus simple est d’utiliser element.click(), et pour envoyer un formulaire, form.requestSubmit().
Syntaxe
#target.dispatchEvent(event)
new Event(type, options)
new CustomEvent(type, { detail, bubbles, cancelable })Paramètres
#event
objet Event
L’événement à envoyer, créé par ex. avecnew Event()ounew CustomEvent().type
chaîne (dans le constructeur)
Le nom de l’événement. Nommez vos propres événements de façon à éviter toute collision avec les événements intégrés, par ex."lesson:complete".options
objet, optionnel (dans le constructeur)
detail(données quelconques, seulement dansCustomEvent),bubblesetcancelable. Ces deux derniers valentfalsepar défaut.
Plus d’exemples
#const search = document.querySelector('#search')
search.addEventListener('input', (event) => {
console.log('Recherche :', search.value, '| isTrusted :', event.isTrusted)
})
search.value = 'python'
console.log('Avant dispatchEvent()')
search.dispatchEvent(new Event('input'))
console.log('Après dispatchEvent()')L’écouteur s’exécute pendant dispatchEvent(), avant que le code continue. Si vous tapez quelque chose dans le champ de l’aperçu, isTrusted vaudra true, car l’événement sera déclenché par l’utilisateur.
const leave = document.querySelector('#leave')
let unsavedChanges = true
leave.addEventListener('lesson:leave', (event) => {
if (unsavedChanges) event.preventDefault()
})
function tryLeave() {
const allowed = leave.dispatchEvent(new CustomEvent('lesson:leave', { cancelable: true }))
console.log(allowed ? 'Je quitte la leçon' : 'Enregistrez d’abord vos modifications')
}
tryLeave()
unsavedChanges = false
tryLeave()const list = document.querySelector('#list')
const item = document.querySelector('#item')
list.addEventListener('task:done', () => console.log('Liste : tâche terminée'))
item.dispatchEvent(new CustomEvent('task:done'))
console.log('Sans bubbles, la liste n’a rien affiché')
item.dispatchEvent(new CustomEvent('task:done', { bubbles: true }))Compatibilité des navigateurs
#Largement disponible
Fonctionne dans tous les navigateurs modernes, y compris sur mobile. Vous pouvez l’utiliser sans crainte.
- Chrome
- Edge
- Firefox
- Safari
Bonnes pratiques
#- Écrivez les noms de vos propres événements en minuscules, avec un préfixe, par ex.
"cart:add". Vous éviterez ainsi toute collision avec les événements intégrés du navigateur. - Si l’événement doit atteindre les parents (par ex. un écouteur sur
document), définissezbubbles: true. Par défaut, il n’atteint que l’élément sur lequel il a été déclenché. - Passez les données dans le champ
detailde l’objetCustomEvent. Ajouter vos propres propriétés à unEventordinaire est moins lisible.
Entrées associées
#- EventTarget.addEventListener()Enregistre une fonction appelée à chaque fois qu’un événement se produit sur un élément, par ex. un clic.
- EventTarget.removeEventListener()Détache une fonction de gestion d’événement ajoutée plus tôt avec addEventListener(). Exige la même fonction et le même type d’événement.
- Event.preventDefault()Bloque l’action par défaut du navigateur pour un événement, par ex. l’envoi d’un formulaire ou le suivi d’un lien.
- Event.targetL’élément sur lequel l’événement s’est réellement produit, par ex. le bouton cliqué à l’intérieur d’une liste.
Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.