Skip to content

Bileşende v-model ​

Temel Kullanım ​

v-model, bir bileşende iki yönlü bağlama uygulamak için kullanılabilir.

Vue 3.4 itibarıyla bunu başarmanın önerilen yolu, defineModel() makrosunu kullanmaktır:

Child.vue
vue
<script setup>
const model = defineModel()

function update() {
  model.value++
}
</script>

<template>
  <div>Parent bound v-model is: {{ model }}</div>
  <button @click="update">Increment</button>
</template>

Üst bileşen ardından bir değeri v-model ile bağlayabilir:

Parent.vue
template
<Child v-model="countModel" />

defineModel() tarafından döndürülen değer bir ref’tir. Herhangi bir ref gibi erişilebilir ve değiştirilebilir; ancak üst bileşendeki bir değer ile yerel değer arasında iki yönlü bağlama oluşturur:

  • .value değeri, üst bileşendeki v-model ile bağlanan değerle eşitlenir;
  • Alt bileşen tarafından değiştirildiğinde, üst bileşendeki bağlanan değerin de güncellenmesini sağlar.

Bu ref’i yerleşik bir input öğesine de v-model ile bağlayabileceğiniz anlamına gelir; böylece yerleşik input'ları sarmalarken aynı v-model kullanımını sunmak kolaylaşır:

vue
<script setup>
const model = defineModel()
</script>

<template>
  <input v-model="model" />
</template>

Playground'da deneyin

Arka planda ​

defineModel, kullanışlı bir makrodur. Derleyici bunu aşağıdakilere dönüştürür:

  • Yerel ref’in değeriyle eşitlenen modelValue adlı bir prop;
  • Yerel ref’in değeri değiştirildiğinde tetiklenen update:modelValue adlı bir olay.

Yukarıda gösterilen aynı alt bileşen, 3.4 öncesinde şu şekilde uygulanırdı:

Child.vue
vue
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>

<template>
  <input
    :value="props.modelValue"
    @input="emit('update:modelValue', $event.target.value)"
  />
</template>

Ardından, üst bileşendeki v-model="foo" ifadesi şuna derlenir:

Parent.vue
template
<Child
  :modelValue="foo"
  @update:modelValue="$event => (foo = $event)"
/>

Gördüğünüz gibi bu çok daha uzundur. Ancak, arka planda neler olduğunu anlamak faydalıdır.

defineModel bir prop bildirdiğinden, altta yatan prop’un seçeneklerini defineModel’e ileterek bildirebilirsiniz:

js
// v-model'i zorunlu yapma
const model = defineModel({ required: true })

// varsayılan değer atama
const model = defineModel({ default: 0 })

Uyarı

defineModel prop’u için bir default değeriniz varsa ve üst bileşenden bu prop için hiçbir değer iletmezseniz, üst ve alt bileşenler arasında senkronizasyon bozulmasına neden olabilir. Aşağıdaki örnekte üst bileşendeki myRef tanımsızdır, ancak alt bileşendeki model değeri 1’dir:

Child.vue
vue
<script setup>
const model = defineModel({ default: 1 })
</script>
Parent.vue
vue
<script setup>
const myRef = ref()
</script>

<template>
  <Child v-model="myRef"></Child>
</template>

Önce v-model’in yerleşik bir öğede nasıl kullanıldığını yeniden hatırlayalım:

template
<input v-model="searchText" />

Arka planda, şablon derleyicisi v-model’i bizim için daha uzun eşdeğerine dönüştürür. Dolayısıyla yukarıdaki kod, aşağıdakiyle aynı işi yapar:

template
<input
  :value="searchText"
  @input="searchText = $event.target.value"
/>

Bir bileşende kullanıldığında v-model bunun yerine şuna dönüşür:

template
<CustomInput
  :model-value="searchText"
  @update:model-value="newValue => searchText = newValue"
/>

Bunun gerçekten çalışması için <CustomInput> bileşeninin iki şey yapması gerekir:

  1. Yerleşik bir <input> öğesinin value özniteliğini modelValue prop’una bağlamalı
  2. Yerleşik input olayı tetiklendiğinde, yeni değerle update:modelValue özel olayını tetiklemeli

Örnek uygulama:

CustomInput.vue
vue
<script>
export default {
  props: ['modelValue'],
  emits: ['update:modelValue']
}
</script>

<template>
  <input
    :value="modelValue"
    @input="$emit('update:modelValue', $event.target.value)"
  />
</template>

Artık v-model bu bileşenle sorunsuz çalışmalıdır:

template
<CustomInput v-model="searchText" />

