Kurs Vue.js · Moduł 7: Props i zdarzenia

Custom Events

4 min czytania ·
W tej lekcji4

W Stacji Komunikacji sygnał nie idzie tylko w jedną stronę! Gdy Mars odbierze dane, wysyła potwierdzenie z powrotem na Ziemię. W Vue dziecko komunikuje się z rodzicem przez custom events - sygnały emitowane w górę drzewa komponentów.

Props płyną wyłącznie w dół, więc przycisk w module nadawczym nie może sam zmienić stanu centrali. Operator klika "Wyślij" i co dalej? Przycisk nie jest właścicielem dziennika łączności, trzyma go rodzic. Potrzebny jest kanał zwrotny: dziecko ogłasza, że coś się stało, a rodzic decyduje, co z tym zrobić.

defineEmits

W <script setup> deklarujesz emitowane zdarzenia makrem defineEmits. Tak jak defineProps, nie wymaga ono importu. Zwraca funkcję emit: jej pierwszym argumentem jest nazwa zdarzenia, a kolejnymi dane, które chcesz wysłać, czyli payload:

<!-- SignalButton.vue (dziecko) -->
<script setup>
const emit = defineEmits(['signal-sent', 'error'])

const sendSignal = () => {
  emit('signal-sent', { message: 'OK', time: Date.now() })
}

const reportError = (code) => {
  emit('error', code)
}
</script>

<template>
  <button @click="sendSignal">Send</button>
</template>

Lista w defineEmits działa jak rejestr kanałów modułu: od razu widać, jakie sygnały komponent potrafi nadać. Jeśli wyemitujesz zdarzenie spoza listy, Vue w trybie deweloperskim ostrzeże Cię w konsoli. Samo wywołanie emit niczego nie zmienia w dziecku - tylko nadaje komunikat.

Nasłuchiwanie w rodzicu

Rodzic nasłuchuje zdarzeń przez @event-name lub v-on:event-name, dokładnie tak jak kliknięć w zwykłe elementy HTML:

<!-- Parent.vue -->
<template>
  <SignalButton
    @signal-sent="handleSignal"
    @error="handleError"
  />
</template>

<script setup>
const handleSignal = (data) => {
  console.log('Signal received:', data.message)
}

const handleError = (code) => {
  console.error('Error:', code)
}
</script>

Handler dostaje payload jako swoje argumenty, dlatego handleSignal może odczytać data.message. Vue dopasowuje przy tym zapis nazw: zdarzenie wyemitowane jako signalSent złapiesz przez @signal-sent. Dokumentacja poleca camelCase w emit i kebab-case w szablonie rodzica, ale kebab-case po obu stronach, jak w tym przykładzie, też działa. Najważniejsza różnica względem zdarzeń DOM: zdarzenia komponentów nie wędrują w górę drzewa. Słyszy je tylko bezpośredni rodzic, a komponent dwa piętra wyżej nie dostanie sygnału, chyba że rodzic przekaże go dalej.

Event Payload

Emit może przekazywać dowolne dane jako payload - pojedynczą wartość, kilka argumentów albo cały obiekt:

<script setup>
const emit = defineEmits(['submit'])

const onSubmit = () => {
  // Jeden argument
  emit('submit', 'data')

  // Wiele argumentów
  emit('submit', name, email, role)

  // Obiekt
  emit('submit', { name, email, role })
}
</script>

Wszystkie argumenty po nazwie zdarzenia trafiają do handlera w tej samej kolejności. Polecam trzecią formę, czyli jeden obiekt: łatwiej dopisać do niego nowe pole, a rodzic nie musi pamiętać, który argument był który.

Walidacja Eventów

Obiektowa składnia defineEmits pozwala sprawdzić payload przed wysłaniem. Kluczem jest nazwa zdarzenia, a wartością null (bez walidacji) albo funkcja, która dostaje argumenty emit i zwraca true lub false:

<script setup>
const emit = defineEmits({
  // Bez walidacji
  click: null,

  // Z walidacją
  submit: (payload) => {
    if (!payload.email) return false
    if (!payload.email.includes('@')) return false
    return true
  }
})
</script>

Tak jak przy props, nieudana walidacja tylko ostrzega w konsoli w trybie deweloperskim - zdarzenie i tak zostanie wysłane, więc rodzic nadal powinien być gotowy na złe dane. W tym przykładzie kryje się też pułapka: linia click: null deklaruje nazwę zdarzenia natywnego. Od tej chwili nasłuchiwacz @click w rodzicu reaguje wyłącznie na zdarzenia wyemitowane przez komponent, a nie na zwykłe kliknięcia w jego główny element.

Moja rada: deklaruj każde zdarzenie, nawet gdy nie potrzebujesz walidacji. Rejestr kanałów to najkrótsza dokumentacja modułu, a ostrzeżenia o niezadeklarowanych sygnałach wyłapią literówki w nazwach. W edytorze poniżej dwa przyciski nadają ten sam sygnał, a rodzic zbiera je w jednym dzienniku. Props w dół i zdarzenia w górę tworzą razem pełny obieg danych - w następnej lekcji zobaczysz, jak Vue skleja te dwa kanały w jedną dyrektywę v-model.

Zapamiętaj: props to rozkaz z Ziemi, a emit to potwierdzenie z Marsa - dwa kanały, każdy w swoją stronę.

Kod do tej lekcji: App.vue
<script setup>
import { ref } from 'vue'
import SignalButton from './SignalButton.vue'

const messages = ref([])

const handleSignal = (data) => {
  messages.value.push(data)
}
</script>

<template>
  <div class="nova-lab">
    <h1>Demo: custom events</h1>

    <SignalButton
      label="Wyślij sygnał Alfa"
      @signal-sent="handleSignal"
    />
    <SignalButton
      label="Wyślij sygnał Beta"
      @signal-sent="handleSignal"
    />

    <div class="log">
      <h3>Odebrane sygnały:</h3>
      <p v-for="(msg, i) in messages" :key="i">
        {{ msg.timestamp }} - {{ msg.label }}: {{ msg.message }}
      </p>
      <p v-if="!messages.length" class="empty">Nie odebrano jeszcze żadnego sygnału...</p>
    </div>
  </div>
</template>

<style scoped>
.nova-lab {
  background: #0a0e27;
  color: #00ff88;
  min-height: 100vh;
  padding: 20px;
  font-family: monospace;
}
h1 { color: #00ff88; margin-bottom: 20px; }
.log {
  margin-top: 20px;
  padding: 15px;
  background: rgba(0, 180, 216, 0.1);
  border: 2px solid #00b4d8;
}
.log h3 { color: #00b4d8; margin-bottom: 10px; }
.empty { color: #666; font-style: italic; }
</style>

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Co to są custom events w Vue?

  2. 2. Jak wyemitować event w <script setup>?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Stwórz komponent emitujący event 'signal-received' z payload po kliknięciu przycisku.

  • Układanie w pionie

    Uporządkuj kroki przepływu custom event:

  • Klikanie w kolejności

    Ułóż kod emitowania eventu z danymi:

  • Edytor kodu

    Stwórz komponent z defineEmits z walidacją payloadu (obiektowa składnia).

  1. PytanieCzym są custom events?
  2. PytaniedefineEmits i emit
  3. Zadanie z kodemPraktyka: Custom events
  4. Ułóż w kolejnościPrzepływ custom event
  5. PytanieEvent payload
  6. Kliknij w kolejnościSkładnia emitowania eventu
  7. Zadanie z kodemPraktyka: Events z walidacją

Przydatne artykuły