Les événements de composant ​

Cette page suppose que vous avez déjà lu les principes fondamentaux des composants. Lisez-les d'abord si vous débutez avec les composants.

Émettre et écouter des événements ​

Un composant peut émettre des événements personnalisés directement à partir du template (par exemple, dans un gestionnaire d'événement v-on) à l'aide de la méthode native $emit :

<!-- MyComponent -->
<button @click="$emit('someEvent')">click me</button>

export default {
  methods: {
    submit() {
      this.$emit('someEvent')
    }
  }
}

Le composant parent peut alors l'écouter en utilisant v-on :

<MyComponent @some-event="callback" />

Le modificateur .once est également pris en charge sur les écouteurs d'événements de composants :

<MyComponent @some-event.once="callback" />

Comme les composants et les props, les noms d'événements fournissent une transformation de casse automatique. Notez que nous avons émis un événement camelCase, mais que nous pouvons l'écouter à l'aide d'un écouteur kebab-case dans le parent. Comme pour la casse des props, nous vous recommandons d'utiliser des noms d'écouteurs d'événement au format kebab-case dans les templates.

Arguments d'événement ​

Il est parfois utile d'émettre une valeur spécifique avec un événement. Par exemple, nous pouvons vouloir que le composant <BlogPost> soit en charge d'agrandir plus ou moins le texte. Dans ces cas, nous pouvons passer des arguments supplémentaires à $emit pour fournir cette valeur :

<button @click="$emit('increaseBy', 1)">
  Increase by 1
</button>

Ensuite, lorsque nous écoutons l'événement dans le composant parent, nous pouvons utiliser une fonction fléchée comme écouteur, ce qui nous permet d'accéder à l'argument de l'événement :

<MyButton @increase-by="(n) => count += n" />

Ou, si le gestionnaire d'événements est une méthode :

<MyButton @increase-by="increaseCount" />

Ensuite, la valeur sera transmise comme premier paramètre de cette méthode :

methods: {
  increaseCount(n) {
    this.count += n
  }
}

function increaseCount(n) {
  count.value += n
}

Déclaration des événements émis ​

Les événements émis peuvent être explicitement déclarés sur le composant via la macro defineEmits()l'option emits :

<script setup>
defineEmits(['inFocus', 'submit'])
</script>

<script setup>
const emit = defineEmits(['inFocus', 'submit'])

function buttonClick() {
  emit('submit')
}
</script>

export default {
  emits: ['inFocus', 'submit'],
  setup(props, ctx) {
    ctx.emit('submit')
  }
}

export default {
  emits: ['inFocus', 'submit'],
  setup(props, { emit }) {
    emit('submit')
  }
}

export default {
  emits: ['inFocus', 'submit']
}

L'option emits et la macro defineEmits() supportent également une syntaxe avec un objet. Si vous utilisez TypeScript, vous pouvez utiliser les arguments, ce qui nous permet d'effectuer une validation à l'exécution du contenu des événements émis :

<script setup lang="ts">
const emit = defineEmits({
  submit(payload: { email: string, password: string }) {
    // renvoie `true` ou `false` pour indiquer
    // que la validation a réussi/échoué
  }
})
</script>

<script setup lang="ts">
const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()
</script>

export default {
  emits: {
    submit(payload: { email: string, password: string }) {
      // renvoie `true` ou `false` pour indiquer
      // que la validation a réussi/échoué
    }
  }
}

Bien que facultatif, il est recommandé de définir tous les événements émis afin de mieux documenter le fonctionnement d'un composant. Cela permet également à Vue d'exclure les écouteurs connus des attributs implicitement déclarés (fallthrough attributes), évitant ainsi les problèmes liés aux cas à la marge causés par des événements DOM envoyés manuellement par du code tiers.

Validation des événements ​

Semblable à la validation de type de prop, un événement émis peut être validé s'il est défini avec la syntaxe utilisant un objet au lieu d'un tableau.

Pour ajouter une validation, l'événement se voit attribuer une fonction qui reçoit les arguments passés à l'appel de this.$emitemit et renvoie un booléen pour indiquer si l'événement est valide ou non.

<script setup>
const emit = defineEmits({
  // Pas de validation
  click: null,

  // Validation de l'événement soumis
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Invalid submit event payload!')
      return false
    }
  }
})

function submitForm(email, password) {
  emit('submit', { email, password })
}
</script>

export default {
  emits: {
    // Pas de validation
    click: null,

    // Validation de l'événement soumis
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Invalid submit event payload!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}