Props ​

Bu sayfa, Bileşenlerin Temelleri'ni okuduğunuzu varsayar. Bileşenlere yeniyseniz, önce bunu okuyun.

Props Tanımlama ​

Vue bileşenleri, bileşene iletilen dış özelliklerden (props) hangilerinin aktarılacak öznitelikler (fallthrough attributes) olarak ele alınacağını Vue’nün bilmesi için açık bir props tanımlaması gerektirir (bu konu kendi bölümünde ele alınacaktır).

<script setup>
const props = defineProps(['foo'])

console.log(props.foo)
</script>

export default {
  props: ['foo'],
  setup(props) {
    // setup() props'u ilk argüman olarak alır.
    console.log(props.foo)
  }
}

export default {
  props: ['foo'],
  created() {
    // props'lar `this` üzerinden erişilebilir
    console.log(this.foo)
  }
}

Söz dizisi kullanarak props tanımlamanın yanı sıra, nesne söz dizimini de kullanabiliriz:

export default {
  props: {
    title: String,
    likes: Number
  }
}

// <script setup> içinde
defineProps({
  title: String,
  likes: Number
})

// <script setup> kullanılmayan bileşenlerde
export default {
  props: {
    title: String,
    likes: Number
  }
}

Nesne tanımlama söz diziminde her bir özellik için anahtar, prop’un adıdır; değer ise beklenen tipin constructor fonksiyonu olmalıdır.

Bu yalnızca bileşeninizi dokümante etmekle kalmaz, aynı zamanda diğer geliştiriciler bileşeninizi kullanırken yanlış bir tip ile props geçerse tarayıcı konsolunda uyarı verilmesini de sağlar. Prop doğrulama konusunu bu sayfanın ilerleyen bölümlerinde daha ayrıntılı ele alacağız.

<script setup lang="ts">
defineProps<{
  title?: string
  likes?: number
}>()
</script>

const { foo } = defineProps(['foo'])

watchEffect(() => {
  // 3.5 öncesinde yalnızca bir kez çalışır
  // 3.5+ sürümünde "foo" prop’u değiştiğinde yeniden çalışır
  console.log(foo)
})

const props = defineProps(['foo'])

watchEffect(() => {
  // `foo`, derleyici tarafından `props.foo` olarak dönüştürülür
  console.log(props.foo)
})

const { foo = 'hello' } = defineProps<{ foo?: string }>()

const { foo } = defineProps(['foo'])

watch(foo, /* ... */)

watch(() => foo, /* ... */)

useComposable(() => foo)

Prop Aktarım Detayları ​

Prop İsimlendirme Stili ​

Uzun prop isimlerini camelCase kullanarak tanımlarız çünkü bu, bunları nesne anahtarı olarak kullanırken tırnak işaretleri kullanma ihtiyacını ortadan kaldırır ve geçerli JavaScript tanımlayıcıları oldukları için şablon ifadelerinde doğrudan referans verilmesine olanak tanır:

defineProps({
  greetingMessage: String
})

export default {
  props: {
    greetingMessage: String
  }
}

<span>{{ greetingMessage }}</span>

Teknik olarak, props’ları bir alt bileşene aktarırken camelCase de kullanabilirsiniz (DOM içi şablonlar hariç). Ancak yaygın kullanım, HTML öznitelikleriyle uyum sağlamak için tüm durumlarda kebab-case kullanılması yönündedir:

<MyComponent greeting-message="hello" />

Mümkün olduğunda bileşen etiketleri için PascalCase kullanırız çünkü bu, şablon okunabilirliğini artırarak Vue bileşenlerini yerleşik (native) HTML öğelerinden ayırmayı kolaylaştırır. Ancak props aktarırken camelCase kullanmanın aynı düzeyde pratik bir avantajı olmadığı için, her dilin kendi kullanım kurallarını takip etmeyi tercih ederiz.

Statik ve Dinamik Props ​

Şu ana kadar props’ların statik değerler olarak iletildiğini gördünüz, örneğin:

<BlogPost title="My journey with Vue" />

Ayrıca props’ların v-bind ya da bunun kısayolu olan : kullanılarak dinamik olarak atandığını da gördünüz, örneğin:

<!-- Bir değişkenin değerini dinamik olarak ata -->
<BlogPost :title="post.title" />

<!-- Karmaşık bir ifadenin değerini dinamik olarak ata -->
<BlogPost :title="post.title + ' by ' + post.author.name" />

Farklı Değer Türlerinin İletilmesi ​

Yukarıdaki iki örnekte, string değerler ilettik; ancak bir prop’a herhangi bir türde değer iletilebilir.

