Passer au contenu

Gestion d'événement

Écouter des événements

Nous pouvons utiliser la directive v-on, que nous raccourcissons généralement par le symbole @, pour écouter les événements DOM et exécuter du JavaScript lorsqu'ils sont déclenchés. L'utilisation serait alors v-on:click="handler" ou avec le raccourci, @click="handler".

La valeur du gestionnaire peut alors prendre l'une des formes suivantes :

  1. Gestionnaires en ligne : Du JavaScript inline qui sera exécuté lorsque l'événement sera déclenché (similaire à l'attribut natif onclick).

  2. Méthodes gestionnaires : Un nom ou un chemin de propriété qui pointe vers une méthode définie sur le composant.

Gestionnaires en ligne

Les gestionnaires inline sont généralement utilisés dans des cas simples, par exemple :

js
const count = ref(0)
js
data() {
  return {
    count: 0
  }
}
template
<button @click="count++">Add 1</button>
<p>Count is: {{ count }}</p>

Méthodes gestionnaires

Cependant, pour de nombreux gestionnaires d'événements, la logique sera plus complexe et ne sera probablement pas réalisable avec des gestionnaires en ligne. C'est pourquoi v-on peut également accepter le nom ou le chemin d'une méthode de composant que vous souhaitez appeler.

Par exemple :

js
const name = ref('Vue.js')

function greet(event) {
  alert(`Hello ${name.value}!`)
  // `event` est l'événement natif du DOM
  if (event) {
    alert(event.target.tagName)
  }
}
js
data() {
  return {
    name: 'Vue.js'
  }
},
methods: {
  greet(event) {
    // `this` à l'intérieur des méthodes pointe sur l'instance actuellement active
    alert(`Hello ${this.name}!`)
    // `event` est l'événement natif du DOM
    if (event) {
      alert(event.target.tagName)
    }
  }
}
template
<!-- `greet` est le nom de la méthode définie plus haut -->
<button @click="greet">Greet</button>

Une méthode gestionnaire reçoit automatiquement l'objet événement natif du DOM qui la déclenche - dans l'exemple ci-dessus, nous pouvons accéder à l'élément qui envoie l'événement via event.target.tagName.

Voir aussi : Typing Event Handlers

Méthodes vs. Détection en ligne

Le compilateur de templates détecte les méthodes gestionnaires en vérifiant si la valeur en chaîne de caractères v-on est un identifiant JavaScript ou un chemin d'accès de propriété valide. Par exemple, foo, foo.bar et foo['bar'] sont traités comme des méthodes gestionnaires, tandis que foo() et count++ sont traités comme des gestionnaires en ligne.

Appeler des méthodes dans les gestionnaires en ligne

Au lieu de se lier directement à un nom de méthode, nous pouvons également appeler des méthodes dans un gestionnaire en ligne. Cela nous permet de passer à la méthode des arguments personnalisés au lieu de l'événement natif :

js
function say(message) {
  alert(message)
}
js
methods: {
  say(message) {
    alert(message)
  }
}
template
<button @click="say('hello')">Say hello</button>
<button @click="say('bye')">Say bye</button>

Accéder à l'argument de l'événement dans les gestionnaires en ligne

Parfois, nous avons aussi besoin d'accéder à l'événement original du DOM dans un gestionnaire en ligne. Vous pouvez le passer dans une méthode en utilisant la variable spéciale $event, ou utiliser une fonction fléchée en ligne :

template
<!-- en utilisant la variable spéciale $event  -->
<button @click="warn('Form cannot be submitted yet.', $event)">
  Submit
</button>

<!-- en utilisant une fonction fléchée en ligne -->
<button @click="(event) => warn('Form cannot be submitted yet.', event)">
  Submit
</button>
js
function warn(message, event) {
  // nous avons maintenant accès à l'événement natif
  if (event) {
    event.preventDefault()
  }
  alert(message)
}
js
methods: {
  warn(message, event) {
    // nous avons maintenant accès à l'événement natif
    if (event) {
      event.preventDefault()
    }
    alert(message)
  }
}

Modificateurs d'événements

Il est courant d'avoir besoin d'appeler event.preventDefault() ou event.stopPropagation() à l'intérieur des gestionnaires d'événements. Bien que nous puissions le faire facilement à l'intérieur des méthodes, il serait préférable que les méthodes puissent se focaliser exclusivement sur la logique des données plutôt qu'avoir à gérer les détails des événements du DOM.

Pour résoudre ce problème, Vue fournit des modificateurs d'événements pour v-on. Rappelons que les modificateurs sont des postfixes de directives désignés par un point.

  • .stop
  • .prevent
  • .self
  • .capture
  • .once
  • .passive
template
<!-- la propagation de l'événement clic va être arrêtée -->
<a @click.stop="doThis"></a>

<!-- l'événement submit ne va plus rafraîchir la page -->
<form @submit.prevent="onSubmit"></form>

