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

v-model na Komponentach

4 min czytania ·
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:

  1. Przyjąć prop modelValue
  2. 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. 1. Czym jest v-model na custom komponencie?

  2. 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.

  1. Pytaniev-model na komponencie
  2. PytanieImplementacja v-model w komponencie
  3. Zadanie z kodemPraktyka: v-model komponent
  4. Ułóż w kolejnościImplementacja v-model
  5. PytanieMultiple v-model
  6. Zadanie z kodemPraktyka: Multiple v-model

Przydatne artykuły