Sayı ​

<!-- `42` statik olsa bile, Vue'ye bunun bir string değil                   -->
<!-- JavaScript ifadesi olduğunu belirtmek için v-bind kullanmamız gerekir. -->
<BlogPost :likes="42" />

<!-- Bir değişkenin değerine dinamik olarak ata. -->
<BlogPost :likes="post.likes" />

Boolean ​

<!-- Prop'u değer vermeden eklemek, `true` anlamına gelir. -->
<BlogPost is-published />

<!-- `false` statik olsa bile, Vue'ye bunun bir string değil                -->
<!-- JavaScript ifadesi olduğunu belirtmek için v-bind kullanmamız gerekir. -->
<BlogPost :is-published="false" />

<!-- Bir değişkenin değerine dinamik olarak ata. -->
<BlogPost :is-published="post.isPublished" />

Dizi ​

<!-- Dizi statik olsa bile, Vue'ye bunun bir string değil                   -->
<!-- JavaScript ifadesi olduğunu belirtmek için v-bind kullanmamız gerekir. -->
<BlogPost :comment-ids="[234, 266, 273]" />

<!-- Bir değişkenin değerine dinamik olarak ata. -->
<BlogPost :comment-ids="post.commentIds" />

Nesne ​

<!-- Nesne statik olsa bile, Vue'ye bunun bir string değil                  -->
<!-- JavaScript ifadesi olduğunu belirtmek için v-bind kullanmamız gerekir. -->
<BlogPost
  :author="{
    name: 'Veronica',
    company: 'Veridian Dynamics'
  }"
 />

<!-- Bir değişkenin değerine dinamik olarak ata. -->
<BlogPost :author="post.author" />

Bir Nesne Kullanarak Birden Fazla Özellik Bağlama ​

Bir nesnenin tüm özelliklerini props olarak iletmek istiyorsanız, v-bind’ı argümansız olarak kullanabilirsiniz (:prop-name yerine v-bind). Örneğin, bir post nesnesi verildiğinde:

export default {
  data() {
    return {
      post: {
        id: 1,
        title: 'My Journey with Vue'
      }
    }
  }
}

const post = {
  id: 1,
  title: 'My Journey with Vue'
}

Aşağıdaki şablon:

<BlogPost v-bind="post" />

Şuna eşdeğer olacaktır:

<BlogPost :id="post.id" :title="post.title" />

Tek Yönlü Veri Akışı ​

Tüm props’lar, alt özellik ile üst özellik arasında tek yönlü aşağı doğru bir bağ oluşturur: üst özellik güncellendiğinde bu değişiklik alt özelliğe yansır, ancak tersi mümkün değildir. Bu, alt bileşenlerin yanlışlıkla üst bileşenlerin durumunu değiştirmesini engeller ve uygulamanızdaki veri akışının anlaşılmasını zorlaştırabilecek durumların önüne geçer.

Ayrıca, her üst bileşen güncellendiğinde, alt bileşendeki tüm props’lar en güncel değerleriyle yeniden güncellenir. Bu, bir prop’u alt bileşen içinde değiştirmeye (mutate etmeye) çalışmamanız gerektiği anlamına gelir. Eğer bunu yaparsanız, Vue konsolda size bir uyarı gösterecektir:

const props = defineProps(['foo'])

// ❌ uyarı, props salt okunurdur!
props.foo = 'bar'

export default {
  props: ['foo'],
  created() {
    // ❌ uyarı, props salt okunurdur!
    this.foo = 'bar'
  }
}

Bir prop’u değiştirmeye (mutate etmeye) yönelme eğiliminin genellikle iki durumu vardır:

1. Prop başlangıç değeri olarak iletilir; alt bileşen ise bunu sonrasında yerel bir data özelliği olarak kullanmak ister. Bu durumda, prop’u başlangıç değeri olarak kullanan yerel bir data özelliği tanımlamak en iyi yaklaşımdır:

   js

   const props = defineProps(['initialCounter'])
   
   // counter, props.initialCounter değerini yalnızca başlangıç değeri olarak kullanır;
   // sonraki prop güncellemeleriyle bağlantılı değildir.
   const counter = ref(props.initialCounter)

   js

   export default {
     props: ['initialCounter'],
     data() {
       return {
         // counter, this.initialCounter değerini yalnızca başlangıç değeri olarak kullanır;
         // sonraki prop güncellemeleriyle bağlantılı değildir.
         counter: this.initialCounter
       }
     }
   }

