Kurs Vue.js · Moduł 7: Props i zdarzenia
v-model na Komponentach
W tej lekcji5
Formularz nadawczy stacji ma pole "Treść komunikatu". Rodzic trzyma treść w ref, a samo pole siedzi w komponencie MarsInput. Props przekażą wartość w dół, zdarzenie odeśle zmianę w górę - ale pisanie tej pary przy każdym polu formularza szybko się nudzi. Na szczęście v-model działa też na custom komponentach - to jak dwukierunkowa synchronizacja danych między Ziemią a Marsem!
Na natywnych elementach HTML v-model jest skrótem, który zależy od elementu: pole tekstowe <input> i <textarea> łączą value ze zdarzeniem input, pola wyboru i przyciski radiowe łączą checked ze zdarzeniem change, a <select> łączy value ze zdarzeniem change. Na komponencie reguła jest jedna i to Ty ją wypełniasz.
Jak działa v-model na komponencie?
Kompilator Vue rozwija v-model na komponencie do propsa modelValue i nasłuchiwacza zdarzenia update:modelValue. Oba zapisy poniżej robią dokładnie to samo:
<!-- Rodzic używa v-model -->
<MarsInput v-model="message" />
<!-- Jest równoważne z: -->
<MarsInput
:modelValue="message"
@update:modelValue="message = $event"
/>W drugiej wersji $event to pierwszy argument wysłany przez dziecko, czyli nowa treść pola. Rodzic przypisuje ją do message, więc właścicielem danych nadal pozostaje rodzic.
Implementacja w komponencie
Komponent musi:
- Przyjąć prop
modelValue - Emitować event
update:modelValue
W praktyce oba punkty mieszczą się w kilku linijkach:
<!-- MarsInput.vue -->
<script setup>
defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>
<template>
<input
:value="modelValue"
@input="emit('update:modelValue', $event.target.value)"
/>
</template>Rodzic nie zmienił się ani o znak - wciąż pisze <MarsInput v-model="message" />. Całą pracę wykonuje dziecko: wyświetla modelValue i przy każdym wpisanym znaku wysyła zdarzenie z nową treścią. Samo nie nadpisuje propsa, zgodnie z zasadą jednokierunkowego przepływu - tylko prosi rodzica o zmianę.
defineModel - krótszy zapis (Vue 3.4+)
Od Vue 3.4 ten sam komponent napiszesz krócej dzięki makru defineModel. Zwraca ono ref: odczyt daje wartość propsa modelValue, a zapis emituje update:modelValue. Dlatego wewnątrz wystarczy zwykły v-model na polu <input>:
<!-- MarsInput.vue -->
<script setup>
const model = defineModel()
</script>
<template>
<input v-model="model" />
</template>Pod spodem działa ten sam mechanizm - prop i zdarzenie - więc rodzic nie widzi żadnej różnicy. Dokumentacja Vue zaleca defineModel w nowym kodzie, a wersję ręczną warto znać, bo spotkasz ją w starszych projektach i bibliotekach.
Multiple v-model
Vue 3 pozwala na wiele v-model na jednym komponencie. Argument po dwukropku zmienia nazwę pary: v-model:first-name łączy się z propsem firstName i zdarzeniem update:firstName:
<!-- Rodzic -->
<template>
<CrewForm
v-model:first-name="firstName"
v-model:last-name="lastName"
/>
</template>
<!-- CrewForm.vue -->
<script setup>
defineProps(['firstName', 'lastName'])
const emit = defineEmits(['update:firstName', 'update:lastName'])
</script>
<template>
<input
:value="firstName"
@input="emit('update:firstName', $event.target.value)"
/>
<input
:value="lastName"
@input="emit('update:lastName', $event.target.value)"
/>
</template>W szablonie rodzica argument możesz zapisać w kebab-case albo w camelCase, jako v-model:firstName - w plikach .vue obie formy działają. Z defineModel wystarczy podać nazwę: const firstName = defineModel('firstName').
v-model Modifiers
Możesz tworzyć własne modyfikatory. Użyte przy v-model trafiają do dziecka w propsie modelModifiers jako obiekt, na przykład { uppercase: true }:
<!-- Rodzic -->
<MarsInput v-model.uppercase="text" />
<!-- MarsInput.vue -->
<script setup>
const props = defineProps({
modelValue: String,
modelModifiers: { default: () => ({}) }
})
const emit = defineEmits(['update:modelValue'])
function onInput(e) {
let value = e.target.value
if (props.modelModifiers.uppercase) {
value = value.toUpperCase()
}
emit('update:modelValue', value)
}
</script>
<template>
<input :value="modelValue" @input="onInput" />
</template>Komponent sprawdza flagę i przekształca tekst przed wysłaniem, więc rodzic dostaje już wielkie litery. Dla nazwanego v-model:first-name prop z modyfikatorami nazywa się firstNameModifiers. Z defineModel modyfikatory odczytasz jako drugi element zwróconej pary, a przekształcenie wpiszesz w opcję set:
<script setup>
const [model, modifiers] = defineModel({
set(value) {
return modifiers.uppercase ? value.toUpperCase() : value
}
})
</script>Funkcja set dostaje wartość zapisywaną do modelu i zwraca to, co ma trafić do rodzica. Rodzic niczego nie zmienia - nadal pisze <MarsInput v-model.uppercase="text" />.
Moja rada: w nowych komponentach sięgaj po defineModel, bo to mniej kodu i mniej miejsc na literówkę w nazwie zdarzenia. W edytorze poniżej MarsInput i CrewForm używają wersji ręcznej - spróbuj przepisać je na defineModel. Pamiętaj tylko, że v-model łączy dwa sąsiednie poziomy; w następnej lekcji prześlesz dane pięć pięter w dół bez przekazywania ich przez każde piętro.
Zapamiętaj: v-model na komponencie to para prop i zdarzenie, spięta w jeden kanał dupleksowy.
Kod do tej lekcji: App.vue
<script setup>
import { ref } from 'vue'
import MarsInput from './MarsInput.vue'
import CrewForm from './CrewForm.vue'
const message = ref('Pozdrowienia z Marsa!')
const firstName = ref('Nova')
const lastName = ref('Komandor')
</script>
<template>
<div class="nova-lab">
<h1>v-model na komponentach</h1>
<h2>Pojedynczy v-model:</h2>
<MarsInput v-model="message" />
<p>Wartość w rodzicu: {{ message }}</p>
<h2>Wiele v-model:</h2>
<CrewForm
v-model:first-name="firstName"
v-model:last-name="lastName"
/>
<p>Imię i nazwisko: {{ firstName }} {{ lastName }}</p>
</div>
</template>
<style scoped>
.nova-lab {
background: #0a0e27;
color: #00ff88;
min-height: 100vh;
padding: 20px;
font-family: monospace;
}
h1 { color: #00ff88; margin-bottom: 20px; }
h2 { color: #00b4d8; margin: 15px 0 10px; }
p { margin: 8px 0; }
</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. Czym jest v-model na custom komponencie?
2. Co trzeba zrobić w komponencie, aby wspierał v-model?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Stwórz MarsInput z pełnym wsparciem v-model (modelValue + update:modelValue).
- Układanie w pionie
Ułóż kroki implementacji v-model w komponencie:
- Edytor kodu
Stwórz komponent z dwoma v-model: v-model:firstName i v-model:lastName.