Eventos de Componente ​

Esta página asume que ya has leído los Fundamentos de Componentes. Léela primero si eres nuevo en los componentes.

Emitir y Escuchar Eventos ​

Un componente puede emitir eventos personalizados directamente en expresiones de template (por ejemplo, en un handler de v-on) usando el método $emit incorporado:

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

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

El componente padre puede entonces escucharlo usando v-on:

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

El modificador .once también es compatible con los listeners de eventos de componente:

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

Al igual que los componentes y los props, los nombres de eventos proporcionan una transformación de mayúsculas y minúsculas automática. Observa que emitimos un evento en camelCase, pero podemos escucharlo usando un listener en kebab-cased en el padre. Al igual que con el uso de mayúsculas/minúsculas en props, recomendamos usar listeners de eventos en kebab-cased en los templates.

Argumentos de Evento ​

A veces es útil emitir un valor específico con un evento. Por ejemplo, es posible que deseemos que el componente <BlogPost> sea el encargado de cuánto debe agrandar el texto. En esos casos, podemos pasar argumentos adicionales a $emit para proporcionar este valor:

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

Luego, cuando escuchamos el evento en el componente padre, podemos usar una función de flecha en línea como listener, lo que nos permite acceder al argumento del evento:

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

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

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

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

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

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

Declarar Eventos Emitidos ​

Un componente puede declarar explícitamente los eventos que emitirá usando 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 la macro defineEmits() también admiten una sintaxis de objeto. Si usas TypeScript, puedes tipar los argumentos, lo que nos permite realizar la validación en tiempo de ejecución de la carga útil de los eventos emitidos:

<script setup lang="ts">
const emit = defineEmits({
  submit(payload: { email: string; password: string }) {
    // devuelve `true` o `false` para indicar
    // si la validación pasó / falló
  }
})
</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
      // si la validación pasó / falló
    }
  }
}

Aunque es opcional, se recomienda definir todos los eventos emitidos para documentar mejor cómo debe funcionar un componente. También permite a Vue excluir listeners conocidos de los atributos de fallthrough, evitando casos extremos causados por eventos del DOM enviados manualmente por código de terceros.

Validación de Eventos ​

Similar a la validación de tipo de prop, un evento emitido puede validarse si se define con la sintaxis de objeto en lugar de la sintaxis de array.

Para agregar validación, al evento se le asigna una función que recibe los argumentos pasados a la llamada 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 evento submit
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('¡Carga útil de evento submit no válida!')
      return false
    }
  }
})

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

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

    // Validar evento submit
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('¡Carga útil de evento submit no válida!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}