Vlastnosti (Props)

Tato stránka předpokládá, že už jste četli Základy komponent. Pokud jsou pro vás komponenty nové, přečtěte si je jako první.

Podívejte se ukázkovou hodinu od Vue School zdarma

Deklarace vlastností

Vue komponenty vyžadují explicitní deklaraci vlastností, aby Vue vědělo, které externí hodnoty předávané komponentě mají být považovány za „fallthrough“ atributy (což bude probráno v příslušné sekci).

V Single-file komponentách (SFC) s využitím <script setup>, je možné vlastnosti deklarovat pomocí makra defineProps():

vue

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

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

Ve komponentách bez <script setup>, se vlastnosti deklarují v možnosti props:

export default {
  props: ['foo'],
  setup(props) {
    // setup() obdrží `props` jako první parametr
    console.log(props.foo)
  }
}

Všimněte si, že parametr předávaný do defineProps() je stejný jako hodnota předávaná ze možnosti props: pro deklaraci vlastností je mezi oběma styly deklarace sdíleno stejné API.

Vlastnosti se deklarují v možnosti props:

export default {
  props: ['foo'],
  created() {
    // props jsou vystaveny přes `this`
    console.log(this.foo)
  }
}

Kromě deklarace vlastností pomocí pole řetězců můžeme použít také objektovou syntaxi:

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

// v rámci `<script setup>`
defineProps({
  title: String,
  likes: Number
})

// pokud není použito `<script setup>`
export default {
  props: {
    title: String,
    likes: Number
  }
}

Pro každou vlastnost deklarovanou objektovou syntaxí je klíčem jméno vlastnosti, zatímco hodnotou by měla být funkce konstruktoru očekávaného typu.

Nejen, že to vaší komponentu popisuje, ale také budou prostřednictvím výpisu do konzole prohlížeče varováni ostatní vývojáři, kteří vaši komponetu použjí, pokud budou předávat špatný datový typ. O validaci vlastností budeme více mluvit později níže na této stránce.

Viz také: Typování vlastností komponenty

Pokud používáte TypeScript a <script setup>, je také možné deklarovat vlastnosti s použitím „pure“ typových anotací:

vue

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

Více informací: Typování vlastností komponent

Detaily předávání vlastností

Velká a malá písmena v názvech vlastností

Dlouhé názvy vlastností deklarujeme pomocí camelCase, protože se tak vyhneme nutnosti doplňovat uvozovky při jejich použití jako klíčů vlastností a umožní nám to odkazovat přímo na ně ve výrazech šablon, jelikož se jedná o platné JavaScript identifikátory:

defineProps({
  greetingMessage: String
})

export default {
  props: {
    greetingMessage: String
  }
}

template

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

Technicky lze camelCase použít i při předávání vlastností do komponenty potomka (kromě in-DOM šablon). Konvence však ve všech případech používá kebab-case, aby se sladila s HTML atributy:

template

<MyComponent greeting-message="hello" />

Kdykoli je to možné, používáme pro tagy komponent PascalCase, protože to zlepšuje čitelnost šablony tím, že odlišuje Vue komponenty od nativních elementů. Použití camelCase při předávání vlastností však takový praktický přínos nemá, proto jsme se rozhodli dodržovat konvence jednotlivých jazyků.

Statické vs. dynamické vlastnosti

Zatím jste viděli vlastnosti předávané jako statické hodnoty, jako např.:

template

<BlogPost title="Moje cesta s Vue" />

Viděli jste také dynamické přiřazování vlastností pomocí v-bind nebo jeho zkratky :, jako třeba v:

template

<!-- Dynamicky přiřazená hodnota z jiné proměnné -->
<BlogPost :title="post.title" />

<!-- Dynamicky přiřazená hodnota komplexního výrazu -->
<BlogPost :title="post.title + ' od ' + post.author.name" />

Předávání různých datových typů

Ve dvou výše uvedených příkladech jsme předávali hodnoty typu string, ale jako vlastnost lze předat jakýkoli datový typ.

Číslo

template

<!-- I když je `42` statická hodnota, je třeba v-bind, abychom řekli Vue, -->
<!-- že toto je JavaScript výraz a nikoli prostý string. -->
<BlogPost :likes="42" />

<!-- Dynamicky přiřazená hodnota z jiné proměnné -->
<BlogPost :likes="post.likes" />

