Eventi dei componenti ​

Si assume che tu abbia già letto le Basi dei componenti. Leggi prima quello se sei nuovo al concetto di componente.

Emettere ed ascoltare eventi ​

Un componente può emettere eventi personalizzati direttamente nelle espressioni del template (ad esempio, in un listener v-on) utilizzando il metodo integrato $emit:

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

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

Il genitore può poi ascoltarlo utilizzando v-on:

<MyComponent @nome-evento="callback" />

Anche il modificatore .once è supportato sui listener degli eventi del componente:

<MyComponent @nome-evento.once="callback" />

Come i componenti e le props, i nomi degli eventi forniscono una trasformazione automatica delle maiuscole e minuscole. Nota che abbiamo emesso un evento in stile camelCase, ma possiamo ascoltarlo usando un listener in stile kebab-case nel genitore. Come per la gestione delle maiuscole delle props, consigliamo di utilizzare listener degli eventi in stile kebab-case nei template.

Argomenti degli Eventi ​

A volte è utile emettere un valore specifico con un evento. Ad esempio, potremmo voler far sì che il componente <BlogPost> sia responsabile di quanto ingrandire il testo. In questi casi, possiamo passare argomenti aggiuntivi a $emit per fornire questo valore:

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

Quindi, quando ascoltiamo l'evento nel genitore, possiamo utilizzare una arrow function come listener, che ci consente di accedere all'argomento dell'evento:

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

Oppure, se l'handler dell'evento è un metodo:

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

Allora il valore sarà passato come primo parametro di quel metodo:

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

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

Dichiarare eventi emessi ​

Un componente può dichiarare esplicitamente gli eventi che emetterà utilizzando la macrodefineEmits() opzione 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'opzione emits supporta anche una sintassi ad oggetto, che ci consente di eseguire la convalida a runtime del payload degli eventi emessi:

<script setup>
const emit = defineEmits({
  submit(payload) {
    // restituisci `true` o `false` per indicare
    // il superamento / fallimento della convalida
  }
})
</script>

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

export default {
  emits: {
    submit(payload) {
      // restituisci `true` o `false` per indicare
      // il superamento / fallimento della convalida
    }
  }
}

Anche se opzionali, è consigliabile definire tutti gli eventi emessi per documentare meglio come dovrebbe funzionare un componente. Inoltre, consente a Vue di escludere gli ascoltatori noti dagli attributi fallthrough, evitando casi limite causati dagli eventi del DOM inviati manualmente da codice di terze parti.

Convalida degli eventi ​

Analogamente alla convalida del tipo di prop, un evento emesso può essere convalidato se è definito con la sintassi dell'oggetto anziché con la sintassi dell'array.

Per aggiungere la convalida, all'evento viene assegnata una funzione che riceve gli argomenti passati alla chiamata di this.$emitemit e restituisce un valore booleano per indicare se l'evento è valido o meno.

<script setup>
const emit = defineEmits({
  // Nessuna validazione
  click: null,

  // Validazione sull'evento submit
  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: {
    // Nessuna validazione
    click: null,

    // Validazione sull'evento submit
    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 })
    }
  }
}