Události komponent (Events) ​

Tato stránka předpokládá, že už jste četli Základy komponent. Pokud jsou pro vás komponenty nové, přečtěte si je jako první.

Vyvolání událostí a naslouchání jim ​

Komponenta může vysílat (emit) vlastní události přímo ve výrazech šablony (např. ve v-on handleru) pomocí vestavěné metody $emit:

<!-- MyComponent -->
<button @click="$emit('someEvent')">Klikni na mě</button>

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

Komponenta rodiče může událostem naslouchat s využitím v-on:

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

Event listenery komponenty podporují i modifikátor .once:

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

Stejně jako komponenty a vlastnosti poskytují názvy událostí automatickou transformaci názvů. Všimněte si, že jsme emitovali událost jako camelCase, ale můžeme jí v komponentě rodiče naslouchat pomocí listeneru s kebab-cased zápisem. Stejně jako v případě velkých a malých písmen v názvech vlastností doporučujeme v šablonách používat kebab-cased event listenery.

Parametry událostí ​

Někdy je užitečné vysílat spolu s událostí určitou hodnotu. Například můžeme chtít, aby komponenta <BlogPost> určovala, o kolik se má zvětšit text. V takových případech můžeme události $emit předat další parametry, které tuto hodnotu poskytnou:

<button @click="$emit('increaseBy', 1)">
  Zvýšit o 1
</button>

Když pak nasloucháme události v komponentě rodiče, můžeme jako listener použít inline arrow funkci, která nám umožní přistupovat k parametrům události:

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

Nebo pokud je event handler funkce:

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

Pak bude hodnota předána do této funkce jako první parametr:

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

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

Deklarování vysílaných událostí ​

Komponenta může explicitně deklarovat události, které bude vysílat, pomocí makra defineEmits()možnosti 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']
}

Možnost emits a defineEmits() makro také podporují objektovou syntaxi. Při použití TypeScriptu je možné typovat parametry, což nám umožňuje provádět runtime validaci obsahu (payload) emitovaných událostí:

<script setup lang="ts">
const emit = defineEmits({
  submit(payload: { email: string, password: string }) {
    // vrací `true` nebo `false` pro určení,
    // zda validace prošla / selhala
  }
})
</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 }) {
    // vrací `true` nebo `false` pro určení,
    // zda validace prošla / selhala
    }
  }
}

Ačkoli to není povinné, doporučuje se definovat všechny vysílané události, aby bylo možné lépe zdokumentovat, jak má komponenta fungovat. Umožňuje to také Vue vyloučit známé listenery z fallthrough atributů, čímž se vyhnete okrajovým případům způsobeným DOM událostmi odesílanými ručně kódem třetí strany.

Validace událostí ​

Podobně jako u validace typů u vlastností lze validovat emitovanou událost, pokud je definována pomocí syntaxe objektu namísto syntaxe pole.

Pro přidání validace je události přiřazena funkce, která obdrží parametry předané do volání this.$emitemit a vrátí boolean hodnotu označující, zda je událost platná, nebo ne.

<script setup>
const emit = defineEmits({
  // bez validace
  click: null,

  // validace události `submit`
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Neplatná data události!')
      return false
    }
  }
})

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

export default {
  emits: {
    // bez validace
    click: null,

    // validace události `submit`
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Neplatná data události!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}