Boolean

template

<!-- Vlastnost bez hodnoty bude mít implicitně hodnotu `true`. -->
<BlogPost is-published />

<!-- I když je `false` statická hodnota, je třeba v-bind, abychom řekli Vue, -->
<!-- že toto je JavaScript výraz a nikoli prostý string. -->
<BlogPost :is-published="false" />

<!-- Dynamicky přiřazená hodnota z jiné proměnné -->
<BlogPost :is-published="post.isPublished" />

Pole

template

<!-- I když je hodnota pole statická, je třeba v-bind, abychom řekli Vue, -->
<!-- že toto je JavaScript výraz a nikoli prostý string. -->
<BlogPost :comment-ids="[234, 266, 273]" />

<!-- Dynamicky přiřazená hodnota z jiné proměnné -->
<BlogPost :comment-ids="post.commentIds" />

Objekt

template

<!-- I když je hodnota objektu statická, je třeba v-bind, abychom řekli Vue, -->
<!-- že toto je JavaScript výraz a nikoli prostý string. -->
<BlogPost
  :author="{
    name: 'Veronica',
    company: 'Veridian Dynamics'
  }"
 />

<!-- Dynamicky přiřazená hodnota z jiné proměnné -->
<BlogPost :author="post.author" />

Binding více vlastností s využitím objektu

Pokud chcete předat všechny vlastnosti objektu najednou, můžete použít v-bind bez argumentu (v-bind místo :prop-name). Například pokud máte objekt post:

export default {
  data() {
    return {
      post: {
        id: 1,
        title: 'Moje cesta s Vue'
      }
    }
  }
}

const post = {
  id: 1,
  title: 'Moje cesta s Vue'
}

Následující šablona:

template

<BlogPost v-bind="post" />

Bude stejná jako:

template

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

Jednosměrný datový tok

Všechny vlastnosti tvoří jednosměrný binding směrem dolů mezí nadřízenou a podřízenou vlastností: když se aktualizuje vlastnost v komponentě rodiče, přenese se to dolů na vlastnost potomka, ale nikoli naopak. To zabraňuje tomu, aby komponenty potomků omylem měnily stav vlastností rodiče, což by mohlo ztížit pochopení toku dat ve vaší aplikaci.

Kromě toho se při každé aktualizaci komponenty rodiče všechny vlastnosti v komponentě potomka obnoví na nejnovější hodnotu. To znamená, že byste se neměli pokoušet měnit vlastnost uvnitř komponenty potomka. Pokud to uděláte, Vue vás na to upozorní v konzoli:

const props = defineProps(['foo'])

// ❌ varování, props jsou read-only!
props.foo = 'bar'

export default {
  props: ['foo'],
  created() {
    // ❌ varování, props jsou read-only!
    this.foo = 'bar'
  }
}

Obvykle jsou dva případy, kdy vypadá lákavě vlastnost měnit:

Vlastnost slouží k předání počáteční hodnoty; komponenta potomka ji chce následně použít jako lokální datovou hodnotu. V tomto případě je nejlepší definovat lokální datovou proměnnou, která používá předanou vlastnost jako svou výchozí hodnotu:

const props = defineProps(['initialCounter'])

// counter použije `props.initialCounter` pouze jako výchozí hodnotu;
// od budoucích aktualizací je odpojen
const counter = ref(props.initialCounter)

export default {
  props: ['initialCounter'],
  data() {
    return {
      // counter použije `props.initialCounter` pouze jako výchozí hodnotu;
      // od budoucích aktualizací je odpojen
      counter: this.initialCounter
    }
  }
}

Vlastnost je předána jako surová (raw) hodnota, kterou je třeba transformovat. V tom případě je nejlepší pomocí hodnoty vlastnosti definovat computed proměnnou:

const props = defineProps(['size'])

// computed proměnná, která se automaticky aktualizuje, 
// pokud se vlastnost změní
const normalizedSize = computed(() => props.size.trim().toLowerCase())

export default {
  props: ['size'],
  computed: {
    // computed proměnná, která se automaticky aktualizuje, 
    // pokud se vlastnost změní
    normalizedSize() {
      return this.size.trim().toLowerCase()
    }
  }
}

Změny vlastností typu objekt / pole

