Kurs Vue.js · Moduł 7: Props i zdarzenia
Custom Events
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. Co to są custom events w Vue?
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).