<!-- les modificateurs peuvent être chaînés -->
<a @click.stop.prevent="doThat"></a>

<!-- seulement le modificateur -->
<form @submit.prevent></form>

<!-- ne déclenche le gestionnaire que si event.target est l'élément lui-même. -->
<!-- par exemple pas depuis un élément enfant -->
<div @click.self="doThat">...</div>

TIP

L'ordre est important lorsqu'on utilise des modificateurs car le code correspondant est généré dans le même ordre. De ce fait, utiliser @click.prevent.self empêchera l'action par défaut du clic sur l'élément lui-même et ses enfants, alors que @click.self.prevent empêchera seulement l'action par défaut de click sur l'élément lui-même.

Les modificateurs .capture, .once, et .passive imitent les options de la méthode native addEventListener:

template
<!-- utiliser le mode capture lorsque vous ajoutez l'écouteur d'événements -->
<!-- par exemple un événement visant un élément intérieur est traité ici avant d'être traité par cet élément -->
<div @click.capture="doThis">...</div>

<!-- l'événement clic sera déclenché au maximum une fois -->
<a @click.once="doThis"></a>

<!-- le comportement par défaut de l'élément de défilement (scrolling) aura lieu -->
<!-- immédiatement, au lieu d'attendre la fin de `onScroll`  -->
<!-- s'il contient `event.preventDefault()`                -->
<div @scroll.passive="onScroll">...</div>

Le modificateur .passive est généralement utilisé avec les écouteurs d'événements de touche pour améliorer les performances sur les périphériques mobiles.

TIP

N'utilisez pas .passive et .prevent ensemble, car .passive indique déjà au navigateur que vous n'avez pas l'intention d'empêcher le comportement par défaut de l'événement, et vous aurez probablement un avertissement du navigateur si vous le faites.

Modificateurs de touche

Lorsque nous écoutons des événements du clavier, nous avons souvent besoin de vérifier des touches spécifiques. Vue permet d'ajouter des modificateurs de touches pour v-on ou @ lors de l'écoute d'événements du clavier :

template
<!-- appelle `submit` seulement lorsque `key` est `Enter` -->
<input @keyup.enter="submit" />

Vous pouvez utiliser directement n'importe quel nom de touche exposé via KeyboardEvent.key comme des modificateurs en les convertissant en kebab-case.

template
<input @keyup.page-down="onPageDown" />

Dans l'exemple ci-dessus, le gestionnaire ne sera appelé que si $event.key est égal à 'PageDown'.

Alias de touche

Vue fournit des alias pour les touches les plus couramment utilisées :

  • .enter
  • .tab
  • .delete (capture à la fois les touches "Delete" et "Backspace")
  • .esc
  • .space
  • .up
  • .down
  • .left
  • .right

Touches de modification du système

Vous pouvez utiliser les modificateurs suivant pour déclencher des écouteurs d'événements de la souris ou du clavier seulement lorsque la touche modificatrice correspondante est pressée :

  • .ctrl
  • .alt
  • .shift
  • .meta

Note

Sur les claviers Macintosh, meta est la touche commande (⌘). Sur les claviers Windows, meta est la touche Windows (⊞). Sur les claviers Sun Microsystems, meta est marqué d'un diamant solide (◆). Sur certains claviers, en particulier les claviers MIT et ceux des machines Lisp et leurs successeurs, tels que le clavier Knight, le clavier space-cadet, meta est étiqueté "META". Sur les claviers Symbolics, meta est étiqueté "META" ou "Meta".

Par exemple :

template
<!-- Alt + Entrée -->
<input @keyup.alt.enter="clear" />

<!-- Ctrl + Clic -->
<div @click.ctrl="doSomething">Do something</div>

TIP

Notez que les touches modificatrices sont différentes des touches normales et que lorsqu'elles sont utilisées avec des événements keyup, elles doivent être appuyées lorsque l'événement est émis. En d'autres termes, keyup.ctrl ne se déclenchera que si vous relâchez une touche tout en maintenant la touche ctrl enfoncée. Il ne se déclenchera pas si vous relâchez la touche ctrl seulement.

Modificateur .exact

Le modificateur .exact permet le contrôle de la combinaison exacte de touches de modification du système requise pour déclencher un événement.

template
<!-- l'événement sera déclenché même si Alt ou Maj est également pressée -->
<button @click.ctrl="onClick">A</button>

<!-- l'événement ne sera déclenché que quand Ctrl est enfoncé sans autres touches -->
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- l'événement ne sera déclenché que lorsqu'aucune touche de modification du système n'est pressée -->
<button @click.exact="onClick">A</button>

Modificateurs des boutons de la souris

  • .left
  • .right
  • .middle

Ces modificateurs limitent le gestionnaire aux événements déclenchés par un bouton spécifique de la souris.

Gestion d'événementa chargé