Руководство

Обработка событий

Подписка на события

Чтобы подписаться на события DOM и выполнить JavaScript-код при их наступлении, примените директиву v-on.

Например:

<div id="example-1">
  <button v-on:click="counter += 1">+1</button>
  <p>Кнопка выше была нажата {{counter}} раз</p>
</div>
var example1 = new Vue({
  el: '#example-1',
  data: {
    counter: 0
  }
})

Результат:

Кнопка выше была нажата {{counter}} раз

Обработчики событий

Логика обработки события может быть довольно сложной, так что оставить весь JavaScript-код в значении атрибута v-on не всегда возможно. В этом случае v-on может принять и название метода, который вы хотите вызвать.

Например:

<div id="example-2">
  <!-- `greet` — это название метода, определённого ниже -->
  <button v-on:click="greet">Поприветствовать</button>
</div>
var example2 = new Vue({
  el: '#example-2',
  data: {
    name: 'Vue.js'
  },
  // определяйте методы в объекте `methods`
  methods: {
    greet: function (event) {
      // `this` внутри методов указывает на экземпляр Vue
      alert('Привет, ' + this.name + '!')
      // `event` — нативное событие DOM
      if (event) {
        alert(event.target.tagName)
      }
    }
  }
})

// вызывать методы можно и императивно
example2.greet() // => 'Привет, Vue.js!'

Результат:

Методы и inline-обработчики

Можно связаться с методом не по имени, а вызвав его в JavaScript-выражении:

<div id="example-3">
  <button v-on:click="say('hi')">Скажи hi</button>
  <button v-on:click="say('what')">Скажи what</button>
</div>
new Vue({
  el: '#example-3',
  methods: {
    say: function (message) {
      alert(message)
    }
  }
})

Результат:

Иногда и в inline-обработчиках, оказывается, необходим доступ к оригинальному событию DOM. Его можно передать в метод, используя специальную переменную $event:

<button v-on:click="warn('Форма пока что не может быть отправлена.', $event)">
  Отправить
</button>
// ...
methods: {
  warn: function (message, event) {
    // теперь у нас есть доступ к нативному событию
    if (event) event.preventDefault()
    alert(message)
  }
}

Модификаторы событий

Очень часто возникает необходимость вызвать event.preventDefault() или event.stopPropagation() в обработчике события. Хотя это легко можно сделать внутри метода, было бы лучше сохранить чистоту логики и абстрагироваться от деталей реализации событий DOM.

Для решения этой задачи Vue предлагает модификаторы событий для v-on. Напомним, что модификаторы директив указываются как постфиксы и отделяются точкой.

<!-- событие click не будет всплывать дальше -->
<a v-on:click.stop="doThis"></a>

<!-- событие submit больше не будет перезагружать страницу -->
<form v-on:submit.prevent="onSubmit"></form>

<!-- модификаторы можно объединять в цепочки -->
<a v-on:click.stop.prevent="doThat"></a>

<!-- и использовать без указания пользовательского обработчика -->
<form v-on:submit.prevent></form>

<!-- при добавлении слушателя события можно использовать capture mode -->
<!-- т.е. событие, нацеленное на внутренний элемент, обрабатывается здесь до обработки этим элементом -->
<div v-on:click.capture="doThis">...</div>

<!-- вызывать обработчик только в случае наступления события непосредственно -->
<!-- на данном элементе (то есть не на дочернем компоненте) -->
<div v-on:click.self="doThat">...</div>

Порядок имеет значение при использовании модификаторов, потому что код генерируется в том же порядке. Поэтому использование v-on:click.prevent.self будет предотвращать все клики, в то время как v-on:click.self.prevent будет предотвращать клики только на самом элементе.

Добавлено в версии 2.1.4+

<!-- Событие click сработает только 1 раз -->
<a v-on:click.once="doThis"></a>

В отличие от остальных модификаторов, которые поддерживают исключительно нативные DOM-события, модификатор .once можно использовать и в пользовательских событиях компонентов. Если вы ещё не читали о компонентах, не беспокойтесь об этом сейчас.

Добавлено в версии 2.3.0+

Vue также предоставляет модификатор .passive, соответствующий опции passive в addEventListener.

<!-- по умолчанию произойдёт событие scroll (при прокрутке)   -->
<!-- незамедлительно, вместо ожидания окончания `onScroll`    -->
<!-- на случай, если будет содержать `event.preventDefault()` -->
<div v-on:scroll.passive="onScroll">...</div>

Модификатор .passive особенно полезен для повышения производительности на мобильных устройствах.