2. Prop, dönüştürülmesi gereken ham bir değer olarak iletilir. Bu durumda, prop’un değerini kullanan bir computed özellik tanımlamak en iyi yaklaşımdır:

   js

   const props = defineProps(['size'])
   
   // prop değiştiğinde otomatik olarak güncellenen computed özellik
   const normalizedSize = computed(() => props.size.trim().toLowerCase())

   js

   export default {
     props: ['size'],
     computed: {
       // prop değiştiğinde otomatik olarak güncellenen computed özellik
       normalizedSize() {
         return this.size.trim().toLowerCase()
       }
     }
   }

Nesne / Dizi Props’larını Değiştirme ​

Nesneler ve diziler props olarak iletildiğinde, alt bileşen prop bağını değiştiremez; ancak nesne ya da dizinin iç içe özelliklerini değiştirebilir. Bunun nedeni, JavaScript’te nesnelerin ve dizilerin referansla aktarılmasıdır ve Vue’nün bu tür değişiklikleri engellemesi makul olmayan bir maliyet oluşturur.

Bu tür değişikliklerin temel sakıncası, alt bileşenin üst durumu üst bileşen açısından açık olmayan bir şekilde etkileyebilmesidir; bu da gelecekte veri akışını anlamayı zorlaştırabilir. En iyi uygulama olarak, üst ve alt tasarım gereği sıkı şekilde bağlı olmadıkça bu tür değişikliklerden kaçınmalısınız. Çoğu durumda alt bileşen, değişikliğin üst bileşen tarafından yapılmasını sağlamak için bir olay tetiklemelidir.

Prop Doğrulama ​

Bileşenler, daha önce gördüğünüz türler gibi props’ları için gereksinimler belirleyebilir. Eğer bu gereksinimlerden biri karşılanmazsa, Vue tarayıcının JavaScript konsolunda bir uyarı gösterir. Bu özellik, özellikle başkaları tarafından kullanılmak üzere geliştirilen bileşenlerde oldukça faydalıdır.

Prop doğrulamalarını belirtmek için, string dizisi yerine defineProps() makrosunaprops seçeneğine doğrulama gereksinimlerini içeren bir nesne sağlayabilirsiniz. Örneğin:

defineProps({
  // Temel tip kontrolü
  // (`null` ve `undefined` değerleri her türü kabul eder)
  propA: Number,
  // Birden fazla olası tip
  propB: [String, Number],
  // Zorunlu string
  propC: {
    type: String,
    required: true
  },
  // Zorunlu ama nullable string
  propD: {
    type: [String, null],
    required: true
  },
  // Varsayılan değeri olan sayı
  propE: {
    type: Number,
    default: 100
  },
  // Varsayılan değeri olan nesne
  propF: {
    type: Object,
    // Nesne veya dizi varsayılanları bir factory (fabrika) fonksiyonundan döndürülmelidir.
    // Bu fonksiyon, bileşenin aldığı ham props değerlerini argüman olarak alır.
    default(rawProps) {
      return { message: 'hello' }
    }
  },
  // Özel validator (doğrulama) fonksiyonu
  // 3.4+ sürümünde tüm props ikinci argüman olarak da iletilir
  propG: {
    validator(value, props) {
      // Değer şu string'lerden biri olmalıdır
      return ['success', 'warning', 'danger'].includes(value)
    }
  },
  // Varsayılan değeri olan fonksiyon
  propH: {
    type: Function,
    // Nesne veya dizi varsayılanlarından farklı olarak bu bir factory (fabrika) fonksiyonu değildir
    // bu, varsayılan değer olarak kullanılan bir fonksiyondur
    default() {
      return 'Default function'
    }
  }
})

export default {
  props: {
    // Temel tip kontrolü
    // (`null` ve `undefined` değerleri her türü kabul eder)
    propA: Number,
    // Birden fazla olası tip
    propB: [String, Number],
    // Zorunlu string
    propC: {
      type: String,
      required: true
    },
    // Zorunlu ama nullable string
    propD: {
      type: [String, null],
      required: true
    },
    // Varsayılan değeri olan sayı
    propE: {
      type: Number,
      default: 100
    },
    // Varsayılan değeri olan nesne
    propF: {
      type: Object,
      // Nesne veya dizi varsayılanları bir factory (fabrika) fonksiyonundan döndürülmelidir.
      // Bu fonksiyon, bileşenin aldığı ham props değerlerini argüman olarak alır.
      default(rawProps) {
        return { message: 'hello' }
      }
    },
    // Özel validator (doğrulama) fonksiyonu
    // 3.4+ sürümünde tüm props ikinci argüman olarak da iletilir
    propG: {
      validator(value, props) {
        // Değer şu string'lerden biri olmalıdır
        return ['success', 'warning', 'danger'].includes(value)
      }
    },
    // Varsayılan değeri olan fonksiyon
    propH: {
      type: Function,
      // Nesne veya dizi varsayılanlarından farklı olarak bu bir factory (fabrika) fonksiyonu değildir
      // bu, varsayılan değer olarak kullanılan bir fonksiyondur
      default() {
        return 'Default function'
      }
    }
  }
}