Pokud jsou objekty a pole předávány jako vlastnosti, komponenta potomka sice nemůže měnit binding na vlastnosti, ale bude moci měnit vnořené prvky objektu nebo pole. Je to proto, že v jazyce JavaScript se objekty a pole předávají pomocí odkazů (pass by reference) a pro Vue je nepřiměřeně nákladné takovým změnám zabránit.

Hlavní nevýhodou takových změn je, že umožňují komponentám potomka ovlivňovat stav rodičů způsobem, který není pro komponentu rodiče zřejmý, což může v budoucnu ztížit uvažování o toku dat. V rámci osvědčených postupů byste se měli takovým změnám vyhnout, pokud nejsou komponenty rodiče a potomka už z definice úzce propojeny (tightly coupled). Ve většině případů by měl potomek vyvolat událost, aby nechal změnu provést svého rodiče.

Validace vlastností

Komponenty mohou specifikovat požadavky na své vlastnosti, například datové typy, které jste již viděli. Pokud některý požadavek není splněn, Vue vás na to upozorní v JavaScript konzoli prohlížeče. To je užitečné zejména při vývoji komponenty, která má být používána jinými uživateli.

Chcete-li zadat ověřování vlastností, můžete makru defineProps()v možnosti props místo pole řetězců zadat objekt s požadavky na ověření. Například:

defineProps({
  // základní kontrola typu
  //  (hodnoty `null` a `undefined` umožní jakýkoli typ)
  propA: Number,
  // více možných typů
  propB: [String, Number],
  // povinný string
  propC: {
    type: String,
    required: true
  },
  // číslo s výchozí hodnotou
  propD: {
    type: Number,
    default: 100
  },
  // objekt s výchozí hodnotou
  propE: {
    type: Object,
    // výchozí hodnota objektu či pole musí být
    // vrácena z tovární (factory) metody
    // argumentem funkce budou surové (raw) vlastnosti,
    // které jsou předány do komponenty
    default(rawProps) {
      return { message: 'hello' }
    }
  },
  // vlastní validační funkce
  // od verze 3.4+ jsou jako druhý parametr předávány kompletní props
  propF: {
    validator(value, props) {
      // hodnota musí odpovídat jednomu z těchto tří řetězců
      return ['success', 'warning', 'danger'].includes(value)
    }
  },
  // funkce s výchozí hodnotou
  propG: {
    type: Function,
    // na rozdíl od výchozí hodnoty objektu či pole, 
    // toto není tovární (factory) metoda
    // toto je funkce, která bude nabídnuta jako výchozí hodnota
    default() {
      return 'Default function'
    }
  }
})

TIP

Kód uvnitř makra defineProps() nemůže přistupovat k jiným proměnným deklarovaným v <script setup>, protože celý výraz je při kompilaci přesunut do vnějšího function scope.

export default {
  props: {
    // základní kontrola typu
    //  (hodnoty `null` a `undefined` umožní jakýkoli typ)
    propA: Number,
    // více možných typů
    propB: [String, Number],
    // povinný string
    propC: {
      type: String,
      required: true
    },
    // číslo s výchozí hodnotou
    propD: {
      type: Number,
      default: 100
    },
    // objekt s výchozí hodnotou
    propE: {
      type: Object,
      // výchozí hodnota objektu či pole musí být
      // vrácena z tovární (factory) metody
      // argumentem funkce budou surové (raw) vlastnosti,
      // které jsou předány do komponenty
      default(rawProps) {
        return { message: 'hello' }
      }
    },
    // vlastní validační funkce
    // od verze 3.4+ jsou jako druhý parametr předávány kompletní props
    propF: {
      validator(value, props) {
        // hodnota musí odpovídat jednomu z těchto tří řetězců
        return ['success', 'warning', 'danger'].includes(value)
      }
    },
    // funkce s výchozí hodnotou
    propG: {
      type: Function,
      // na rozdíl od výchozí hodnoty objektu či pole,
      // toto není tovární (factory) metoda
      // toto je funkce, která bude nabídnuta jako výchozí hodnota
      default() {
        return 'Default function'
      }
    }
  }
}

Další podrobnosti:

