Component Events ​

Подразумевается, что вы уже изучили и разобрались с разделом Основы компонентов. Если нет — прочитайте его сначала.

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

Компонент может генерировать пользовательские события непосредственно в выражениях шаблона (например, в обработчике 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" />

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

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

Иногда бывает полезно передать определенное значение вместе с событием. Например, мы можем захотеть, чтобы компонент <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 также поддерживает синтаксис объекта, что позволяет нам выполнять проверку полезной нагрузки пользовательских событий во время выполнения:

<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('Некорректные данные для события submit!')
      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('Некорректные данные для события submit!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}