Vue.js

# Manipulação de Eventos

Aprenda como manipular eventos em uma aula gratuita da Vue School

# Escutando Eventos

Podemos usar a diretiva v-on, que normalmente abreviamos para o símbolo @, para escutar eventos do DOM e rodar algum JavaScript quando tal evento for disparado. A maneira de usar seria v-on:click="nomeDoMétodo" ou com o atalho, @click="nomeDoMétodo"

Por exemplo:

<div id="basic-event">
  <button @click="counter += 1">Adicionar 1</button>
  <p>O botão acima foi clicado {{counter}} vezes.</p>
</div>
1
2
3
4
Vue.createApp({
  data() {
    return {
      counter: 0
    }
  }
}).mount('#basic-event')
1
2
3
4
5
6
7

Resultado:

Veja o exemplo Exemplo básico de manipulação de eventos por vuejs-br (@vuejs-br) no CodePen.

# Métodos em Manipuladores

A lógica para muitos manipuladores de evento será mais complexa, portanto, manter diretamente código JavaScript no valor do atributo v-on não é viável. É por isso que v-on também pode aceitar o nome de um método que você gostaria de chamar.

Por Exemplo:

<div id="event-with-method">
  <!-- `greet` é o nome de um método definido abaixo -->
  <button @click="greet">Cumprimentar</button>
</div>
1
2
3
4
Vue.createApp({
  data() {
    return {
      name: 'Vue.js'
    }
  },
  methods: {
    greet(event) {
      // `this` dentro de métodos aponta para a atual instância Vue ativa
      alert('Olá ' + this.name + '!')
      // `event` é o evento DOM nativo
      if (event) {
        alert(event.target.tagName)
      }
    }
  }
}).mount('#event-with-method')
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Resultado:

Veja o exemplo Exemplo de manipulação de eventos com um método por vuejs-br (@vuejs-br) no CodePen.

# Chamada Direta de Métodos

Em vez de interligar o evento diretamente ao nome de um método, também podemos chamar métodos diretamente com uma instrução JavaScript:

<div id="inline-handler">
  <button @click="say('oi')">Diga oi</button>
  <button @click="say('tchau')">Diga tchau</button>
</div>
1
2
3
4
Vue.createApp({
  methods: {
    say(message) {
      alert(message)
    }
  }
}).mount('#inline-handler')
1
2
3
4
5
6
7

Resultado:

Veja o exemplo Exemplo de evento com chamada direta de métodoo por vuejs-br (@vuejs-br) no CodePen.

Às vezes, também precisamos acessar o evento original do DOM em um manipulador. Você pode passá-lo à um método usando a variável especial $event:

<button @click="warn('O formulário ainda não pode ser enviado.', $event)">
  Enviar
</button>
1
2
3
// ...
methods: {
  warn(message, event) {
    // agora temos acesso ao evento nativo
    if (event) {
      event.preventDefault()
    }
    alert(message)
  }
}
1
2
3
4
5
6
7
8
9
10

# Múltiplos Manipuladores de Eventos

Você pode ter vários métodos em um manipulador de eventos separados por vírgula, desta forma:

<!-- ambos one() e two() serão executados no clique do botão -->
<button @click="one($event), two($event)">
  Enviar
</button>
1
2
3
4
// ...
methods: {
  one(event) {
    // lógica do primeiro manipulador...
  },
  two(event) {
    // lógica do segundo manipulador...
  }
}
1
2
3
4
5
6
7
8
9

# Modificadores de Evento

É muito comum precisar chamar event.preventDefault() ou event.stopPropagation() em manipuladores de eventos. Embora possamos fazer isto facilmente dentro de métodos, seria melhor se os métodos pudessem lidar apenas com a lógica dos dados, em vez de ter que lidar com detalhes de eventos DOM.

Para resolver esse problema, Vue fornece modificadores de evento para v-on. É só se lembrar que modificadores são sufixos da diretiva, denotados por um ponto.

  • .stop
  • .prevent
  • .capture
  • .self
  • .once
  • .passive
<!-- a propagação do evento click será interrompida -->
<a @click.stop="doThis"></a>

<!-- o evento submit deixará de recarregar a página -->
<form @submit.prevent="onSubmit"></form>

<!-- modificadores podem ser encadeados -->
<a @click.stop.prevent="doThat"></a>

<!-- é possível utilizar apenas o modificador -->
<form @submit.prevent></form>

<!-- usar modo de captura ao adicionar o evento -->
<!-- ou seja, um evento em um elemento interno é tratado aqui antes de ser tratado por aquele elemento -->
<div @click.capture="doThis">...</div>

<!-- só aciona o manipulador se event.target é o próprio elemento -->
<!-- isto é, não aciona a partir de um elemento filho -->
<div @click.self="doThat">...</div>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Nota

A ordem importa ao utilizar modificadores pois o código relevante é gerado na mesma ordem. Desta forma, @click.prevent.self prevenirá a ação padrão do clique no próprio elemento e seus filhos, enquanto @click.self.prevent prevenirá apenas a ação padrão de cliques no próprio elemento.