Všechny vlastnosti jsou ve výchozím nastavení nepovinné, pokud není zadáno required: true.
Neuvedená nepovinná vlastnost kromě Boolean bude mít hodnotu undefined.
Neuvedená Boolean vlastnost bude převedena na hodnotu false. To můžete změnit nastavením default - tj.: default: undefined, aby se chovala jako ne-Boolean vlastnost.
Pokud je zadána default hodnota, bude použita, pokud je předáváná hodnota vlastnosti undefined - to se týká jak případů, kdy vlastnost chybí, tak těch, kdy je předána explicitní hodnota undefined.

Pokud validace vlastnosti selže, zobrazí Vue varování do konzole (pokud je aplikace sestavena v development módu).

Pokud používáte Type-based deklarace vlastností , Vue se pokusí kompilovat typové anotace na odpovídající runtime deklarace vlastností jak nejlépe dovede. Například, defineProps<{ msg: string }> bude při kompilaci převedeno na{ msg: { type: String, required: true }}.

Poznámka

Zapamatujte si, že vlastnosti jsou validovány dříve než je vytvořena instance komponenty, takže proměnné instance (např. data, computed, atd.) nebudou uvnitř funkcí default či validator dostupné.

Kontrola typů za běhu

Hodnota type může být jeden z následujících nativních konstruktorů:

String
Number
Boolean
Array
Object
Date
Function
Symbol
Error

Kromě toho může být type také vlastní třída nebo funkce konstruktoru a ověření bude provedeno pomocí kontroly instanceof. Například následující třídu:

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

Můžete použít jako typ vlastnosti:

defineProps({
  author: Person
})

export default {
  props: {
    author: Person
  }
}

Vue použije instanceof Person k ověření, zda je hodnota vlastnosti author skutečně instancí třídy Person.

Přetypování Boolean

Vlastnosti typu Boolean mají speciální pravidla přetypování k napodobení chování nativních boolean atributů. Pokud máme <MyComponent> s následující definicí:

defineProps({
  disabled: Boolean
})

export default {
  props: {
    disabled: Boolean
  }
}

Lze komponentu použít i tímto způsobem:

template

<!-- stejné jako předání :disabled="true" -->
<MyComponent disabled />

<!-- stejné jako předání :disabled="false" -->
<MyComponent />

Když je vlastnost deklarována, aby umožnila více typů, budou uplatněna rovněž pravidla přetypování pro Boolean. Ovšem je tu krajní případ, kdy jsou povoleny jak String, tak Boolean - pravidlo přetypování na Boolean bude uplatněno pouze pokud se Boolean objeví před String:

// disabled bude přetypováno na true
defineProps({
  disabled: [Boolean, Number]
})
  
// disabled bude přetypováno na true
defineProps({
  disabled: [Boolean, String]
})
  
// disabled bude přetypováno na true
defineProps({
  disabled: [Number, Boolean]
})
  
// disabled bude chápáno jako prázdný string (disabled="")
defineProps({
  disabled: [String, Boolean]
})

// disabled bude přetypováno na true
export default {
  props: {
    disabled: [Boolean, Number]
  }
}
  
// disabled bude přetypováno na true
export default {
  props: {
    disabled: [Boolean, String]
  }
}
  
// disabled bude přetypováno na true
export default {
  props: {
    disabled: [Number, Boolean]
  }
}
  
// disabled bude chápáno jako prázdný string (disabled="")
export default {
  props: {
    disabled: [String, Boolean]
  }
}

Navrhněte úpravu této stránky na GitHubu

Vlastnosti (Props) ​

Deklarace vlastností ​

Detaily předávání vlastností ​

Velká a malá písmena v názvech vlastností ​

Statické vs. dynamické vlastnosti ​

Předávání různých datových typů ​

Číslo ​

Boolean ​

Pole ​

Objekt ​

Binding více vlastností s využitím objektu ​

Jednosměrný datový tok ​

Změny vlastností typu objekt / pole ​

Validace vlastností ​

Kontrola typů za běhu ​

Přetypování Boolean ​

Vlastnosti (Props)

Deklarace vlastností

Detaily předávání vlastností

Velká a malá písmena v názvech vlastností

Statické vs. dynamické vlastnosti

Předávání různých datových typů

Číslo

Boolean

Pole

Objekt

Binding více vlastností s využitím objektu

Jednosměrný datový tok

Změny vlastností typu objekt / pole

Validace vlastností

Kontrola typů za běhu

Přetypování Boolean