Playground'da deneyin

Bu bileşen içinde v-model’i uygulamanın bir başka yolu, hem getter hem de setter içeren yazılabilir bir computed özellik kullanmaktır. get yöntemi modelValue prop’unu döndürmeli, set yöntemi ise karşılık gelen olayı yayımlamalıdır:

CustomInput.vue
vue
<script>
export default {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  computed: {
    value: {
      get() {
        return this.modelValue
      },
      set(value) {
        this.$emit('update:modelValue', value)
      }
    }
  }
}
</script>

<template>
  <input v-model="value" />
</template>

v-model Argümanları ​

Bir bileşendeki v-model bir argüman da alabilir:

template
<MyComponent v-model:title="bookTitle" />

Alt bileşende, karşılık gelen argümanı desteklemek için defineModel() fonksiyonunun ilk argümanı olarak bir string değer iletebiliriz:

MyComponent.vue
vue
<script setup>
const title = defineModel('title')
</script>

<template>
  <input type="text" v-model="title" />
</template>

Playground'da deneyin

Prop seçenekleri de gerekiyorsa, model adından sonra iletilmelidir:

js
const title = defineModel('title', { required: true })
3.4 Öncesi Kullanım
MyComponent.vue
vue
<script setup>
defineProps({
  title: {
    required: true
  }
})
defineEmits(['update:title'])
</script>

<template>
  <input
    type="text"
    :value="title"
    @input="$emit('update:title', $event.target.value)"
  />
</template>

Playground'da deneyin

Bu durumda, varsayılan modelValue prop’u ve update:modelValue olayı yerine alt bileşen bir title prop’u beklemeli ve üst bileşendeki değeri güncellemek için update:title olayını tetiklemelidir:

MyComponent.vue
vue
<script>
export default {
  props: ['title'],
  emits: ['update:title']
}
</script>

<template>
  <input
    type="text"
    :value="title"
    @input="$emit('update:title', $event.target.value)"
  />
</template>

Playground'da deneyin

Birden Fazla v-model Bağlaması ​

Daha önce v-model argümanları ile belirli bir prop ve olayı hedefleme konusunda öğrendiğimiz bilgileri kullanarak, tek bir bileşen örneğinde birden fazla v-model bağlaması oluşturabiliriz.

Her v-model, bileşende ek seçenek gerekmeden farklı bir prop ile eşitlenir:

template
<UserName
  v-model:first-name="first"
  v-model:last-name="last"
/>
vue
<script setup>
const firstName = defineModel('firstName')
const lastName = defineModel('lastName')
</script>

<template>
  <input type="text" v-model="firstName" />
  <input type="text" v-model="lastName" />
</template>

Playground'da deneyin

3.4 Öncesi Kullanım
vue
<script setup>
defineProps({
  firstName: String,
  lastName: String
})

defineEmits(['update:firstName', 'update:lastName'])
</script>

<template>
  <input
    type="text"
    :value="firstName"
    @input="$emit('update:firstName', $event.target.value)"
  />
  <input
    type="text"
    :value="lastName"
    @input="$emit('update:lastName', $event.target.value)"
  />
</template>

Playground'da deneyin

vue
<script>
export default {
  props: {
    firstName: String,
    lastName: String
  },
  emits: ['update:firstName', 'update:lastName']
}
</script>

<template>
  <input
    type="text"
    :value="firstName"
    @input="$emit('update:firstName', $event.target.value)"
  />
  <input
    type="text"
    :value="lastName"
    @input="$emit('update:lastName', $event.target.value)"
  />
</template>

Playground'da deneyin

v-model Değiştiricilerini İşleme ​

Form input bağlamalarını incelerken, v-model’in yerleşik değiştiricilere sahip olduğunu görmüştük: .trim, .number ve .lazy. Bazı durumlarda özel input bileşeninizdeki v-model’in özel değiştiricileri desteklemesini de isteyebilirsiniz.

Özel bir değiştirici örneği olan capitalize ile v-model bağlamasının sağladığı string değerin ilk harfini büyütelim:

template
<MyComponent v-model.capitalize="myText" />

Bileşen v-model’ine eklenen değiştiricilere, alt bileşende defineModel() dönüş değerini şu şekilde parçalayarak erişebilirsiniz:

vue
<script setup>
const [model, modifiers] = defineModel()

console.log(modifiers) // { capitalize: true }
</script>

<template>
  <input type="text" v-model="model" />
</template>

