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 :

const count = ref(0)

data() {
  return {
    count: 0
  }
}

<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 :

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)
  }
}

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)
    }
  }
}

<!-- `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.

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 :

function say(message) {
  alert(message)
}

methods: {
  say(message) {
    alert(message)
  }
}

<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 :

<!-- 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>

function warn(message, event) {
  // nous avons maintenant accès à l'événement natif
  if (event) {
    event.preventDefault()
  }
  alert(message)
}

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

<!-- 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>

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

<!-- utiliser le mode capture lors de l'ajout de l'écouteur d'événement -->
<!-- c'est-à-dire qu'un événement ciblant un élément interne 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 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.

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 :

<!-- 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.

<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

Par exemple :

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

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

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.

<!-- 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.

Notez cependant que les noms des modificateurs .left, .right et .middle sont basés sur la disposition typique d'une souris pour droitier, mais représentent en fait les déclencheurs d'événements des dispositifs de pointage "principal", "secondaire" et "auxiliaire", respectivement, et non les boutons physiques réels. Ainsi, pour une souris de gaucher, le bouton "principal" peut être physiquement celui de droite, mais il déclenchera le gestionnaire du modificateur .left. Ou bien un trackpad peut déclencher le gestionnaire .left en tapant avec un doigt, le gestionnaire .right en tapant avec deux doigts, et le gestionnaire .middle en tapant avec trois doigts. De même, d'autres dispositifs et sources d'événements générant des événements "souris" peuvent avoir des modes de déclenchement qui ne sont pas liés à "left" et "right".