Manipulação de Evento ​

Ouvindo Eventos ​

Nós podemos utilizar a diretiva v-on, que normalmente abreviamos para o símbolo @, para ouvir os eventos do DOM e executar algum código de JavaScript quando são acionadas. A utilização seria v-on:click="handler" ou com o atalho, @click="handler".

O valor de handler (manipulador) pode ser um dos seguintes:

1. Manipuladores em linha: O código de JavaScript em linha pode ser executado quando o evento é acionado (semelhante ao atributo onclick nativo).

2. Manipuladores de método: O nome da propriedade ou o caminho que aponta para um método definido no componente.

Manipuladores Em Linha ​

Os manipuladores em linha normalmente são utilizados em casos simples, por exemplo:

const count = ref(0)

data() {
  return {
    count: 0
  }
}

<button @click="count++">Add 1</button>
<p>Count is: {{ count }}</p>

Manipuladores de Método ​

A lógica para muitos manipuladores de evento será mais complexa, e provavelmente não é viável com manipuladores em linha. É por isto que a v-on também pode aceitar o nome ou caminho de um método do componente que gostarias de chamar.

Por exemplo:

const name = ref('Vue.js')

function greet(event) {
  alert(`Hello ${name.value}!`)
  // `event` é um evento de DOM nativo
  if (event) {
    alert(event.target.tagName)
  }
}

data() {
  return {
    name: 'Vue.js'
  }
},
methods: {
  greet(event) {
    // `this` dentro de métodos aponta para atual instância ativa
    alert(`Hello ${this.name}!`)
    // `event` é um evento de DOM nativo
    if (event) {
      alert(event.target.tagName)
    }
  }
}

<!-- `greet` é o nome do método definido acima -->
<button @click="greet">Greet</button>

Um manipulador de método recebe automaticamente o objeto de evento de DOM nativo que o aciona - no exemplo acima, somos capazes de acessar o elemento despachando o evento através de event.target.tagName.

Método vs. Deteção Em Linha ​

O compilador do modelo de marcação deteta os manipuladores de método verificando se o valor de sequência de caracteres de v-on é um identificador de JavaScript válido ou caminho de acesso de propriedade. Por exemplo, foo, foo.bar e foo['bar'] são tratados como manipuladores de métodos, enquanto foo() e count++ são tratados como manipuladores em linha.

Chamando Métodos em Manipuladores Em Linha ​

No lugar de vincular diretamente para um nome de método, também podemos chamar métodos em um manipulador em linha. Isto permite-nos passar os argumentos personalizados do método ao invés do evento nativo:

function say(message) {
  alert(message)
}

methods: {
  say(message) {
    alert(message)
  }
}

<button @click="say('hello')">Say hello</button>
<button @click="say('bye')">Say bye</button>

Acessando Argumento de Evento nos Manipuladores Em Linha ​

Algumas vezes também precisamos acessar o evento de DOM original em um manipulador em linha. Tu podes passá-lo para um método utilizando variável especial $event, ou utilizar uma função em flecha em linha:

<!-- utilizando a variável especial $event -->
<button @click="warn('Form cannot be submitted yet.', $event)">
  Submit
</button>

<!-- utilizando a função em flecha em linha -->
<button @click="(event) => warn('Form cannot be submitted yet.', event)">
  Submit
</button>

function warn(message, event) {
  // agore temos acesso ao evento nativo
  if (event) {
    event.preventDefault()
  }
  alert(message)
}

methods: {
  warn(message, event) {
    // agore temos acesso ao evento nativo
    if (event) {
      event.preventDefault()
    }
    alert(message)
  }
}

Modificadores de Evento ​

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

Para tratar este problema, a Vue fornece modificadores de evento para v-on. Recorda-te de que os modificadores são nomes especiais depois do nome do evento denotados por um ponto.

• .stop
• .prevent
• .self
• .capture
• .once
• .passive

<!-- o propagação do evento de clique será interrompida -->
<a @click.stop="doThis"></a>

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

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

<!-- apenas o modificador -->
<form @submit.prevent></form>

<!-- apenas aciona o manipulador se `event.target` for o próprio elemento -->
<!-- por exemplo, não um elemento filho -->
<div @click.self="doThat">...</div>

Os modificadores .capture, .once, e .passive refletem as opções do método addEventListener nativo:

<!-- utilize o modo de captura quando estiveres adicionando o ouvinte de evento -->
<!-- por exemplo, um evento mirando um elemento interno é manipulado aqui antes de ser manipulado por aquele elemento -->
<div @click.capture="doThis">...</div>

<!-- o evento de clique será acionado no máximo uma vez -->
<a @click.once="doThis"></a>

<!-- o comportamento padrão do evento de deslocamento (deslocando) acontecerá -->
<!-- imediatamente, no lugar de esperar o `onScroll` terminar  -->
<!-- neste caso ele contém `event.preventDefault()`                -->
<div @scroll.passive="onScroll">...</div>

O modificador .passive é normalmente utilizado com o ouvintes de evento de toque para melhorar o desempenho nos dispositivos móveis.

Modificadores de Tecla ​

Quando estivermos ouvindo por eventos teclado, precisamos com frequência verificar por teclas especificas. A Vue permite a adição de modificadores de tecla para v-on ou @ quando estivermos ouvindo por eventos de tecla:

<!-- só chama `vm.submit()` quando a `tecla` pressionada for `Enter` -->
<input @keyup.enter="submit" />

Tu podes utilizar diretamente quaisquer nomes de tecla válidos expostos através de KeyboardEvent.key como modificadores convertendo-os para "kebab-case".

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

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

Pseudónimos de Tecla ​

A Vue fornece pseudónimos para as teclas mais comummente utilizadas:

• .enter
• .tab
• .delete (captura ambas teclas "Delete" e "Backspace")
• .esc
• .space
• .up
• .down
• .left
• .right

Teclas Modificadoras do Sistema ​

Tu podes utilizar os seguintes modificadores para acionares ouvintes de eventos de teclado ou rato apenas quando a tecla modificadora correspondente for pressionada:

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

Por exemplo:

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

<!-- Ctrl + Click -->
<div @click.ctrl="doSomething">Do something</div>

O Modificador .exact ​

O modificador .exact permite o controlo da combinação exata de modificadores de sistema necessária para acionar um evento.

<!-- isto disparará mesmo se Alt ou Shift também for pressionado -->
<button @click.ctrl="onClick">A</button>

<!-- isto só disparará quando Ctrl e não outras teclas for pressionado -->
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- isto só disparará quando nenhum dos modificadores do sistema for pressionado -->
<button @click.exact="onClick">A</button>

Modificadores de Botão de Rato ​

• .left
• .right
• .middle

Estes modificadores limitam o manipulador para os eventos acionados por um botão de rato especifico.