События компонента ​

Эта страница предполагает, что вы уже прочитали Основы компонентов.

Испускание и прослушивание событий ​

Компонент может испускать пользовательские события непосредственно в выражениях шаблона (например, в обработчике v-on) с помощью встроенного метода $emit:

<!-- MyComponent -->
<button @click="$emit('someEvent')">Нажми меня</button>

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

Родитель может прослушать его с помощью v-on:

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

Модификатор .once также поддерживается для слушателей событий компонентов:

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

Как и компоненты и параметры, имена событий обеспечивают автоматическое преобразование регистров. Обратите внимание, что мы создали событие в «верблюжьем» регистре, но можем прослушать его с помощью слушателя kebab-cased («шашлычная» нотация) в родителе. Как и в случае с регистром имён параметров, мы рекомендуем использовать в шаблонах слушатели событий в «шашлычном» регистре.

Аргументы событий ​

Иногда бывает полезно выдать событию определённое значение. Например, мы можем захотеть, чтобы компонент <BlogPost> отвечал за то, на сколько увеличивать текст. В таких случаях мы можем передать $emit дополнительные аргументы, чтобы получить это значение:

<button @click="$emit('increaseBy', 1)">
  Увеличить на 1
</button>

Затем, когда мы прослушиваем событие в родителе, мы можем использовать встроенную стрелочную функцию в качестве слушателя, что позволит нам получить доступ к аргументу события:

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

Или, если обработчик события является методом:

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

Тогда значение будет передано в качестве первого параметра этого метода:

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

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

Объявление испускаемых событий ​

Компонент может явно объявить события, которые он будет испускать, с помощью макроса defineEmits()свойства 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']
}

Опция emits и макрос defineEmits() также поддерживают объектный синтаксис. Если вы используете TypeScript, вы можете ввести аргументы, что позволит нам выполнить проверку полезной нагрузки испускаемых событий во время выполнения:

<script setup lang="ts">
const emit = defineEmits({
  submit(payload: { email: string; password: string }) {
    // возвращает `true` или `false` для указания, что
    // проверка пройдена / не пройдена
  }
})
</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 }) {
      // возвращает `true` или `false` для указания, что
      // проверка пройдена / не пройдена
    }
  }
}

Хотя это необязательно, рекомендуется определять все испускаемые события, чтобы лучше документировать работу компонента. Это также позволяет Vue исключать известные слушатели из обычных атрибутов, избегая краевых случаев, вызванных событиями DOM, вручную диспетчеризируемыми сторонним кодом.

Валидация событий ​

Аналогично проверке типа параметра, испускаемое событие может быть проверено, если оно определено с помощью синтаксиса объекта, а не синтаксиса массива.

Чтобы добавить проверку, событию назначается функция, которая получает аргументы, переданные вызову this.$emitemit, и возвращает булево число, указывающее, является ли событие действительным или нет.

<script setup>
const emit = defineEmits({
  // Без валидации
  click: null,

  // Проверка события submit
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Неверная полезная нагрузка события sumbit!')
      return false
    }
  }
})

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

export default {
  emits: {
    // Без валидации
    click: null,

    // Проверка события submit
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Неверная полезная нагрузка события sumbit!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}

События как пропсы ​

Вы также можете объявлять и передавать events как props, префиксируя имя события заглавными буквами с on.

Использование props.onEvent отличается от использования emit('event'), так как в первом случае будет передаваться только обработка слушателя, основанного на свойстве (либо @event, либо :on-event).

В связи с этим рекомендуется использовать emit('event') вместо props.onEvent при эмиссии событий.