Eventos de los Componentes ​

Esta página supone que ya has leído los Fundamentos de los Componentes. Léelo primero si eres nuevo en el tema de componentes.

Emitiendo y Escuchando Eventos ​

Un componente puede emitir eventos personalizados directamente en las expresiones de la plantilla (por ejemplo, en un manejador v-on) utilizando el método incorporado $emit:

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

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

El padre puede entonces escucharlo usando v-on:

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

El modificador .once también es compatible con los escuchadores de eventos de los componentes:

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

Al igual que los componentes y props, los nombres de eventos proporcionan una transformación automática de mayúsculas y minúsculas. Observa que emitimos un evento camelCase, pero podemos escucharlo usando un listener kebab-cased en el padre. Como en el caso de la Nomenclatura de las Props, recomendamos utilizar escuchas de eventos con mayúsculas en las plantillas.

Argumentos del Evento ​

A veces es útil emitir un valor específico con un evento. Por ejemplo, podemos querer que el componente <BlogPost> se encargue de cuánto ampliar el texto. En esos casos, podemos pasar argumentos extra a $emit para proporcionar este valor:

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

Así, cuando escuchamos el evento en el padre, podemos utilizar una función de flecha en línea como oyente, lo que nos permite acceder al argumento del evento:

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

O, si el manejador del evento es un método:

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

Entonces el valor se pasará como primer parámetro de ese método:

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

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

Declarando Eventos Emitidos ​

Un componente puede declarar explícitamente los eventos que emitirá utilizando la macro defineEmits()opción 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']
}

La opción emits y el macro defineEmits() también admiten una sintaxis de objeto. Si utilizas TypeScript puedes tipar argumentos, lo que nos permite realizar una validación en tiempo de ejecución del payload de los eventos emitidos:

<script setup>
const emit = defineEmits({
  submit(payload: { email: string; password: string }) {
    // devuelve `true` o `false` para indicar
    // que la validación ha pasado / no ha pasado
  }
})
</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 }) {
      // devuelve `true` o `false` para indicar
      // que la validación ha pasado / no ha pasado
    }
  }
}

Aunque es opcional, se recomienda definir todos los eventos emitidos para documentar mejor cómo debe funcionar un componente. Esto también permite a Vue excluir a los escuchadores conocidos desde los atributos fallthrough, evitando situaciones críticas causadas por eventos del DOM enviados manualmente por código de terceros.

Validación de Eventos ​

De forma similar a la validación del tipo de props, un evento emitido puede ser validado si se define con la sintaxis de objeto en lugar de la sintaxis de array.

Para agregar la validación, se asigna al evento una función que recibe los argumentos pasados a la invocación de this.$emitemit y devuelve un booleano para indicar si el evento es válido o no.

<script setup>
const emit = defineEmits({
  // Sin validación
  click: null,

  // Validar el evento submit
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('¡Payload del evento submit inválido!')
      return false
    }
  }
})

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

export default {
  emits: {
    // Sin validación
    click: null,

    // Validar el evento submit
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('¡Payload del evento submit inválido!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}

Eventos como Props ​

También puedes declarar y pasar eventos como props, prefijando el nombre del evento en mayúsculas con on.

Usar props.onEvent tiene un comportamiento diferente que usar emit('event'), ya que el primero sólo manejará el listener basado en la propiedad (ya sea @event o :on-event)

Debido a esto, se recomienda usar emit('event') en lugar de props.onEvent cuando se emitan eventos.