Değiştiricilere göre değerin nasıl okunup yazılacağını koşullu olarak ayarlamak için defineModel()’e get ve set seçeneklerini iletebilirsiniz. Bu iki seçenek model ref’inin okunması ve yazılması sırasında gelen değeri alır ve dönüştürülmüş bir değer döndürmelidir. capitalize değiştiricisini uygulamak için set seçeneğini şöyle kullanabilirsiniz:

vue
<script setup>
const [model, modifiers] = defineModel({
  set(value) {
    if (modifiers.capitalize) {
      return value.charAt(0).toUpperCase() + value.slice(1)
    }
    return value
  }
})
</script>

<template>
  <input type="text" v-model="model" />
</template>

Playground'da deneyin

3.4 Öncesi Kullanım
vue
<script setup>
const props = defineProps({
  modelValue: String,
  modelModifiers: { default: () => ({}) }
})

const emit = defineEmits(['update:modelValue'])

function emitValue(e) {
  let value = e.target.value
  if (props.modelModifiers.capitalize) {
    value = value.charAt(0).toUpperCase() + value.slice(1)
  }
  emit('update:modelValue', value)
}
</script>

<template>
  <input type="text" :value="props.modelValue" @input="emitValue" />
</template>

Playground'da deneyin

Bileşen v-model’ine eklenen değiştiriciler modelModifiers prop’u üzerinden bileşene iletilir. Aşağıdaki örnekte, varsayılan değeri boş bir nesne olan bir modelModifiers prop’u içeren bir bileşen oluşturduk:

vue
<script>
export default {
  props: {
    modelValue: String,
    modelModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:modelValue'],
  created() {
    console.log(this.modelModifiers) // { capitalize: true }
  }
}
</script>

<template>
  <input
    type="text"
    :value="modelValue"
    @input="$emit('update:modelValue', $event.target.value)"
  />
</template>

Bileşenin modelModifiers prop’unun capitalize içerdiğine ve değerinin true olduğuna dikkat edin — bunun nedeni v-model.capitalize="myText" bağlamasında ayarlanmış olmasıdır.

Prop’umuzu kurduğumuza göre, modelModifiers nesnesinin anahtarlarını kontrol edebilir ve yayımlanan değeri değiştiren bir işleyici yazabiliriz. Aşağıdaki kodda, <input /> öğesi input olayı tetiklediğinde string değerin ilk harfini büyüteceğiz.

vue
<script>
export default {
  props: {
    modelValue: String,
    modelModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:modelValue'],
  methods: {
    emitValue(e) {
      let value = e.target.value
      if (this.modelModifiers.capitalize) {
        value = value.charAt(0).toUpperCase() + value.slice(1)
      }
      this.$emit('update:modelValue', value)
    }
  }
}
</script>

<template>
  <input type="text" :value="modelValue" @input="emitValue" />
</template>

Playground'da deneyin

Argümanlı v-model için Değiştiriciler ​

Hem argüman hem de değiştirici içeren v-model bağlamalarında üretilen prop adı arg + "Modifiers" olur. Örneğin:

template
<MyComponent v-model:title.capitalize="myText">

Karşılık gelen bildirimler şöyle olmalıdır:

js
export default {
  props: ['title', 'titleModifiers'],
  emits: ['update:title'],
  created() {
    console.log(this.titleModifiers) // { capitalize: true }
  }
}

Farklı argümanlara sahip birden fazla v-model ile değiştirici kullanımına ilişkin bir başka örnek:

template
<UserName
  v-model:first-name.capitalize="first"
  v-model:last-name.uppercase="last"
/>
vue
<script setup>
const [firstName, firstNameModifiers] = defineModel('firstName')
const [lastName, lastNameModifiers] = defineModel('lastName')

console.log(firstNameModifiers) // { capitalize: true }
console.log(lastNameModifiers) // { uppercase: true }
</script>
3.4 Öncesi Kullanım
vue
<script setup>
const props = defineProps({
  firstName: String,
  lastName: String,
  firstNameModifiers: { default: () => ({}) },
  lastNameModifiers: { default: () => ({}) }
})
defineEmits(['update:firstName', 'update:lastName'])

console.log(props.firstNameModifiers) // { capitalize: true }
console.log(props.lastNameModifiers) // { uppercase: true }
</script>
vue
<script>
export default {
  props: {
    firstName: String,
    lastName: String,
    firstNameModifiers: {
      default: () => ({})
    },
    lastNameModifiers: {
      default: () => ({})
    }
  },
  emits: ['update:firstName', 'update:lastName'],
  created() {
    console.log(this.firstNameModifiers) // { capitalize: true }
    console.log(this.lastNameModifiers) // { uppercase: true }
  }
}
</script>
Bileşende v-model has loaded