<!-- o evento click será disparado apenas uma vez -->
<a @click.once="doThis"></a>
1
2

Diferente dos outros modificadores, que são exclusivos para eventos nativos, o modificador .once também pode ser usado em eventos de componentes. Se você ainda não leu sobre componentes, não se preocupe com isso neste momento.

Vue também oferece o modificador .passive, correspondendo à opção passive do addEventListener (opens new window).

<!-- o comportamento padrão do evento _scroll_ (rolar) acontecerá -->
<!-- imediatamente, ao invés de aguardar `onScroll` completar   -->
<!-- para descobrir se ele chama `event.preventDefault()`       -->
<div @scroll.passive="onScroll">...</div>
1
2
3
4

O .passive é especialmente útil para otimizar desempenho em dispositivos móveis.

Nota

Não use .passive e .prevent juntos, pois .prevent será ignorado e seu navegador provavelmente exibirá um aviso. Lembre-se, .passive comunica ao navegador que você não quer prevenir o comportamento padrão do evento.

# Modificadores de Teclado

Quando escutamos eventos do teclado, precisamos muitas vezes verificar a ocorrência de teclas específicas. O Vue também permite a adição de modificadores v-on ou @ ao escutar eventos de teclado:

<!-- só chama `vm.submit()` quando o `key` é `Enter` -->
<input @keyup.enter="submit" />
1
2

Você pode usar diretamente qualquer nome de tecla válido exposto via KeyboardEvent.key (opens new window) como modificadores, convertendo-os em kebab-case.

<input @keyup.page-down="onPageDown" />
1

No exemplo acima, o manipulador só será chamado se $event.key for igual a 'PageDown'.

# Apelidos de Teclas

Vue fornece apelidos para os códigos de teclas mais comuns:

  • .enter
  • .tab
  • .delete (captura tanto "Delete" quanto "Backspace")
  • .esc
  • .space
  • .up
  • .down
  • .left
  • .right

# Modificadores de Teclas do Sistema

Você pode utilizar os seguintes modificadores para acionar eventos de mouse ou teclado apenas quando o modificador correspondente estiver pressionado:

  • .ctrl
  • .alt
  • .shift
  • .meta

Nota

Nos teclados Macintosh, meta é a tecla de comando (⌘). Nos teclados Windows, meta é a tecla Windows (⊞). Nos teclados Sun Microsystems, meta é marcada como um diamante sólido (◆). Em alguns teclados, especificamente em máquinas MIT e Lisp e suas sucessoras, assim como o teclado Knight e teclados space-cadet, meta é marcada como “META”. Em teclados Symbolics, meta é marcada como “META” ou “Meta”.

Por exemplo:

<!-- Alt + Enter -->
<input @keyup.alt.enter="clear" />

<!-- Ctrl + Click -->
<div @click.ctrl="doSomething">Faça alguma coisa</div>
1
2
3
4
5

TIP

Teclas modificadoras são diferentes de teclas comuns, e quando utilizadas com eventos keyup, precisam estar pressionadas quando o evento é emitido. Em outras palavras, keyup.ctrl só vai disparar se você soltar alguma tecla enquanto ainda estiver segurando ctrl. E não irá disparar se você soltar a tecla ctrl sozinha.

# Modificador .exact

O modificador .exact permite controlar a exata combinação de modificadores de sistema que deve ser pressionada para que o gatilho dispare.

<!-- dispara mesmo se Alt ou Shift também estiverem pressionados -->
<button @click.ctrl="onClick">A</button>

<!-- dispara somente quando Ctrl (e nenhuma outra tecla) for pressionado -->
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- dispara somente se não houverem teclas do sistema pressionadas -->
<button @click.exact="onClick">A</button>
1
2
3
4
5
6
7
8

# Modificadores dos Botões do Mouse

  • .left
  • .right
  • .middle

Estes modificadores restringem o manipulador à eventos disparados por um botão específico do mouse.

# Por Que Escutas no HTML?

Você pode estar pensando que esta abordagem de escutas de evento viola as boas e velhas práticas sobre "separação de responsabilidades". Fique tranquilo - como todas as funções de manipuladores e expressões Vue são estritamente ligadas ao ViewModel que está manipulando o modo de exibição atual, essa abordagem não causará qualquer dificuldade de manutenção. Na verdade, há vários benefícios em usar v-on ou @:

  1. É mais fácil localizar as implementações de função de manipulador dentro de seu código JS percorrendo o template HTML.

  2. Como você não tem que manualmente anexar escutas à eventos em JS, seu código de ViewModel pode conter apenas a lógica pura e ser livre de manipulação do DOM. Isto torna mais fácil de testar.

  3. Quando um ViewModel é destruído, todas as escutas de eventos são removidas automaticamente. Você não precisa se preocupar em removê-las explicitamente.

← Interligações em Formulários →