Ek detaylar:

• Tüm props’lar varsayılan olarak opsiyoneldir; required: true belirtilmediği sürece zorunlu değildir.

• Boolean dışında kalan opsiyonel bir prop sağlanmadığında, değeri undefined olur.

• Boolean türündeki ve gönderilmeyen props’lar false olarak değerlendirilir. Bunu değiştirmek için prop’a bir default değeri atayabilirsiniz — örneğin default: undefined kullanarak, Boolean olmayan bir prop gibi davranmasını sağlayabilirsiniz.

• Eğer bir default değeri belirtilmişse, çözümlenen prop değeri undefined olduğunda bu değer kullanılır — bu durum hem prop’un hiç gönderilmediği hem de açıkça undefined olarak iletildiği durumları kapsar.

Prop doğrulaması başarısız olduğunda, Vue (geliştirme sürümü kullanılıyorsa) konsolda bir uyarı üretir.

Runtime Tip Kontrolleri ​

type aşağıdaki yerleşik constructor’lardan biri olabilir:

• String
• Number
• Boolean
• Array
• Object
• Date
• Function
• Symbol
• Error

Buna ek olarak, type bir özel sınıf veya constructor fonksiyonu da olabilir ve doğrulama instanceof kontrolü ile yapılır. Örneğin, aşağıdaki sınıf verildiğinde:

class Person {
  constructor(firstName, lastName) {
    this.firstName = firstName
    this.lastName = lastName
  }
}

Bunu bir prop’un tipi olarak kullanabilirsiniz:

defineProps({
  author: Person
})

export default {
  props: {
    author: Person
  }
}

Vue, author prop’unun değerinin gerçekten Person sınıfının bir örneği olup olmadığını doğrulamak için instanceof Person kontrolünü kullanır.

Nullable Tip ​

Eğer tip zorunlu ancak null değeri alabiliyorsa, null içeren dizi söz dizimini kullanabilirsiniz:

defineProps({
  id: {
    type: [String, null],
    required: true
  }
})

export default {
  props: {
    id: {
      type: [String, null],
      required: true
    }
  }
}

type yalnızca null olarak belirtilirse ve dizi söz dizimi kullanılmazsa, bu durumda her tür kabul edilir.

Boolean Dönüştürme ​

Boolean tipindeki props’lar, yerleşik boolean attribute’ların davranışını taklit etmek için özel dönüştürme kurallarına sahiptir. Aşağıdaki şekilde tanımlanmış bir <MyComponent> verildiğinde:

defineProps({
  disabled: Boolean
})

export default {
  props: {
    disabled: Boolean
  }
}

Bileşen şu şekilde kullanılabilir:

<!-- :disabled="true" ile aynı anlama gelir -->
<MyComponent disabled />

<!-- :disabled="false" ile aynı anlama gelir -->
<MyComponent />

Bir prop birden fazla tip kabul edecek şekilde tanımlandığında, Boolean için geçerli olan dönüştürme kuralları da uygulanır. Ancak String ve Boolean birlikte kullanıldığında bir istisna vardır — Boolean dönüştürme kuralı yalnızca Boolean, String’den önce geliyorsa uygulanır:

// disabled true olarak değerlendirilir
defineProps({
  disabled: [Boolean, Number]
})

// disabled true olarak değerlendirilir
defineProps({
  disabled: [Boolean, String]
})

// disabled true olarak değerlendirilir
defineProps({
  disabled: [Number, Boolean]
})

// disabled boş bir string olarak değerlendirilir (disabled="")
defineProps({
  disabled: [String, Boolean]
})

// disabled true olarak değerlendirilir
export default {
  props: {
    disabled: [Boolean, Number]
  }
}

// disabled true olarak değerlendirilir
export default {
  props: {
    disabled: [Boolean, String]
  }
}

// disabled true olarak değerlendirilir
export default {
  props: {
    disabled: [Number, Boolean]
  }
}

// disabled boş bir string olarak değerlendirilir (disabled="")
export default {
  props: {
    disabled: [String, Boolean]
  }
}