Не используйте .passive и .prevent вместе, потому что .prevent будет проигнорирован и ваш браузер возможно покажет предупреждение. Помните, что .passive сообщает браузеру, что вы не хотите предотвращать для события поведение по умолчанию.

Модификаторы клавиш

При обработке событий от клавиатуры нас часто интересуют распространённые коды клавиш. Vue позволяет добавить модификаторы клавиш при использовании v-on для отслеживания событий от клавиатуры:

<!-- вызвать `vm.submit()` только если `keyCode` равен 13 -->
<input v-on:keyup.13="submit">

Удерживать все коды клавиш в памяти — неблагодарное дело, поэтому Vue предоставляет псевдонимы для наиболее часто используемых из них:

<!-- аналогично примеру выше -->
<input v-on:keyup.enter="submit">

<!-- работает также и в сокращённой записи -->
<input @keyup.enter="submit">

Вот полный список поддерживаемых псевдонимов:

Вы можете также определить пользовательские псевдонимы клавиш через глобальный объект config.keyCodes:

// позволит использовать `v-on:keyup.f1`
Vue.config.keyCodes.f1 = 112

Автоматические модификаторы клавиш

Добавлено в версии 2.5.0+

Вы можете также напрямую использовать любые допустимые имена клавиш, открытые через KeyboardEvent.key в качестве модификаторов, именуя их в kebab-case:

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

В приведённом выше примере обработчик будет вызван только в случае, если $event.key === 'PageDown'.

Несколько клавиш (.esc и все клавиши со стрелками) имеют несогласованные значения в IE9, их встроенные псевдонимы должны быть предпочтительными, если вам нужно поддерживать IE9.

Системные модификаторы клавиш

Добавлено в версии 2.1.0+

Вы можете использовать следующие модификаторы для отслеживания событий мыши или клавиатуры с зажатой клавишей-модификатором:

Примечание: На клавиатурах Apple клавиша meta отмечена знаком ⌘. На клавиатурах Windows клавиша meta отмечена знаком ⊞. На клавиатурах Sun Microsystems клавиша meta отмечена символом ромба (◆). На некоторых клавиатурах, особенно MIT и Lisp machine и их преемников, таких как Knight-клавиатуры или клавиатуры space-cadet, клавиша meta отмечена словом “META”. На клавиатурах Symbolics, meta-клавиша отмечена словом “META” или “Meta”.

Например:

<!-- Alt + C -->
<input @keyup.alt.67="clear">

<!-- Ctrl + Click -->
<div @click.ctrl="doSomething">Сделать что-нибудь</div>

Обратите внимание, клавиши-модификаторы отличаются от обычных клавиш и при использовании событий keyup они должны быть нажаты, когда событие генерируется. Другими словами, keyup.ctrl сработает только тогда, когда вы отпустите клавишу, удерживая нажатой ctrl. Это не сработает, если вы отпустите только клавишу ctrl. Если вы хотите такое поведение, используйте keyCode для ctrl вместо keyup.17.

Модификатор .exact

Добавлено в версии 2.5.0+

Модификатор .exact позволяет контролировать точную комбинацию системных модификаторов, необходимых для запуска события.

<!-- это сработает, даже если Alt или Shift также нажаты -->
<button @click.ctrl="onClick">A</button>

<!-- это сработает, только когда нажат Ctrl и не нажаты никакие другие клавиши -->
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- это сработает, только когда не нажаты никакие системные модификаторы -->
<button @click.exact="onClick">A</button>

Модификаторы клавиш мыши

Добавлено в версии 2.2.0+

Эти модификаторы ограничивают обработчик события только вызовами определённой кнопкой мыши.

Почему подписчики указываются в HTML?

Может показаться, что такой подход к отслеживанию событий нарушает старое доброе правило “разделения мух и котлет”. Не беспокойтесь — поскольку все обработчики во Vue строго связываются с ответственным за текущее представление экземпляром vm, трудностей в поддержке не возникает. На практике есть даже несколько преимуществ при использовании v-on:

  1. Легче получить представление об имеющихся обработчиках, просто пробежав глазами по HTML-коду шаблона.

  2. Поскольку нет необходимости вручную привязывать слушателей событий в JS, код vm остаётся независимым от DOM и содержит только необходимую логику. Это облегчает тестирование.

  3. Когда vm уничтожается, все слушатели событий автоматически удаляются. Нет необходимости волноваться о том, что придётся прибираться за собой.

← Рендеринг списков Работа с формами →
Обнаружили ошибку или хотите добавить что-то своё в документацию? Отредактируйте эту страницу на GitHub!