Eventos de Componente ​

Esta página presume que já fizeste leitura dos Fundamentos de Componentes. Leia aquele primeiro se fores novo para os componentes.

Emitindo e Ouvindo Eventos ​

Um componente pode emitir eventos personalizados diretamente nas expressões de modelo de marcação (por exemplo, num manipulador de v-on) utilizando o método $emit embutido:

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

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

O componente pai pode então ouvi-lo utilizando a v-on:

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

O modificador .once também é suportado nos ouvintes de evento do componente:

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

Tal como os componentes e propriedades, os nomes de eventos fornecem uma transformação de caixa automática. Repara que nós emitimos um evento em "camelCase", mas podemos ouvir ele utilizando um ouvinte em "kebab-case" no componente pai. De acordo com a caixa dos caracteres das propriedades, recomendamos a utilização de ouvintes de evento em "kebab-case" nos modelos de marcação.

Argumentos de Evento ​

Algumas vezes é útil emitir um valor especifico com um evento. Por exemplo, podemos desejar que o componente <BlogPost> esteja encarregado do por quanto aumentar o texto. Naqueles casos, podemos passar argumentos adicionais para a $emit para fornecer este valor:

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

Então, quando ouvirmos o evento no componente pai, podemos utilizar uma função em flecha em linha como ouvinte, que permite-nos acessar o argumento do evento:

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

Ou, se o manipulador de evento for um método:

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

Então o valor será passado como primeiro parâmetro daquele método:

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

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

Declarando Eventos Emitidos ​

Um componente pode declarar explicitamente os eventos que ele emitirá usando a macro defineEmits()opção 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']
}

A opção emits também suporta uma sintaxe de objeto, que permite-nos realizar validação de tempo de execução da carga dos eventos emitidos:

<script setup>
const emit = defineEmits({
  submit(payload) {
    // retorna `true` ou `false` para indicar
    // que a validação passou ou falhou
  }
})
</script>

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

export default {
  emits: {
    submit(payload) {
      // retorna `true` ou `false` para indicar
      // que a validação passou ou falhou
    }
  }
}

Ainda que opção, é recomendado definir todos eventos emitidos em ordem para documentar melhor como um componente deveria funcionar. Também permite a Vue excluir ouvintes conhecidos dos atributos que caiem.

Validação de Eventos ​

Semelhante a validação de tipo de propriedade, um evento emitido pode ser validado se for definido com a sintaxe de objeto no lugar da sintaxe de arranjo.

Para adicionar a validação, o evento é atribuído à uma função que recebe os argumentos passados para chamada de this.$emitemit e retorna um booleano para indicar se o evento é válido ou não.

<script setup>
const emit = defineEmits({
  // Sem validação
  click: null,

  // Valida o 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: {
    // Sem validação
    click: null,

    // Valida o 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 })
    }
  }
}