---
url: /api/sfc-script-setup.md
---
# \<script setup> {#script-setup}

`<script setup>` est un sucre syntaxique de compilation pour l'utilisation de la Composition API dans les composants monofichiers (SFC). C'est la syntaxe recommandée si vous utilisez à la fois les SFC et la Composition API. Elle offre un certain nombre d'avantages par rapport à la syntaxe classique `<script>` :

* Un code plus succinct avec moins de répétitions
* Possibilité de déclarer des props et des événements émis en utilisant du TypeScript pur.
* Meilleures performances d'exécution (le template est compilé dans une fonction de rendu dans la même portée, sans proxy intermédiaire).
* Meilleures performances de l'environnement de développement concernant l'inférence de type (moins de travail pour le serveur de langage pour extraire les types du code).

## Syntaxe basique {#basic-syntax}

Pour utiliser cette syntaxe, ajoutez l'attribut `setup` au bloc `<script>` :

```vue
<script setup>
console.log('hello script setup')
</script>
```

Le code qu'il contient est compilé en tant que contenu de la fonction `setup()` du composant. Cela signifie que, contrairement au `<script>` normal, qui ne s'exécute qu'une fois lorsque le composant est importé pour la première fois, le code contenu dans `<script setup>` sera **exécuté à chaque fois qu'une instance du composant sera créée**.

### Les liaisons de haut niveau sont exposées au template {#top-level-bindings-are-exposed-to-template}

Lorsque vous utilisez `<script setup>`, toute liaison de haut niveau (y compris les variables, les déclarations de fonctions et les imports) déclarées dans `<script setup>` est directement utilisable dans le template :

```vue
<script setup>
// variable
const msg = 'Hello!'

// fonctions
function log() {
  console.log(msg)
}
</script>

<template>
  <button @click="log">{{ msg }}</button>
</template>
```

Les importations sont exposées de la même manière. Cela signifie que vous pouvez utiliser directement une fonction utilitaire importée dans des expressions de template sans avoir à l'exposer via l'option `methods` :

```vue
<script setup>
import { capitalize } from './helpers'
</script>

<template>
  <div>{{ capitalize('hello') }}</div>
</template>
```

## Réactivité {#reactivity}

L'état réactif doit être créé explicitement à l'aide des [API de réactivité](./reactivity-core). Comme les valeurs retournées par une fonction `setup()`, les refs sont automatiquement déballées lorsqu'elles sont référencées dans les templates :

```vue
<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>
```

## Utilisation des composants {#using-components}

Les valeurs dans la portée de `<script setup>` peuvent également être utilisées directement comme noms de balises de composants personnalisés :

```vue
<script setup>
import MyComponent from './MyComponent.vue'
</script>

<template>
  <MyComponent />
</template>
```

Voyez `MyComponent` comme référencé à l'instar d'une variable. Si vous avez utilisé du JSX, le modèle mental est le même ici. L'équivalent en casse kebab `<my-component>` fonctionne aussi dans le template - mais les balises de composant en casse Pascal sont fortement recommandées pour des raisons de cohérence. Cela permet également de faire la différence avec les éléments personnalisés natifs.

### Composants dynamiques {#dynamic-components}

Puisque les composants sont référencés comme des variables au lieu d'être enregistrés sous des clés de chaîne de caractères, nous devons utiliser la liaison dynamique `:is` lorsque nous utilisons des composants dynamiques dans `<script setup>` :

```vue
<script setup>
import Foo from './Foo.vue'
import Bar from './Bar.vue'
</script>

<template>
  <component :is="Foo" />
  <component :is="someCondition ? Foo : Bar" />
</template>
```

Notez comment les composants peuvent être utilisés comme variables dans une expression ternaire.

### Composants récursifs {#recursive-components}

Un composant monofichier peut implicitement se référer à lui-même via son nom de fichier. Par exemple, un fichier nommé `FooBar.vue` peut se référer à lui-même comme `<FooBar/>` dans son template.

Notez cependant que la priorité est inférieure à celle des composants importés. Si vous avez une importation nommée qui entre en conflit avec le nom inféré du composant, vous pouvez utiliser un alias pour l'importation :

```js
import { FooBar as FooBarChild } from './components'
```

### Composants sous espace de nom {#namespaced-components}

Vous pouvez utiliser des balises de composants avec des points comme `<Foo.Bar>` pour faire référence à des composants imbriqués dans des propriétés d'objets. Ceci est utile lorsque vous importez plusieurs composants à partir d'un seul fichier :

```vue
<script setup>
import * as Form from './form-components'
</script>

<template>
  <Form.Input>
    <Form.Label>label</Form.Label>
  </Form.Input>
</template>
```

## Utilisation de directives personnalisées {#using-custom-directives}

Les directives personnalisées enregistrées de manière globale fonctionnent normalement. Les directives locales personnalisées n'ont pas besoin d'être explicitement enregistrées avec `<script setup>`, mais elles doivent suivre le schéma de dénomination `vNameOfDirective` :

```vue
<script setup>
const vMyDirective = {
  beforeMount: (el) => {
    // faire quelque chose avec l'élément
  }
}
</script>
<template>
  <h1 v-my-directive>This is a Heading</h1>
</template>
```

Si vous importez une directive d'ailleurs, vous pouvez la renommer pour qu'elle corresponde au schéma de dénomination requis :

```vue
<script setup>
import { myDirective as vMyDirective } from './MyDirective.js'
</script>
```

## defineProps() et defineEmits() {#defineprops-defineemits}

Pour déclarer des options comme `props` et `emits` avec une prise en charge complète de l'inférence de type, nous pouvons utiliser les API `defineProps` et `defineEmits`, qui sont automatiquement disponibles dans `<script setup>` :

```vue
<script setup>
const props = defineProps({
  foo: String
})

const emit = defineEmits(['change', 'delete'])
// code du script setup
</script>
```

* `defineProps` et `defineEmits` sont des **macros de compilation** utilisables uniquement à l'intérieur de `<script setup>`. Elles n'ont pas besoin d'être importées, et sont compilées lorsque `<script setup>` est traité.

* `defineProps` accepte la même valeur que l'option `props`, tandis que `defineEmits` accepte la même valeur que l'option `emits`.

* `defineProps` et `defineEmits` fournissent une inférence de type appropriée basée sur les options passées.

* Les options passées à `defineProps` et `defineEmits` seront placées en dehors de setup dans la portée du module. Par conséquent, les options ne peuvent pas faire référence à des variables locales déclarées dans la portée de setup. Cela entraînerait une erreur de compilation. Cependant, elles *peuvent* faire référence à des liaisons importées puisqu'elles sont également dans la portée du module.

### Déclaration des types de props et emits  {#type-only-props-emit-declarations}

Les props et les emits peuvent également être déclarés à l'aide d'un typage pur en passant un argument de type littéral à `defineProps` ou `defineEmits` :

```ts
const props = defineProps<{
  foo: string
  bar?: number
}>()

const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()

// 3.3+ : alternative, syntaxe plus succincte
const emit = defineEmits<{
  change: [id: number] // syntaxe avec tuple nommé
  update: [value: string]
}>()
```

* `defineProps` ou `defineEmits` ne peuvent utiliser que la déclaration à l'exécution OU la déclaration de type. L'utilisation des deux en même temps entraînera une erreur de compilation.

* Lors de l'utilisation de la déclaration de type, la déclaration à l'exécution équivalente est automatiquement générée à partir de l'analyse statique pour supprimer la nécessité d'une double déclaration tout en garantissant un comportement d'exécution correct.

  * En mode dev, le compilateur essaiera de déduire la validation d'exécution correspondante à partir des types. Par exemple ici `foo: String` est déduit du type `foo: string`. Les types importés sont également résolus, à condition que TypeScript soit installé en tant que dépendance pair.

  * En mode prod, le compilateur générera la déclaration au format tableau pour réduire la taille du bundle (les props ici seront compilées dans `['foo', 'bar']`)

* Dans la version 3.2 et les versions antérieures, le paramètre de type générique pour `defineProps()` était limité à un littéral de type ou à une référence à une interface locale.

  Cette limitation a été résolue en 3.3. La dernière version de Vue prend en charge le référencement importé et un ensemble limité de types complexes dans le paramètre de type. Cependant, étant donné que la conversion de type à l'exécution est toujours basée sur AST, certains types complexes qui nécessitent une analyse de type réelle, par exemple les types conditionnels ne sont pas pris en charge. Vous pouvez utiliser des types conditionnels pour le type d'une prop, mais pas pour l'ensemble de l'objet props.

### Destructuration réactive des props  {#reactive-props-destructure}

À partir de la Vue 3.5, les variables destructurées retournées par `defineProps` sont réactives. Le compilateur de Vue ajoute automatiquement `props.` quand le code dans le même bloc `<script setup>` accède aux variables destructurées provenant de `defineProps` :

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

watchEffect(() => {
  // s'exécute une seule fois avant la version 3.5
  // se ré-exécute quand la props "foo" change à partir de la version 3.5
  console.log(foo)
})
```

Le code ci-dessus est compilé comme suit :

```js {5}
const props = defineProps(['foo'])

watchEffect(() => {
  // `foo` transformé en `props.foo` par le compilateur
  console.log(props.foo)
})
```

De plus, vous pouvez utiliser la syntaxe native des valeurs par défaut de JavaScript pour déclarer des valeurs par défaut pour les accessoires. Ceci est particulièrement utile lorsque vous utilisez la déclaration de props basée sur le type :

```ts
interface Props {
  msg?: string
  labels?: string[]
}

const { msg = 'hello', labels = ['one', 'two'] } = defineProps<Props>()
```

### Valeurs par défaut des props quand on utilise une déclaration de type  {#default-props-values-when-using-type-declaration}

Dans les versions 3.5 et supérieures, les valeurs par défaut peuvent être déclarées naturellement lors de l'utilisation de la destructuration réactive des props. Mais dans les versions 3.4 et inférieures, la destructuration réactive des props n'est pas activé par défaut. Afin de déclarer les valeurs par défaut des props avec la déclaration basée sur le type, la macro de compilation `withDefaults` est nécessaire :

```ts
interface Props {
  msg?: string
  labels?: string[]
}

const props = withDefaults(defineProps<Props>(), {
  msg: 'hello',
  labels: () => ['one', 'two']
})
```

Cela sera compilé avec les options `default` des props à l'exécution. De plus, l'assistant `withDefaults` fournit des vérifications de type pour les valeurs par défaut et s'assure que le type `props` renvoyé a les drapeaux facultatifs supprimés pour les propriétés qui ont des valeurs par défaut déclarées.

:::info
Notez que les valeurs par défaut de référence mutables (comme les tableaux ou les objets) doivent être enveloppées dans des fonctions lors de l'utilisation de `withDefaults` afin d'éviter toute modification accidentelle et tout effet de bord externe. Cela permet de s'assurer que chaque instance de composant reçoit sa propre copie de la valeur par défaut. Ceci n'est **pas** nécessaire lors de l'utilisation de valeurs par défaut avec destructuration.
:::

## defineModel() {#definemodel}

* Disponible à partir de la version 3.4

Cette macro peut être utilisée pour déclarer une prop bidirectionnelle qui peut être consommée via `v-model` à partir du composant parent. Des exemples d'utilisation sont également présentés dans le guide [v-model du composant](/guide/components/v-model).

Sous le capot, cette macro déclare un modèle prop et un événement de mise à jour de valeur correspondant. Si le premier argument est une chaîne littérale, il sera utilisé comme nom de la prop, sinon, le nom de la propriété sera par défaut `"modelValue"`. Dans les deux cas, vous pouvez également passer un objet supplémentaire qui peut inclure les options de la prop et les options de transformation de la valeur de la ref du modèle.

```js
// déclare la prop "modelValue", consommée par le parent via le v-model
const model = defineModel()
// OU : déclare la prop "modelValue" avec des options
const model = defineModel({ type: String })

// émet "update:modelValue" lorsqu'il est modifié
model.value = 'hello'

// déclare la prop "count", consommée par le parent via v-model:count
const count = defineModel('count')
// OU : déclare la prop "count" avec des options
const count = defineModel('count', { type: Number, default: 0 })

function inc() {
  // émet "update:count" lorsqu'il est muté
  count.value++
}
```

:::warning
Si vous avez une valeur `default` pour la propriété `defineModel` et que vous ne fournissez aucune valeur pour cette propriété à partir du composant parent, cela peut provoquer une désynchronisation entre les composants parent et enfant. Dans l'exemple ci-dessous, le composant parent `myRef` est undefined, mais le composant enfant `model` vaut 1 :

```vue [Child.vue]
<script setup>
const model = defineModel({ default: 1 })
</script>
```

```vue [Parent.vue]
<script setup>
const myRef = ref()
</script>

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

:::

### Modificateurs et transformateurs

Pour accéder aux modificateurs utilisés avec la directive `v-model`, nous pouvons déstructurer la valeur de retour de `defineModel()` comme ceci :

```js
const [modelValue, modelModifiers] = defineModel()

// correspond à v-model.trim
if (modelModifiers.trim) {
  // ...
}
```

Lorsqu'un modificateur est présent, il est probable que nous devions transformer la valeur lors de la lecture ou de la synchronisation avec le parent. Nous pouvons y parvenir en utilisant les options de transformation `get` et `set` :

```js
const [modelValue, modelModifiers] = defineModel({
  // get() est omis car il n'est pas nécessaire ici
  set(value) {
    // si le modificateur .trim est utilisé, renvoie la valeur sans espaces supplémentaires
    if (modelModifiers.trim) {
      return value.trim()
    }
    // sinon, renvoie la valeur telle quelle
    return value
  }
})
```

### Utilisation avec TypeScript  {#usage-with-typescript}

Comme `defineProps` et `defineEmits`, `defineModel` peut aussi recevoir des arguments de type pour spécifier les types de la valeur du modèle et des modificateurs :

```ts
const modelValue = defineModel<string>()
//    ^? Ref<string | undefined>

// modèle par défaut avec options, les valeurs requises suppriment les possibles valeurs indéfinies
const modelValue = defineModel<string>({ required: true })
//    ^? Ref<string>

const [modelValue, modifiers] = defineModel<string, 'trim' | 'uppercase'>()
//                 ^? Record<'trim' | 'uppercase', true | undefined>
```

## defineExpose() {#defineexpose}

Les composants utilisant `<script setup>` sont **fermés par défaut** - c'est à dire que l'instance publique du composant, qui est récupérée via les refs du template ou via `$parent`, n'exposera **aucune** des liaisons déclarées dans `<script setup>`.

Pour exposer explicitement des propriétés dans un composant utilisant `<script setup>`, utilisez la macro de compilation `defineExpose` :

```vue
<script setup>
import { ref } from 'vue'

const a = 1
const b = ref(2)

defineExpose({
  a,
  b
})
</script>
```

Lorsqu'un parent accède à une instance de ce composant via des refs de template, l'instance récupérée sera de la forme `{ a: number, b: number }` (les refs sont automatiquement déballés comme pour les instances normales).

## defineOptions() {#defineoptions}

* Uniquement pris en charge à partir de la version 3.3.

Cette macro peut être utilisée pour déclarer des options de composant directement dans `<script setup>` sans avoir à utiliser un bloc `<script>` séparé :

```vue
<script setup>
defineOptions({
  inheritAttrs: false,
  customOptions: {
    /* ... */
  }
})
</script>
```

* Ceci est une macro. Les options seront hissées à la portée du module et ne pourront pas accéder aux variables locales du `<script setup>` qui ne sont pas des constantes littérales.

## defineSlots() {#defineslots}

* Uniquement pris en charge à partir de la version 3.3.

Cette macro peut être utilisée pour fournir des indications de type aux IDE pour la vérification du nom de slot et du type des props.

`defineSlots()` n'accepte qu'un paramètre de type et aucun argument d'exécution. Le paramètre de type doit être un littéral de type où la clé de propriété est le nom du slot et le type de valeur est la fonction du slot. Le premier argument de la fonction est les props que le slot s'attend à recevoir, et son type sera utilisé pour les props de slot dans le template. Le type de retour est actuellement ignoré et peut être `any`, mais nous pouvons l'utiliser pour vérifier le contenu des slots à l'avenir.

Il renvoie également l'objet `slots`, qui est équivalent à l'objet `slots` exposé dans le contexte setup ou renvoyé par `useSlots()`.

```vue
<script setup lang="ts">
const slots = defineSlots<{
  default(props: { msg: string }): any
}>()
</script>
```

## `useSlots()` et `useAttrs()` {#useslots-useattrs}

L'utilisation de `slots` et `attrs` à l'intérieur de `<script setup>` devrait être relativement rare, puisque vous pouvez y accéder directement via `$slots` et `$attrs` dans le template. Dans les rares cas où vous en avez besoin, utilisez respectivement les utilitaires `useSlots` et `useAttrs` :

```vue
<script setup>
import { useSlots, useAttrs } from 'vue'

const slots = useSlots()
const attrs = useAttrs()
</script>
```

`useSlots` et `useAttrs` sont des fonctions d'exécution qui retournent l'équivalent de `setupContext.slots` et `setupContext.attrs`. Elles peuvent également être utilisées dans les fonctions classiques de la Composition API.

## Utilisation en parallèle du `<script>` normal {#usage-alongside-normal-script}

`<script setup>` peut être utilisée en parallèle du `<script>` normal. Un `<script>` normal peut être nécessaire dans les cas où nous avons besoin de :

* Déclarer des options qui ne peuvent pas être exprimées dans `<script setup>`, par exemple `inheritAttrs` ou des options personnalisées activées par des plugins.
* Déclarer des exportations nommées.
* Exécuter des effets de bord ou créer des objets qui ne doivent être exécutés qu'une fois.

```vue
<script>
// <script> normal, exécuté dans la portée du module (une seule fois)
runSideEffectOnce()

// déclare des options supplémentaires
export default {
  inheritAttrs: false,
  customOptions: {}
}
</script>

<script setup>
// exécuté dans la portée de setup() (pour chaque instance)
</script>
```

La prise en charge de la combinaison de `<script setup>` et de `<script>` dans le même composant est limitée aux scénarios décrits ci-dessus. Plus précisément :

* N'utilisez **PAS** une section `<script>` distincte pour les options qui peuvent déjà être définies à l'aide de `<script setup>`, comme `props` et `emits`.
* Les variables créées à l'intérieur de `<script setup>` ne sont pas ajoutées comme propriétés à l'instance du composant, ce qui les rend inaccessibles depuis l'Options API. Il est fortement déconseillé de mélanger les API de cette manière.

Si vous vous trouvez dans un scénario non pris en charge, vous devriez envisager d'utiliser une fonction explicite [`setup()`](/api/composition-api-setup), au lieu d'utiliser `<script setup>`.

## `await` de haut niveau {#top-level-await}

Un `await` de haut niveau peut être utilisé à l'intérieur de `<script setup>`. Le code résultant sera compilé comme `async setup()` :

```vue
<script setup>
const post = await fetch(`/api/post/1`).then((r) => r.json())
</script>
```

De plus, l'expression attendue sera automatiquement compilée dans un format qui préserve le contexte de l'instance du composant courant après le `await`.

:::warning Remarque
`async setup()` doit être utilisée en combinaison avec [`Suspense`](/guide/built-ins/suspense.html), qui est actuellement encore une fonctionnalité expérimentale. Nous prévoyons de la finaliser et de la documenter dans une prochaine version - mais si vous êtes curieux, vous pouvez vous référer à ses [tests](https://github.com/vuejs/core/blob/main/packages/runtime-core/__tests__/components/Suspense.spec.ts) pour voir comment elle fonctionne.
:::

## Déclaration d'importation {#imports-statements}

Les déclarations d'importation en Vue sont conformes à la [spécification des modules ECMAScript](https://nodejs.org/api/esm.html).
En outre, vous pouvez utiliser des alias définis dans la configuration de votre outil de construction :

```vue
<script setup>
import { ref } from 'vue'
import { componentA } from './Components'
import { componentB } from '@/Components'
import { componentC } from '~/Components'
</script>
```

## Génériques  {#generics}

Les paramètres de type générique peuvent être déclarés à l'aide de l'attribut `generic` sur la balise `<script>` :

```vue
<script setup lang="ts" generic="T">
defineProps<{
  items: T[]
  selected: T
}>()
</script>
```

La valeur de `generic` fonctionne exactement de la même manière que la liste de paramètres entre `<...>` dans TypeScript. Par exemple, vous pouvez utiliser plusieurs paramètres, des contraintes "extends", des types par défaut et des types importés de référence :

```vue
<script
  setup
  lang="ts"
  generic="T extends string | number, U extends Item"
>
import type { Item } from './types'
defineProps<{
  id: T
  list: U[]
}>()
</script>
```

Vous pouvez utiliser la directive `@vue-generic` pour passer des types explicites, lorsque le type ne peut pas être déduit :

```vue
<template>
  <!-- @vue-generic {import('@/api').Actor} -->
  <ApiSelect v-model="peopleIds" endpoint="/api/actors" id-prop="actorId" />

  <!-- @vue-generic {import('@/api').Genre} -->
  <ApiSelect v-model="genreIds" endpoint="/api/genres" id-prop="genreId" />
</template>
```

Pour utiliser une référence d'un composant générique dans une 'ref', il convient d'utiliser la librairie [`vue-component-type-helpers`](https://www.npmjs.com/package/vue-component-type-helpers) au lieu de `InstanceType` qui ne fonctionnera pas.

```vue
<script
  setup
  lang="ts"
>
import componentWithoutGenerics from '../component-without-generics.vue';
import genericComponent from '../generic-component.vue';

import type { ComponentExposed } from 'vue-component-type-helpers';

// Fonctionne pour un composant non générique
ref<InstanceType<typeof componentWithoutGenerics>>();

ref<ComponentExposed<typeof genericComponent>>();
```

## Restrictions {#restrictions}

* En raison de la différence de sémantique d'exécution des modules, le code contenu dans `<script setup>` s'appuie sur le contexte d'un composant monofichier. Lorsqu'il est déplacé dans des fichiers externes `.js` ou `.ts`, il peut être source de confusion pour les développeurs et les outils. Par conséquent, **`<script setup>`** ne peut pas être utilisée avec l'attribut `src`.
* `<script setup>` ne supporte pas les composants dont le template est récupéré depuis le DOM. ([Discussion](https://github.com/vuejs/core/issues/8391))

---

---
url: /guide/best-practices/accessibility.md
---
# Accessibilité {#accessibility}

L'accessibilité numérique (en abrégé a11y) fait référence aux pratiques visant à créer des sites web qui peuvent être utilisés par toutes les personnes — qu'elles aient un handicap, une connexion lente, du matériel ancien ou défectueux ou simplement un environnement défavorable. Par exemple, ajouter des sous-titres à une vidéo peut aider vos utilisateurs sourds et malentendants ainsi que ceux dans un environnement bruyant et qui ne peuvent pas entendre leur téléphone. De la même façon, s'assurer que le contraste de votre texte n'est pas trop bas aidera les utilisateurs déficients visuels ainsi que ceux qui utilisent leur téléphone en plein soleil.

Par où commencer ?

Visitez le guide de [planification et pilotage de la prise en compte de l’accessibilité Web (en anglais)](https://www.w3.org/WAI/planning-and-managing/) proposé par le [World Wide Web Consortium (W3C)](https://www.w3.org/)

## Liens d'évitement ou d'accès rapide {#skip-link}

Vous devez ajouter un lien en haut de chaque page qui mène directement à la zone de contenu principale afin que les utilisateurs puissent ignorer les zones de regroupement de contenus répétées sur plusieurs pages web.

Typiquement, cela se fait en haut de `App.vue` car ce sera le premier élément pouvant être ciblé sur toutes vos pages :

```vue-html
<span ref="backToTop" tabindex="-1" />
<ul class="skip-links">
  <li>
    <a href="#main" ref="skipLink" class="skip-link">Skip to main content</a>
  </li>
</ul>
```

Pour masquer le lien lorsqu'il n'est pas ciblé, vous pouvez ajouter le style suivant :

```css
.skip-links {
  list-style: none;
}
.skip-link {
  white-space: nowrap;
  margin: 1em auto;
  top: 0;
  position: fixed;
  left: 50%;
  margin-left: -72px;
  opacity: 0;
}
.skip-link:focus {
  opacity: 1;
  background-color: white;
  padding: 0.5em;
  border: 1px solid black;
}
```

Lorsque qu'un utilisateur change d'itinéraire, redonnez le focus au tout début de la page, juste avant le lien d'évitement. Cela peut être réalisé en appelant focus sur la ref de template du lien d'évitement (en supposant l'utilisation de `vue-router`) :

```vue
<script>
export default {
  watch: {
    $route() {
      this.$refs.backToTop.focus()
    }
  }
}
</script>
```

```vue
<script setup>
import { ref, watch } from 'vue'
import { useRoute } from 'vue-router'

const route = useRoute()
const backToTop = ref()

watch(
  () => route.path,
  () => {
    backToTop.value.focus()
  }
)
</script>
```

[Lisez la documentation à propos des liens d'évitement vers le contenu principal](https://accessibilite.numerique.gouv.fr/methode/glossaire/#liens-d-evitement-ou-d-acces-rapide)

## Structuration de l'information {#content-structure}

L'un des éléments les plus importants de l'accessibilité est de s'assurer que le design peut soutenir une mise en œuvre accessible. Le design doit tenir compte non seulement du contraste des couleurs, de la sélection des polices, du dimensionnement du texte et de la langue, mais également de la structure du contenu dans l'application.

### Titres {#headings}

Les utilisateurs peuvent naviguer dans une application à travers les titres. Le fait d'avoir des titres descriptifs pour chaque section de votre application permet aux utilisateurs de prédire plus facilement le contenu de celle-ci. En ce qui concerne les titres, il existe quelques pratiques d'accessibilité recommandées :

* Imbriquez les titres dans leur ordre hiérarchique : `<h1>` - `<h6>`
* Ne sautez pas les titres à l'intérieur d'une section
* Utilisez les balises de titres plutôt que du style de texte pour représenter visuellement des titres.

[En lire plus à propos des titres](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-descriptive.html)

```vue-html
<main role="main" aria-labelledby="main-title">
  <h1 id="main-title">Main title</h1>
  <section aria-labelledby="section-title-1">
    <h2 id="section-title-1"> Section Title </h2>
    <h3>Section Subtitle</h3>
    <!-- Contenu -->
  </section>
  <section aria-labelledby="section-title-2">
    <h2 id="section-title-2"> Section Title </h2>
    <h3>Section Subtitle</h3>
    <!-- Contenu -->
    <h3>Section Subtitle</h3>
    <!-- contenu -->
  </section>
</main>
```

### Landmarks {#landmarks}

[Les rôles ARIA landmark](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) permettent d'accéder programmatiquement aux sections d'une application. Les utilisateurs qui s'appuient sur des technologies d'assistance peuvent naviguer vers chaque section de l'application et passer d'un contenu à l'autre. Vous pouvez utiliser les [rôles ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) pour vous aider à atteindre ce résultat.

| HTML    | Rôle ARIA            | But du landmark                                                                                                                |
| ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| header  | role="banner"        | Entête principal : titre de la page.                                                                                           |
| nav     | role="navigation"    | Collection de liens utilisables lors de la navigation dans le document ou vers des documents associés                          |
| main    | role="main"          | Le contenu central ou principal du document.                                                                                   |
| footer  | role="contentinfo"   | Information à propos du document parent : notes de pied de page/copyrights/liens vers la déclaration de confidentialité        |
| aside   | role="complementary" | Supporte le contenu principal, malgré tout est séparé et a du sens par lui-même                                                |
| search  | role="search"        | Cette section contient la fonctionnalité de recherche pour l'application                                                       |
| form    | role="form"          | Collection d'éléments associés à un formulaire                                                                                 |
| section | role="region"        | Contenus pertinents vers lesquels les utilisateurs sont susceptibles de naviguer. Un libellé doit être fourni pour cet élément |

[Aller plus loin à propos des landmarks](https://www.w3.org/TR/wai-aria-1.2/#landmark_roles)

## Formulaires sémantiques {#semantic-forms}

Lors de la création d'un formulaire, vous pouvez utiliser les éléments suivants : `<form>`, `<label>`, `<input>`, `<textarea>`, et `<button>`

Les labels sont en général placés en haut ou à gauche des champs de formulaire :

```vue-html
<form action="/dataCollectionLocation" method="post" autocomplete="on">
  <div v-for="item in formItems" :key="item.id" class="form-item">
    <label :for="item.id">{{ item.label }} : </label>
    <input
      :type="item.type"
      :id="item.id"
      :name="item.id"
      v-model="item.value"
    />
  </div>
  <button type="submit">Submit</button>
</form>
```

Remarquez comment vous pouvez inclure `autocomplete='on'` sur l'élément de formulaire et il sera appliqué à tous les input de votre formulaire. Vous pouvez aussi positionner différentes [valeurs pour l'attribut autocomplete](https://developer.mozilla.org/fr/docs/Web/HTML/Attributes/autocomplete) pour chaque input.

### Labels {#labels}

Utilisez des labels pour décrire le but de chaque contrôle de formulaire ; en liant `for` et `id`.

```vue-html
<label for="name">Name: </label>
<input type="text" name="name" id="name" v-model="name" />
```

Si vous inspectez cet élément dans vos Outils de développement Chrome et que vous ouvrez l'onglet Accessibilité dans l'onglet Éléments, vous verrez comment le champ prend son nom du label :

:::warning Attention :
Vous pourriez avoir vu cette façon d'envelopper un champ de saisie par un label :

```vue-html
<label>
  Name:
  <input type="text" name="name" id="name" v-model="name" />
</label>
```

Associer les labels avec un id correspondant est mieux supporté par les technologies d'assistance.
:::

#### `aria-label` {#aria-label}

Vous pouvez aussi donner un nom accessible au champ avec [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label).

```vue-html
<label for="name">Name: </label>
<input
  type="text"
  name="name"
  id="name"
  v-model="name"
  :aria-label="nameLabel"
/>
```

N'hésitez pas à inspecter cet élément dans les outils de développeur de Chrome pour voir comment le nom accessible a changé :

![Outils de développement de Chrome montrant le nom accessible d'un champs via aria-label](./images/AccessibleARIAlabelDevTools.png)

#### `aria-labelledby` {#aria-labelledby}

Utiliser [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) est similaire à `aria-label` à l'exception du fait que c'est utilisé si le libellé est visible à l'écran. Associez-le à d'autres éléments par leurs `id` et vous pourrez associer plusieurs `id`:

```vue-html
<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <h1 id="billing">Billing</h1>
  <div class="form-item">
    <label for="name">Name: </label>
    <input
      type="text"
      name="name"
      id="name"
      v-model="name"
      aria-labelledby="billing name"
    />
  </div>
  <button type="submit">Submit</button>
</form>
```

![Outils de développeur de Chrome montrant le nom du champs accessible via aria-labelledby](./images/AccessibleARIAlabelledbyDevTools.png)

#### `aria-describedby` {#aria-describedby}

L'attribut [aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby) est utilisé de la même manière que `aria-labelledby` à l'exception qu'il fournit une description avec de l'information supplémentaire pour l'utilisateur. Cela peut être utilisé pour décrire le critère pour n'importe quel champ :

```vue-html
<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <h1 id="billing">Billing</h1>
  <div class="form-item">
    <label for="name">Full Name: </label>
    <input
      type="text"
      name="name"
      id="name"
      v-model="name"
      aria-labelledby="billing name"
      aria-describedby="nameDescription"
    />
    <p id="nameDescription">Please provide first and last name.</p>
  </div>
  <button type="submit">Submit</button>
</form>
```

Vous pouvez voir la description en inspectant depuis les outils de développeur Chrome :

![Outils de développeur Chrome montrant un nom de champs accessible depuis aria-labelledby et décrit avec aria-describedby](./images/AccessibleARIAdescribedby.png)

### Placeholder {#placeholder}

Évitez d'utiliser des placeholders car ils perturbent beaucoup d'utilisateurs.

Un des problèmes avec les placeholders est qu'ils ne remplissent pas les [critères de contraste de couleur](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) par défaut ; corriger le contraste de couleur donne l'impression que le champ est pré-rempli avec une valeur. En regardant l'exemple suivant, vous pouvez voir que le placeholder Last Name conforme aux critères de contraste semble être pré-rempli :

![Placeholder accessible](./images/AccessiblePlaceholder.png)

```vue-html
<form
  class="demo"
  action="/dataCollectionLocation"
  method="post"
  autocomplete="on"
>
  <div v-for="item in formItems" :key="item.id" class="form-item">
    <label :for="item.id">{{ item.label }} : </label>
    <input
      type="text"
      :id="item.id"
      :name="item.id"
      v-model="item.value"
      :placeholder="item.placeholder"
    />
  </div>
  <button type="submit">Submit</button>
</form>
```

```css
/* https://www.w3schools.com/howto/howto_css_placeholder.asp */

#lastName::placeholder {
  /* Chrome, Firefox, Opera, Safari 10.1+ */
  color: black;
  opacity: 1; /* Firefox */
}

#lastName:-ms-input-placeholder {
  /* Internet Explorer 10-11 */
  color: black;
}

#lastName::-ms-input-placeholder {
  /* Microsoft Edge */
  color: black;
}
```

Il vaut mieux fournir toutes les informations dont l'utilisateur a besoin pour remplir les formulaires à l'extérieur des champs de saisie.

### Instructions {#instructions}

Lorsque vous ajoutez des instructions pour vos champs de saisie, assurez-vous de les associer correctement aux champs de saisie.
Vous pouvez fournir des instructions complémentaires et associer plusieurs ids à l'intérieur d'un [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby). Cela permet un design plus flexible.

```vue-html
<fieldset>
  <legend>Using aria-labelledby</legend>
  <label id="date-label" for="date">Current Date: </label>
  <input
    type="date"
    name="date"
    id="date"
    aria-labelledby="date-label date-instructions"
  />
  <p id="date-instructions">MM/DD/YYYY</p>
</fieldset>
```

De façon alternative, vous pouvez attacher les instructions au champ avec [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby):

```vue-html
<fieldset>
  <legend>En utilisant aria-describedby</legend>
  <label id="dob" for="dob">Date de naissance : </label>
  <input type="date" name="dob" id="dob" aria-describedby="dob-instructions" />
  <p id="dob-instructions">DD/MM/YYYY</p>
</fieldset>
```

### Cacher du contenu {#hiding-content}

En règle générale, il n'est pas recommandé de cacher visuellement des labels, même si le champ est un nom accessible. Cependant, si la fonctionnalité du champ peut être comprise à l'aide du contenu alentour, alors, nous pouvons cacher le libellé visuel.

Regardons ce champ de recherche :

```vue-html
<form role="search">
  <label for="search" class="hidden-visually">Search: </label>
  <input type="text" name="search" id="search" v-model="search" />
  <button type="submit">Search</button>
</form>
```

Nous pouvons faire cela, car le bouton de recherche va aider les utilisateurs visuels à identifier le but du champ de saisie.

Nous pouvons utiliser du CSS pour cacher visuellement des éléments, mais les laisser disponibles pour les technologies d'assistance :

```css
.hidden-visually {
  position: absolute;
  overflow: hidden;
  white-space: nowrap;
  margin: 0;
  padding: 0;
  height: 1px;
  width: 1px;
  clip: rect(0 0 0 0);
  clip-path: inset(100%);
}
```

#### `aria-hidden="true"` {#aria-hidden-true}

Ajouter `aria-hidden="true"` va cacher l'élément aux technologies d'assistance, mais les laissera disponibles visuellement pour les autres utilisateurs. Ne l'utilisez pas pour des éléments sur lesquels il est possible de faire le focus, uniquement sur des éléments décoratifs ou du contenu hors écran.

```vue-html
<p>This is not hidden from screen readers.</p>
<p aria-hidden="true">This is hidden from screen readers.</p>
```

### Boutons {#buttons}

Lorsque vous utilisez des boutons à l'intérieur d'un formulaire, vous devez en indiquer le type afin d'éviter la soumission du formulaire.
Vous pouvez aussi utiliser un input pour créer des boutons :

```vue-html
<form action="/dataCollectionLocation" method="post" autocomplete="on">
  <!-- Boutons -->
  <button type="button">Cancel</button>
  <button type="submit">Submit</button>

  <!-- Input buttons -->
  <input type="button" value="Cancel" />
  <input type="submit" value="Submit" />
</form>
```

### Images fonctionnelles {#functional-images}

Vous pouvez utiliser cette technique pour créer des images fonctionnelles.

* Champs de saisie

  * Ces images feront office de boutons de soumission pour les formulaires

  ```vue-html
  <form role="search">
    <label for="search" class="hidden-visually">Search: </label>
    <input type="text" name="search" id="search" v-model="search" />
    <input
      type="image"
      class="btnImg"
      src="https://img.icons8.com/search"
      alt="Search"
    />
  </form>
  ```

* Icônes

```vue-html
<form role="search">
  <label for="searchIcon" class="hidden-visually">Search: </label>
  <input type="text" name="searchIcon" id="searchIcon" v-model="searchIcon" />
  <button type="submit">
    <i class="fas fa-search" aria-hidden="true"></i>
    <span class="hidden-visually">Search</span>
  </button>
</form>
```

## Standards {#standards}

Le World Wide Web Consortium (W3C) Web Accessibility Initiative (WAI) développe les standards d'accessibilité pour les différents composants :

* [User Agent Accessibility Guidelines (UAAG)](https://www.w3.org/WAI/standards-guidelines/uaag/)
  * navigateurs web et lecteurs de média, incluant certains aspects de technologies d'assistance
* [Authoring Tool Accessibility Guidelines (ATAG)](https://www.w3.org/WAI/standards-guidelines/atag/)
  * outils de création de contenu
* [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/)
  * contenu web - utilisé par des développeurs, outils de création de contenu, outils d'évaluation d'accessibilité

### Web Content Accessibility Guidelines (WCAG) {#web-content-accessibility-guidelines-wcag}

[WCAG 2.1](https://www.w3.org/TR/WCAG21/) étend [WCAG 2.0](https://www.w3.org/TR/WCAG20/) et permet l'implémentation de nouvelles technologies en tenant compte de l'évolution du web. Le W3C encourage l'utilisation de la version la plus récente de WCAG lors du développement ou de la mise à jour de vos pratiques d'accessibilité Web.

#### WCAG 2.1 Quatre principaux principes de guidance (POUR en abrégé) : {#wcag-2-1-four-main-guiding-principles-abbreviated-as-pour}

* [Perceptible](https://www.w3.org/TR/WCAG21/#perceivable)
  * Les utilisateurs doivent être capables de percevoir l'information qui leur est présentée
* [Utilisable](https://www.w3.org/TR/WCAG21/#operable)
  * Les formulaires, contrôles et navigation de l'interface sont utilisables
* [Compréhensible](https://www.w3.org/TR/WCAG21/#understandable)
  * Les informations et l’utilisation de l’interface utilisateur doivent être compréhensibles par tous les utilisateurs
* [Robuste](https://www.w3.org/TR/WCAG21/#robust)
  * Les utilisateurs doivent pouvoir continuer d'accéder au contenu au fur et à mesure que la technologie avance

#### Web Accessibility Initiative – Accessible Rich Internet Applications (WAI-ARIA) {#web-accessibility-initiative-–-accessible-rich-internet-applications-wai-aria}

WAI-ARIA du W3C fournit des conseils sur comment construire du contenu dynamique et des contrôles avancés d'interface utilisateur.

* [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/)
* [WAI-ARIA Authoring Practices 1.2](https://www.w3.org/TR/wai-aria-practices-1.2/)

## Resources {#resources}

### Documentation {#documentation}

* [WCAG 2.0](https://www.w3.org/TR/WCAG20/)
* [WCAG 2.1](https://www.w3.org/TR/WCAG21/)
* [Accessible Rich Internet Applications (WAI-ARIA) 1.2](https://www.w3.org/TR/wai-aria-1.2/)
* [WAI-ARIA Authoring Practices 1.2](https://www.w3.org/TR/wai-aria-practices-1.2/)

### Technologies d'assistance {#assistive-technologies}

* Liseurs d'écran
  * [NVDA](https://www.nvaccess.org/download/)
  * [VoiceOver](https://www.apple.com/accessibility/mac/vision/)
  * [JAWS](https://www.freedomscientific.com/products/software/jaws/?utm_term=jaws%20screen%20reader\&utm_source=adwords\&utm_campaign=All+Products\&utm_medium=ppc\&hsa_tgt=kwd-394361346638\&hsa_cam=200218713\&hsa_ad=296201131673\&hsa_kw=jaws%20screen%20reader\&hsa_grp=52663682111\&hsa_net=adwords\&hsa_mt=e\&hsa_src=g\&hsa_acc=1684996396\&hsa_ver=3\&gclid=Cj0KCQjwnv71BRCOARIsAIkxW9HXKQ6kKNQD0q8a_1TXSJXnIuUyb65KJeTWmtS6BH96-5he9dsNq6oaAh6UEALw_wcB)
  * [ChromeVox](https://chrome.google.com/webstore/detail/chromevox-classic-extensi/kgejglhpjiefppelpmljglcjbhoiplfn?hl=en)
* Outils de loupe
  * [MAGic](https://www.freedomscientific.com/products/software/magic/)
  * [ZoomText](https://www.freedomscientific.com/products/software/zoomtext/)
  * [Magnifier](https://support.microsoft.com/fr/help/11542/windows-use-magnifier-to-make-things-easier-to-see)

### Tester l'accessibilité {#testing}

* Outils automatisés
  * [Lighthouse](https://chrome.google.com/webstore/detail/lighthouse/blipmdconlkpinefehnmjammfjpmpbjk)
  * [WAVE](https://chrome.google.com/webstore/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh)
  * [ARC Toolkit](https://chrome.google.com/webstore/detail/arc-toolkit/chdkkkccnlfncngelccgbgfmjebmkmce?hl=fr)
* Outils de vérification des couleurs
  * [WebAim Color Contrast](https://webaim.org/resources/contrastchecker/)
  * [WebAim Link Color Contrast](https://webaim.org/resources/linkcontrastchecker)
* Autres outils utiles
  * [HeadingMap](https://chrome.google.com/webstore/detail/headingsmap/flbjommegcjonpdmenkdiocclhjacmbi?hl=fr-FR)
  * [Color Oracle](https://colororacle.org)
  * [NerdeFocus](https://chrome.google.com/webstore/detail/nerdefocus/lpfiljldhgjecfepfljnbjnbjfhennpd?hl=fr-FR)
  * [Visual Aria](https://chrome.google.com/webstore/detail/visual-aria/lhbmajchkkmakajkjenkchhnhbadmhmk?hl=fr-FR)
  * [Simulateur d'accessibilité de site web Silktide](https://chrome.google.com/webstore/detail/silktide-website-accessib/okcpiimdfkpkjcbihbmhppldhiebhhaf?hl=fr-FR)

### Utilisateurs {#users}

L'Organisation Mondiale de la Santé estime que 15% de la population mondiale est atteinte d'une forme de handicap, 2-4% d'entre elle de handicaps sévères. Ceci est estimé à 1 milliard de personnes dans le monde ; faisant des personnes avec un handicap la plus grande minorité au monde.

Il y a un large spectre de handicaps, qui peut être divisé grosso-modo en quatre catégories :

* *[Visuel](https://webaim.org/articles/visual/)* - Ces utilisateurs peuvent bénéficier de l'utilisation de liseurs d'écran, d'outils d'agrandissement, du contrôle du contraste ou de plage braille.
* *[Auditif](https://webaim.org/articles/auditory/)* - Ces utilisateurs peuvent bénéficier de sous-titres, de transcriptions ou de vidéos en langages des signes.
* *[Moteur](https://webaim.org/articles/motor/)* - Ces utilisateurs peuvent bénéficier d'un large spectre de [technologies d'assistance pour les assistive technologies for handicaps moteurs ](https://webaim.org/articles/motor/assistive) : logiciels de reconnaissance vocale, eye tracking, accès par bouton unique, head wand, sip and puff switch, souris trackball surdimensionnée, clavier adaptatif ou autres technologies d'assistance.
* *[Cognitif](https://webaim.org/articles/cognitive/)* - Ces utilisateurs peuvent bénéficier de média supplémentaire, d'une organisation structurelle du contenu, d'un style d'écriture clair et simple.

Rendez-vous aux liens suivants de WebAim pour comprendre via des retours d'expérience d'utilisateurs :

* [Perspectives sur l'accessibilité du Web : En explorer les impacts et bénéfices pour tous](https://www.w3.org/WAI/perspective-videos/)
* [Histoires d'utilisateurs du Web](https://www.w3.org/WAI/people-use-web/user-stories/)

---

---
url: /api.md
---


---

---
url: /api/reactivity-advanced.md
---
# API de la réactivité : Avancé {#reactivity-api-advanced}

## shallowRef() {#shallowref}

Version partiellement réactive de [`ref()`](./reactivity-core#ref).

* **Type :**

  ```ts
  function shallowRef<T>(value: T): ShallowRef<T>

  interface ShallowRef<T> {
    value: T
  }
  ```

* **Détails**

  Contrairement à `ref()`, la valeur interne d'une ref partiellement réactive est stockée et exposée telle quelle, et ne sera pas rendue profondément réactive. Seul l'accès `.value` est réactif.

  `shallowRef()` est généralement utilisée pour l'optimisation des performances de grandes structures de données ou l'intégration avec des systèmes de gestion d'état externes.

* **Exemple**

  ```js
  const state = shallowRef({ count: 1 })

  // ne déclenche PAS de changement
  state.value.count = 2

  // déclenche un changement
  state.value = { count: 2 }
  ```

* **Voir aussi**
  * [Guide - Réduire la surcharge de réactivité pour les grandes structures immuables](/guide/best-practices/performance#reduce-reactivity-overhead-for-large-immutable-structures)
  * [Guide - Intégration avec des systèmes externes de gestion d'état](/guide/extras/reactivity-in-depth#integration-with-external-state-systems)

## triggerRef() {#triggerref}

Force le déclenchement d'effets qui dépendent d'une [ref partiellement réactive](#shallowref). Ceci est généralement utilisé après avoir effectué des mutations profondes sur la valeur interne d'une ref partiellement réactive.

* **Type :**

  ```ts
  function triggerRef(ref: ShallowRef): void
  ```

* **Exemple**

  ```js
  const shallow = shallowRef({
    greet: 'Hello, world'
  })

  // Logue "Hello, world" une fois pour la première exécution
  watchEffect(() => {
    console.log(shallow.value.greet)
  })

  // Cela ne déclenchera pas l'effet car la ref est partiellement réactive
  shallow.value.greet = 'Hello, universe'

  // Logue "Hello, universe"
  triggerRef(shallow)
  ```

## customRef() {#customref}

Crée une ref personnalisée avec un contrôle explicite sur son suivi des dépendances et le déclenchement des mises à jour.

* **Type :**

  ```ts
  function customRef<T>(factory: CustomRefFactory<T>): Ref<T>

  type CustomRefFactory<T> = (
    track: () => void,
    trigger: () => void
  ) => {
    get: () => T
    set: (value: T) => void
  }
  ```

* **Détails**

  `customRef()` attend une fonction *factory*, qui reçoit les fonctions `track` et `trigger` comme arguments et doit renvoyer un objet avec les méthodes `get` et `set`.

  En général, `track()` doit être appelée à l'intérieur de `get()`, et `trigger()` doit être appelée à l'intérieur de `set()`. Cependant, vous avez un contrôle total sur le moment où elles doivent être appelées.

* **Exemple**

  Création d'une ref *debounced* qui ne met à jour la valeur qu'après un certain délai après le dernier appel défini :

  ```js
  import { customRef } from 'vue'

  export function useDebouncedRef(value, delay = 200) {
    let timeout
    return customRef((track, trigger) => {
      return {
        get() {
          track()
          return value
        },
        set(newValue) {
          clearTimeout(timeout)
          timeout = setTimeout(() => {
            value = newValue
            trigger()
          }, delay)
        }
      }
    })
  }
  ```

  Utilisation dans un composant :

  ```vue
  <script setup>
  import { useDebouncedRef } from './debouncedRef'
  const text = useDebouncedRef('hello')
  </script>

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

  [Essayer en ligne](https://play.vuejs.org/#eNplUkFugzAQ/MqKC1SiIekxIpEq9QVV1BMXCguhBdsyaxqE/PcuGAhNfYGd3Z0ZDwzeq1K7zqB39OI205UiaJGMOieiapTUBAOYFt/wUxqRYf6OBVgotGzA30X5Bt59tX4iMilaAsIbwelxMfCvWNfSD+Gw3++fEhFHTpLFuCBsVJ0ScgUQjw6Az+VatY5PiroHo3IeaeHANlkrh7Qg1NBL43cILUmlMAfqVSXK40QUOSYmHAZHZO0KVkIZgu65kTnWp8Qb+4kHEXfjaDXkhd7DTTmuNZ7MsGyzDYbz5CgSgbdppOBFqqT4l0eX1gZDYOm057heOBQYRl81coZVg9LQWGr+IlrchYKAdJp9h0C6KkvUT3A6u8V1dq4ASqRgZnVnWg04/QWYNyYzC2rD5Y3/hkDgz8fY/cOT1ZjqizMZzGY3rDPC12KGZYyd3J26M8ny1KKx7c3X25q1c1wrZN3L9LCMWs/+AmeG6xI=)

  :::warning À utiliser avec précaution
  Lorsque l'on utilise une ref personnalisée, il convient d'être prudent quant à la valeur de retour de son accesseur, en particulier lorsque l'on génère de nouveaux types de données d'objets à chaque fois que le getter est exécuté. Cela affecte la relation entre les composants parent et enfant, lorsqu'une ref a été transmise en tant que prop.

  La fonction de rendu du composant parent pourrait être déclenchée par des changements dans un état réactif différent. Pendant le rendu, la valeur de notre ref personnalisée est réévaluée, renvoyant un nouveau type de données d'objet en tant que prop à un composant enfant. Cette prop est comparé à sa dernière valeur dans le composant enfant, et comme ils sont différents, les dépendances réactives de la ref personnalisée sont déclenchées dans le composant enfant. Pendant ce temps, les dépendances réactives du composant parent ne s'exécutent pas car le mutateur de la ref n'a pas été appelé et ses dépendances n'ont pas été déclenchées en conséquence.

  [Essayer en ligne](https://play.vuejs.org/#eNqFVEtP3DAQ/itTS9Vm1ZCt1J6WBZUiDvTQIsoNcwiOkzU4tmU7+9Aq/71jO1mCWuhlN/PyfPP45kAujCk2HSdLsnLMCuPBcd+Zc6pEa7T1cADWOa/bW17nYMPPtvRsDT3UVrcww+DZ0flStybpKSkWQQqPU0IVVUwr58FYvdvDWXgpu6ek1pqSHL0fS0vJw/z0xbN1jUPHY/Ys87Zkzzl4K5qG2zmcnUN2oAqg4T6bQ/wENKNXNk+CxWKsSlmLTSk7XlhedYxnWclYDiK+MkQCoK4wnVtnIiBJuuEJNA2qPof7hzkEoc8DXgg9yzYTBBFgNr4xyY4FbaK2p6qfI0iqFgtgulOe27HyQRy69Dk1JXY9C03JIeQ6wg4xWvJCqFpnlNytOcyC2wzYulQNr0Ao+Mhw0KnTTEttl/CIaIJiMz8NGBHFtYetVrPwa58/IL48Zag4N0ssquNYLYBoW16J0vOkC3VQtVqk7cG9QcHz1kj0QAlgVYkNMFk6d0bJ1pbGYKUkmtD42HmvFfi94WhOEiXwjUnBnlEz9OLTJwy5qCo44D4O7en71SIFjI/F9VuG4jEy/GHQKq5hQrJAKOc4uNVighBF5/cygS0GgOMoK+HQb7+EWvLdMM7weVIJy5kXWi0Rj+xaNRhLKRp1IvB9hxYegA6WJ1xkUe9PcF4e9a+suA3YwYiC5MQ79KlFUzw5rZCZEUtoRWuE5PaXCXmxtuWIkpJSSr39EXXHQcWYNWfP/9A/uV3QUXJjueN2E1ZhtPnSIqGS+er3T77D76Ox1VUn0fsd4y3HfewCxuT2vVMVwp74RbTX8WQI1dy5qx12xI1Fpa1K5AreeEHCCN8q/QXul+LrSC3s4nh93jltkVPDIYt5KJkcIKStCReo4rVQ/CZI6dyEzToCCJu7hAtry/1QH/qXncQB400KJwqPxZHxEyona0xS/E3rt1m9Ld1rZl+uhaxecRtP3EjtgddCyimtXyj9H/Ii3eId7uOGTkyk/wOEbQ9h)

  :::

  :::warning Use with caution
  When using customRef, we should be cautious about the return value of its getter, particularly when generating new object datatypes each time the getter is run. This affects the relationship between parent and child components, where such a customRef has been passed as a prop.

  The parent component's render function could be triggered by changes to a different reactive state. During rerender, the value of our customRef is reevaluated, returning a new object datatype as a prop to a child component. This prop is compared with its last value in the child component, and since they are different, the reactive dependencies of the customRef are triggered in the child component. Meanwhile, the reactive dependencies in the parent component do not run because the customRef's setter was not called, and its dependencies were not triggered as a result.

  [See it in the Playground](https://play.vuejs.org/#eNqFVEtP3DAQ/itTS9Vm1ZCt1J6WBZUiDvTQIsoNcwiOkzU4tmU7+9Aq/71jO1mCWuhlN/PyfPP45kAujCk2HSdLsnLMCuPBcd+Zc6pEa7T1cADWOa/bW17nYMPPtvRsDT3UVrcww+DZ0flStybpKSkWQQqPU0IVVUwr58FYvdvDWXgpu6ek1pqSHL0fS0vJw/z0xbN1jUPHY/Ys87Zkzzl4K5qG2zmcnUN2oAqg4T6bQ/wENKNXNk+CxWKsSlmLTSk7XlhedYxnWclYDiK+MkQCoK4wnVtnIiBJuuEJNA2qPof7hzkEoc8DXgg9yzYTBBFgNr4xyY4FbaK2p6qfI0iqFgtgulOe27HyQRy69Dk1JXY9C03JIeQ6wg4xWvJCqFpnlNytOcyC2wzYulQNr0Ao+Mhw0KnTTEttl/CIaIJiMz8NGBHFtYetVrPwa58/IL48Zag4N0ssquNYLYBoW16J0vOkC3VQtVqk7cG9QcHz1kj0QAlgVYkNMFk6d0bJ1pbGYKUkmtD42HmvFfi94WhOEiXwjUnBnlEz9OLTJwy5qCo44D4O7en71SIFjI/F9VuG4jEy/GHQKq5hQrJAKOc4uNVighBF5/cygS0GgOMoK+HQb7+EWvLdMM7weVIJy5kXWi0Rj+xaNRhLKRp1IvB9hxYegA6WJ1xkUe9PcF4e9a+suA3YwYiC5MQ79KlFUzw5rZCZEUtoRWuE5PaXCXmxtuWIkpJSSr39EXXHQcWYNWfP/9A/uV3QUXJjueN2E1ZhtPnSIqGS+er3T77D76Ox1VUn0fsd4y3HfewCxuT2vVMVwp74RbTX8WQI1dy5qx12xI1Fpa1K5AreeEHCCN8q/QXul+LrSC3s4nh93jltkVPDIYt5KJkcIKStCReo4rVQ/CZI6dyEzToCCJu7hAtry/1QH/qXncQB400KJwqPxZHxEyona0xS/E3rt1m9Ld1rZl+uhaxecRtP3EjtgddCyimtXyj9H/Ii3eId7uOGTkyk/wOEbQ9h)

  :::

## shallowReactive() {#shallowreactive}

Version partiellement réactive de [`reactive()`](./reactivity-core#reactive).

* **Type :**

  ```ts
  function shallowReactive<T extends object>(target: T): T
  ```

* **Détails**

  Contrairement à `reactive()`, il n'y a pas de conversion profonde : seules les propriétés de niveau racine sont réactives pour un objet partiellement réactif. Les valeurs de propriété sont stockées et exposées telles quelles - cela signifie également que les propriétés avec des valeurs de ref ne seront **pas** automatiquement déballées.

  :::warning À utiliser avec précaution
  Les structures de données partiellement réactives ne doivent être utilisées que pour l'état de niveau racine dans un composant. Évitez de l'imbriquer dans un objet réactif profond car cela crée un arbre avec un comportement de réactivité incohérent qui peut être difficile à comprendre et à déboguer.
  :::

* **Exemple**

  ```js
  const state = shallowReactive({
    foo: 1,
    nested: {
      bar: 2
    }
  })

  // muter les propriétés propres de l'état est réactif
  state.foo++

  // ...mais ne convertit pas les objets imbriqués
  isReactive(state.nested) // false

  // PAS réactif
  state.nested.bar++
  ```

## shallowReadonly() {#shallowreadonly}

Version partiellement réactive de [`readonly()`](./reactivity-core#readonly).

* **Type :**

  ```ts
  function shallowReadonly<T extends object>(target: T): Readonly<T>
  ```

* **Détails**

  Contrairement à `readonly()`, il n'y a pas de conversion profonde : seules les propriétés de niveau racine sont en lecture seule. Les valeurs de propriété sont stockées et exposées telles quelles - cela signifie également que les propriétés avec des valeurs de ref ne seront **pas** automatiquement déballées.

  :::warning À utiliser avec précaution
  Les structures de données partiellement réactives ne doivent être utilisées que pour l'état de niveau racine dans un composant. Évitez de l'imbriquer dans un objet réactif profond car cela crée un arbre avec un comportement de réactivité incohérent qui peut être difficile à comprendre et à déboguer.
  :::

* **Exemple**

  ```js
  const state = shallowReadonly({
    foo: 1,
    nested: {
      bar: 2
    }
  })

  // muter les propriétés propres de l'état va échouer
  state.foo++

  // ...mais fonctionne sur des objets imbriqués
  isReadonly(state.nested) // false

  // fonctione
  state.nested.bar++
  ```

## toRaw() {#toraw}

Renvoie l'objet brut d'origine d'un proxy créé par Vue.

* **Type :**

  ```ts
  function toRaw<T>(proxy: T): T
  ```

* **Détails**

  `toRaw()` peut renvoyer l'objet d'origine à partir de proxys créés par [`reactive()`](./reactivity-core#reactive), [`readonly()`](./reactivity-core#readonly), [`shallowReactive()`](#shallowreactive) ou [`shallowReadonly()`](#shallowreadonly).

  Il s'agit d'une solution d'échappement qui peut être utilisée pour lire temporairement sans encourir d'accès au proxy / de surcharge de suivi ou pour écrire sans déclencher de modifications. Il n'est **pas** recommandé de conserver une ref persistante à l'objet d'origine. À utiliser avec précaution.

* **Exemple**

  ```js
  const foo = {}
  const reactiveFoo = reactive(foo)

  console.log(toRaw(reactiveFoo) === foo) // true
  ```

## markRaw() {#markraw}

Marque un objet afin qu'il ne soit jamais converti en proxy. Renvoie l'objet lui-même.

* **Type :**

  ```ts
  function markRaw<T extends object>(value: T): T
  ```

* **Exemple**

  ```js
  const foo = markRaw({})
  console.log(isReactive(reactive(foo))) // false

  // fonctionne également lorsqu'il est imbriqué dans d'autres objets réactifs
  const bar = reactive({ foo })
  console.log(isReactive(bar.foo)) // false
  ```

  :::warning À utiliser avec précaution
  `markRaw()` et les API partiellement réactives telles que `shallowReactive()` vous permettent de désactiver de manière sélective la conversion profonde réactive/lecture seule par défaut et d'intégrer des objets bruts sans proxy dans votre graphe d'état. Elles peuvent être utilisées pour diverses raisons :

  * Certaines valeurs ne doivent tout simplement pas être rendues réactives, par exemple une instance de classe tierce complexe ou un objet de composant Vue.

  * Ignorer la conversion proxy peut améliorer les performances lors du rendu de grandes listes avec des sources de données immuables.

  Elles sont considérées comme avancées car l'objet brut n'est défini qu'au niveau racine, donc si vous définissez un objet brut imbriqué et non marqué comme brut dans un objet réactif, puis y accédez à nouveau, vous récupérez la version proxyfiée. Cela peut entraîner des **risques d'identité** - par exemple effectuer une opération qui repose sur l'identité de l'objet mais en utilisant à la fois la version brute et la version proxyfiée du même objet :

  ```js
  const foo = markRaw({
    nested: {}
  })

  const bar = reactive({
    // bien que `foo` soit marqué comme brut, foo.nested ne l'est pas.
    nested: foo.nested
  })

  console.log(foo.nested === bar.nested) // false
  ```

  Les risques d'identité sont en général rares. Cependant, pour utiliser correctement ces API tout en évitant en toute sécurité les risques d'identité, il faut une solide compréhension du fonctionnement du système de réactivité.

  :::

## effectScope() {#effectscope}

Crée un objet de portée d'effet qui peut capturer les effets réactifs (c'est-à-dire les propriétés calculées et les observateurs) créés en son sein afin que ces effets puissent être disposés. Pour des cas d'utilisation détaillés de cette API, veuillez consulter son [RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0041-reactivity-effect-scope.md) correspondant.

* **Type :**

  ```ts
  function effectScope(detached?: boolean): EffectScope

  interface EffectScope {
    run<T>(fn: () => T): T | undefined // undefined si le scope est inactif
    stop(): void
  }
  ```

* **Exemple**

  ```js
  const scope = effectScope()

  scope.run(() => {
    const doubled = computed(() => counter.value * 2)

    watch(doubled, () => console.log(doubled.value))

    watchEffect(() => console.log('Count: ', doubled.value))
  })

  // pour disposer tous les effets du scope
  scope.stop()
  ```

## getCurrentScope() {#getcurrentscope}

Renvoie la [portée d'effet](#effectscope) active actuelle s'il y en a une.

* **Type :**

  ```ts
  function getCurrentScope(): EffectScope | undefined
  ```

## onScopeDispose() {#onscopedispose}

Enregistre une fonction de suppression sur la [portée d'effet](#effectscope) active actuelle. La fonction sera appelée lorsque la portée d'effet associée sera arrêtée.

Cette méthode peut être utilisée comme remplacement non couplé à un composant de `onUnmount` dans les fonctions de composition réutilisables, puisque la fonction `setup()` de chaque composant Vue est également invoquée dans une portée d'effet.

Un avertissement sera levé si la fonction est appelée sans d'effect scope actif. À partir de la version 3.5, cet avertissement peut être désactivé en passant `tre` au second argument.

* **Type :**

  ```ts
  function onScopeDispose(fn: () => void, failSilently?: boolean): void
  ```

---

---
url: /api/reactivity-core.md
---
# API de la réactivité : Essentiel {#reactivity-api-core}

:::info Voir aussi
Pour mieux comprendre les API de réactivité, il est recommandé de lire les chapitres suivants du guide :

* [Fondamentaux de la réactivité](/guide/essentials/reactivity-fundamentals) (avec la préférence API définie sur Composition API)
* [La réactivité en détails](/guide/extras/reactivity-in-depth)
  :::

## ref() {#ref}

Prend une valeur interne et retourne un objet ref réactif et mutable, qui n'a qu'une seule propriété `.value` pointant sur la valeur interne.

* **Type :**

  ```ts
  function ref<T>(value: T): Ref<UnwrapRef<T>>

  interface Ref<T> {
    value: T
  }
  ```

* **Détails**

  L'objet ref est mutable - c'est-à-dire que vous pouvez attribuer de nouvelles valeurs à `.value`. Il est également réactif - c'est-à-dire que toute lecture de `.value` est traquée, et que les opérations d'écriture déclenchent les effets associés.

  Si un objet est assigné comme valeur d'une ref, l'objet est rendu profondément réactif via [reactive()](#reactive). Cela signifie également que si l'objet contient des refs imbriquées, elles seront déballées en profondeur.

  Pour éviter la conversion profonde, utilisez plutôt [`shallowRef()`](./reactivity-advanced#shallowref).

* **Exemple**

  ```js
  const count = ref(0)
  console.log(count.value) // 0

  count.value = 1
  console.log(count.value) // 1
  ```

* **Voir aussi**
  * [Guide - Les fondamentaux de la réactivité avec `ref()`](/guide/essentials/reactivity-fundamentals#ref)
  * [Guide - Typer `ref()`](/guide/typescript/composition-api#typing-ref)&#x20;

## computed() {#computed}

Prend une fonction [accesseur](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Functions/get#description) et retourne un objet [ref](#ref) réactif en lecture seule pour la valeur retournée par la fonction acesseur. Elle peut aussi prendre un objet avec les fonctions `get` et `set` pour créer un objet ref modifiable.

* **Type :**

  ```ts
  // lecture seule
  function computed<T>(
    getter: (oldValue: T | undefined) => T,
    // voir "Débogage des propriétés calculées" plus bas
    debuggerOptions?: DebuggerOptions
  ): Readonly<Ref<Readonly<T>>>

  // modifiable
  function computed<T>(
    options: {
      get: (oldValue: T | undefined) => T
      set: (value: T) => void
    },
    debuggerOptions?: DebuggerOptions
  ): Ref<T>
  ```

* **Exemple**

  Création d'une ref d'une propriété calculée en lecture seule :

  ```js
  const count = ref(1)
  const plusOne = computed(() => count.value + 1)

  console.log(plusOne.value) // 2

  plusOne.value++ // erreur
  ```

  Création d'une ref d'une propriété calculée modifiable :

  ```js
  const count = ref(1)
  const plusOne = computed({
    get: () => count.value + 1,
    set: (val) => {
      count.value = val - 1
    }
  })

  plusOne.value = 1
  console.log(count.value) // 0
  ```

  Débogage :

  ```js
  const plusOne = computed(() => count.value + 1, {
    onTrack(e) {
      debugger
    },
    onTrigger(e) {
      debugger
    }
  })
  ```

* **Voir aussi**
  * [Guide - Propriétés calculées](/guide/essentials/computed)
  * [Guide - Débogage des propriétés calculées](/guide/extras/reactivity-in-depth#computed-debugging)
  * [Guide - Typer `computed()`](/guide/typescript/composition-api#typing-computed)&#x20;
  * [Guide - Performance - Stabilité des Computed](/guide/best-practices/performance#computed-stability)

## reactive() {#reactive}

Retourne un proxy réactif de l'objet.

* **Type :**

  ```ts
  function reactive<T extends object>(target: T): UnwrapNestedRefs<T>
  ```

* **Détails**

  La conversion réactive est "profonde" : elle affecte toutes les propriétés imbriquées. Un objet réactif déballe également en profondeur toutes les propriétés qui sont des [refs](#ref) tout en maintenant la réactivité.

  Il faut également noter qu'il n'y a pas de déballage de refs lorsque la ref est accédée en tant qu'élément d'un tableau réactif ou d'un type de collection natif comme `Map`.

  Pour éviter la conversion profonde et ne conserver la réactivité qu'au niveau de la racine, utilisez plutôt [shallowReactive()](./reactivity-advanced#shallowreactive).

  L'objet retourné et ses objets imbriqués sont enveloppés par un [proxy ES](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Proxy) et **non** égaux aux objets originaux. Il est recommandé de travailler exclusivement avec le proxy réactif et d'éviter de se fier à l'objet original.

* **Exemple**

  Création d'un objet réactif :

  ```js
  const obj = reactive({ count: 0 })
  obj.count++
  ```

  Déballage de refs :

  ```ts
  const count = ref(1)
  const obj = reactive({ count })

  // la ref sera déballée
  console.log(obj.count === count.value) // true

  // cela va mettre à jour `obj.count`
  count.value++
  console.log(count.value) // 2
  console.log(obj.count) // 2

  // la ref `count` va également être mise à jour
  obj.count++
  console.log(obj.count) // 3
  console.log(count.value) // 3
  ```

  Notez que les refs ne sont **pas** déballées lorsqu'on y accède en tant qu'éléments de tableau ou de collection :

  ```js
  const books = reactive([ref('Vue 3 Guide')])
  // besoin d'utiliser .value ici
  console.log(books[0].value)

  const map = reactive(new Map([['count', ref(0)]]))
  // besoin d'utiliser .value ici
  console.log(map.get('count').value)
  ```

  Lorsque vous assignez une [ref](#ref) à une propriété `reactive`, cette ref sera également automatiquement déballée :

  ```ts
  const count = ref(1)
  const obj = reactive({})

  obj.count = count

  console.log(obj.count) // 1
  console.log(obj.count === count.value) // true
  ```

* **Voir aussi**
  * [Guide - Fondamentaux de la réactivité](/guide/essentials/reactivity-fundamentals)
  * [Guide - Typer `reactive()`](/guide/typescript/composition-api#typing-reactive)&#x20;

## readonly() {#readonly}

Prend un objet (réactif ou simple) ou une [ref](#ref) et renvoie un proxy en lecture seule vers l'original.

* **Type :**

  ```ts
  function readonly<T extends object>(
    target: T
  ): DeepReadonly<UnwrapNestedRefs<T>>
  ```

* **Détails**

  Un proxy en lecture seule est profond : toute propriété imbriquée à laquelle on accède sera également en lecture seule. Il a également le même comportement en termes de déballage que `reactive()`, sauf que les valeurs déballées seront aussi en lecture seule.

  Pour éviter la conversion profonde, utilisez plutôt [shallowReadonly()](./reactivity-advanced#shallowreadonly).

* **Exemple**

  ```js
  const original = reactive({ count: 0 })

  const copy = readonly(original)

  watchEffect(() => {
    // fonctionne pour le suivi de la réactivité
    console.log(copy.count)
  })

  // La mutation de l'original déclenchera les observateurs qui s'appuient sur la copie
  original.count++

  // la mutation de la copie échouera et donnera lieu à un avertissement
  copy.count++ // avertissement !
  ```

## watchEffect() {#watcheffect}

Exécute immédiatement une fonction tout en suivant de manière réactive ses dépendances et la ré-exécute dès que les dépendances sont modifiées.

* **Type :**

  ```ts
  function watchEffect(
    effect: (onCleanup: OnCleanup) => void,
    options?: WatchEffectOptions
  ): WatchHandle

  type OnCleanup = (cleanupFn: () => void) => void

  interface WatchEffectOptions {
    flush?: 'pre' | 'post' | 'sync' // par défaut : 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
  }

  interface WatchHandle {
    (): void // appelable, comme `stop`
    pause: () => void
    resume: () => void
    stop: () => void
  }
  ```

* **Détails**

  Le premier argument est la fonction à exécuter qui reçoit elle-même en argument une fonction qui peut être utilisée pour enregistrer une fonction de nettoyage. La fonction de nettoyage sera appelée juste avant la prochaine exécution de l'effet, et peut être utilisé pour nettoyer les effets de bord invalidés, par exemple une requête asynchrone en attente (voir l'exemple ci-dessous).

  Le second argument est un objet optionnel d'options qui peut être utilisé pour ajuster le timing du nettoyage de l'effet ou pour déboguer ses dépendances.

  Par défaut, les observateurs seront exécutés juste avant le rendu du composant. Définir `flush: 'post'` reportera l'exécution du watcher après le rendu du composant. Voir le paragraphe sur [le timing du nettoyage des fonctions de rappel](/guide/essentials/watchers#callback-flush-timing) pour plus d'informations. Dans de rares cas, il peut être nécessaire de déclencher un observateur immédiatement lorsqu'une dépendance réactive change, par exemple pour invalider un cache. Ceci peut être réalisé en utilisant `flush: 'sync'`. Cependant, ce paramètre doit être utilisé avec prudence, car il peut entraîner des problèmes de performance et de cohérence des données si plusieurs propriétés sont mises à jour en même temps.

  La valeur de retour est une fonction de gestion qui peut être appelée pour empêcher l'effet de s'exécuter à nouveau.

* **Exemple**

  ```js
  const count = ref(0)

  watchEffect(() => console.log(count.value))
  // -> affiche 0

  count.value++
  // -> affiche 1
  ```

  Arrêter l'observateur :

  ```js
  const stop = watchEffect(() => {})

  // lorsqu'on a plus besoin de l'observateur :
  stop()
  ```

  Mettre en pause / reprendre un observateur :&#x20;

  ```js
  const { stop, pause, resume } = watch(() => {})

  // mettre en pause temporairement l'observateur
  pause()

  // reprendre plus tard
  resume()

  // arrêter
  stop()
  ```

  Nettoyage des effets de bord :

  ```js
  watchEffect(async (onCleanup) => {
    const { response, cancel } = doAsyncWork(newId)
    // `cancel` sera appelé si `id` change,
    // annulant la requête précédente si elle n'a pas déjà été complétée.
    onCleanup(cancel)
    data.value = await response
  })
  ```

  Nettoyage des effets de bord à partir de la version 3.5 :

  ```js
  import { onWatcherCleanup } from 'vue'

  watchEffect(async () => {
    const { response, cancel } = doAsyncWork(newId)
    // `cancel` sera appelé si `id` change,
    // annulant la requête précédente si elle n'a pas déjà été complétée.
    onWatcherCleanup(cancel)
    data.value = await response
  })
  ```

  Options :

  ```js
  watchEffect(() => {}, {
    flush: 'post',
    onTrack(e) {
      debugger
    },
    onTrigger(e) {
      debugger
    }
  })
  ```

* **Voir aussi**
  * [Guide - Observateurs](/guide/essentials/watchers#watcheffect)
  * [Guide - Débogage des observateurs](/guide/extras/reactivity-in-depth#watcher-debugging)

## watchPostEffect() {#watchposteffect}

Alias de [`watchEffect()`](#watcheffect) avec l'option `flush : 'post'`.

## watchSyncEffect() {#watchsynceffect}

Alias de [`watchEffect()`](#watcheffect) avec l'option `flush : 'sync'`.

## watch() {#watch}

Observe une ou plusieurs sources de données réactives et invoque une fonction de rappel lorsque les sources changent.

* **Type :**

  ```ts
  // observation d'une source unique
  function watch<T>(
    source: WatchSource<T>,
    callback: WatchCallback<T>,
    options?: WatchOptions
  ): WatchHandle

  // observation de plusieurs sources
  function watch<T>(
    sources: WatchSource<T>[],
    callback: WatchCallback<T[]>,
    options?: WatchOptions
  ): WatchHandle

  type WatchCallback<T> = (
    value: T,
    oldValue: T,
    onCleanup: (cleanupFn: () => void) => void
  ) => void

  type WatchSource<T> =
    | Ref<T> // ref
    | (() => T) // accesseur
    | (T extends object ? T : never) // objet réactif

  interface WatchOptions extends WatchEffectOptions {
    immediate?: boolean // Par défaut: false
    deep?: boolean | number // Par défaut: false
    flush?: 'pre' | 'post' | 'sync' // Par défaut: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
    once?: boolean // Par défaut: false (3.4+)
  }

  interface WatchHandle {
    (): void // appelable, comme `stop`
    pause: () => void
    resume: () => void
    stop: () => void
  }
  ```

  > Le type est simplifié dans un souci de lisibilité.

* **Détails**

  `watch()` fonctionne à la volée par défaut - c'est-à-dire que la fonction de rappel n'est appelée que lorsque la source surveillée a changé.

  Le premier argument est la **source** de l'observateur. La source peut être l'une des suivantes :

  * Une fonction accesseur qui renvoie une valeur
  * Une ref
  * Un objet réactif
  * ...ou un tableau des éléments ci-dessus.

  Le second argument est la fonction de rappel qui sera appelée lorsque la source sera modifiée. Celle-ci reçoit trois arguments : la nouvelle valeur, l'ancienne, et une fonction pour enregistrer une fonction de nettoyage des effets de bord. La fonction de nettoyage sera appelée juste avant la prochaine exécution de l'effet, et peut être utilisée pour nettoyer les effets de bord invalidés, par exemple une requête asynchrone en attente.

  Lors de l'observation de plusieurs sources, la fonction de rappel reçoit deux tableaux contenant les nouvelles / anciennes valeurs correspondant au tableau des sources.

  Le troisième argument optionnel est un objet d'options qui prend en charge les options suivantes :

  * **`immediate`** : déclenche la fonction de rappel immédiatement à la création de l'observateur. L'ancienne valeur vaudra `undefined` lors du premier appel.
  * **`deep`** : force la traversée profonde de la source si c'est un objet, de sorte que la fonction de rappel se déclenche sur les mutations profondes. Voir [les observateurs profonds](/guide/essentials/watchers#deep-watchers).
  * **`flush`** : ajuste le timing de nettoyage de la fonction de rappel. Voir [timing du nettoyage des rappels](/guide/essentials/watchers#callback-flush-timing) et [`watchEffect()`](/api/reactivity-core#watcheffect).
  * **`onTrack / onTrigger`** : débogue les dépendances de l'observateur. Voir [Débogage des observateur](/guide/extras/reactivity-in-depth#watcher-debugging).
  * **`once`** : (3.4+) déclenche la fonction de rappel une seul fois. L'observateur sera automatiquement arrêté après le premier déclenchement.

  Comparée à [`watchEffect()`](#watcheffect), `watch()` nous permet de :

  * Exécuter l'effet de bord à la volée ;
  * Être plus spécifique quant à l'état qui doit déclencher la ré-exécution de l'observateur ;
  * Accéder à la fois à la valeur précédente et à la valeur actuelle de l'état surveillé.

* **Exemple**

  Observation d'un accesseur :

  ```js
  const state = reactive({ count: 0 })
  watch(
    () => state.count,
    (count, prevCount) => {
      /* ... */
    }
  )
  ```

  Observation d'une ref :

  ```js
  const count = ref(0)
  watch(count, (count, prevCount) => {
    /* ... */
  })
  ```

  Lorsque l'on observe plusieurs sources, la fonction de rappel reçoit des tableaux contenant les nouvelles / anciennes valeurs correspondant au tableau source :

  ```js
  watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
    /* ... */
  })
  ```

  Lorsque vous utilisez une source accesseur, l'observateur ne se déclenche que si la valeur de retour de l'accesseur a changé. Si vous voulez que la fonction de rappel se déclenche même lors de mutations profondes, vous devez explicitement forcer l'observateur à fonctionner en mode profond avec `{ deep: true }`. Notez qu'en mode profond, la nouvelle valeur et l'ancienne seront le même objet si la fonction de rappel a été déclenchée par une mutation profonde :

  ```js
  const state = reactive({ count: 0 })
  watch(
    () => state,
    (newValue, oldValue) => {
      // newValue === oldValue
    },
    { deep: true }
  )
  ```

  Lorsqu'il observe directement un objet réactif, l'observateur est automatiquement en mode profond :

  ```js
  const state = reactive({ count: 0 })
  watch(state, () => {
    /* se déclenche lors des mutations profondes de l'état */
  })
  ```

`watch()` a les mêmes options de timing et de débogage que [`watchEffect()`](#watcheffect) :

```js
watch(source, callback, {
  flush: 'post',
  onTrack(e) {
    debugger
  },
  onTrigger(e) {
    debugger
  }
})
```

Arrêter l'observateur :

```js
const stop = watch(source, callback)

// lorsqu'on n'a plus besoin de l'observateur :
stop()
```

Mettre en pause / reprendre un observateur :&#x20;

```js
const { stop, pause, resume } = watchEffect(() => {})

// mettre en pause temporairement l'observateur
pause()

// reprendre plus tard
resume()

// arrêter
stop()
```

Nettoyage des effets de bord :

```js
watch(id, async (newId, oldId, onCleanup) => {
  const { response, cancel } = doAsyncWork(newId)
  // `cancel` sera appelée si `id` change, annulant
  // la requête précédente si elle n'est pas terminée
  onCleanup(cancel)
  data.value = await response
})
```

Nettoyage des effets de bord à partir de la version 3.5 :

```js
import { onWatcherCleanup } from 'vue'

watch(id, async (newId) => {
  const { response, cancel } = doAsyncWork(newId)
  onWatcherCleanup(cancel)
  data.value = await response
})
```

* **Voir aussi**

  * [Guide - Observateurs](/guide/essentials/watchers)
  * [Guide - Débogage des observateurs](/guide/extras/reactivity-in-depth#watcher-debugging)

## onWatcherCleanup()  {#onwatchercleanup}

Enregistre une fonction de nettoyage à exécuter lorsque l'observateur actuel est sur le point de s'exécuter à nouveau. Elle ne peut être appelée que pendant l'exécution synchrone d'une fonction d'effet `watchEffect` ou d'une fonction de rappel `watch` (c'est-à-dire qu'elle ne peut pas être appelée après une instruction `await` dans une fonction asynchrone).

* **Type**

  ```ts
  function onWatcherCleanup(
    cleanupFn: () => void,
    failSilently?: boolean
  ): void
  ```

* **Exemple**

  ```ts
  import { watch, onWatcherCleanup } from 'vue'

  watch(id, (newId) => {
    const { response, cancel } = doAsyncWork(newId)
    // `cancel` sera appelé si `id` change, ce qui annulera
    // la demande précédente si elle n'est pas encore terminée
    onWatcherCleanup(cancel)
  })
  ```

---

---
url: /api/reactivity-utilities.md
---
# API de la réactivité : Utilitaires {#reactivity-api-utilities}

## isRef() {#isref}

Vérifie si une valeur est un objet ref.

* **Type :**

  ```ts
  function isRef<T>(r: Ref<T> | unknown): r is Ref<T>
  ```

  Notez que le type retourné est un [prédicat de type](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates), ce qui signifie que `isRef` peut être utilisée comme un garde de type :

  ```ts
  let foo: unknown
  if (isRef(foo)) {
    // le type de foo est déduit à Ref<unknown>
    foo.value
  }
  ```

## unref() {#unref}

Retourne la valeur interne si l'argument est une ref, sinon retourne l'argument lui-même. C'est une fonction de sucre syntaxique équivalente à `val = isRef(val) ? val.value : val`.

* **Type :**

  ```ts
  function unref<T>(ref: T | Ref<T>): T
  ```

* **Exemple**

  ```ts
  function useFoo(x: number | Ref<number>) {
    const unwrapped = unref(x)
    // unwrapped sera désormais un nombre
  }
  ```

## toRef() {#toref}

Peut être utilisée pour normaliser les valeurs / refs / accesseurs en refs (3.3+).

Peut être utilisée pour créer une ref pour une propriété sur un objet source réactif. La ref créée est synchronisée avec sa propriété source : la mutation de la propriété source mettra à jour la ref, et vice-versa.

* **Type :**

  ```ts
  // signature de normalisation (3.3+)
  function toRef<T>(
    value: T
  ): T extends () => infer R
    ? Readonly<Ref<R>>
    : T extends Ref
    ? T
    : Ref<UnwrapRef<T>>

  // signature des propriétés de l'objet
  function toRef<T extends object, K extends keyof T>(
    object: T,
    key: K,
    defaultValue?: T[K]
  ): ToRef<T[K]>

  type ToRef<T> = T extends Ref ? T : Ref<T>
  ```

* **Exemple**

  Signature de normalisation (3.3+) :

  ```js
  // retourne la ref existante telle quelle
  toRef(existingRef)

  // crée une ref en lecture seule qui appelle l'accesseur lors de l'accès à .value
  toRef(() => props.foo)

  // crée des refs classiques à partir de valeurs n'étant pas des fonctions
  // équivalent à ref(1)
  toRef(1)
  ```

  Signature de la propriété de l'objet :

  ```js
  const state = reactive({
    foo: 1,
    bar: 2
  })

  // une ref bidirectionnelle qui se synchronise avec la propriété d'origine
  const fooRef = toRef(state, 'foo')

  // muter la ref met à jour l'original
  fooRef.value++
  console.log(state.foo) // 2

  // muter l'original met également à jour la ref
  state.foo++
  console.log(fooRef.value) // 3
  ```

  Notez que cela est différent de :

  ```js
  const fooRef = ref(state.foo)
  ```

  La ref ci-dessus n'est **pas** synchronisée avec `state.foo`, car la fonction `ref()` reçoit une simple valeur numérique.

  `toRef()` est utile quand vous voulez passer la ref d'une prop à une fonction composable :

  ```vue
  <script setup>
  import { toRef } from 'vue'

  const props = defineProps(/* ... */)

  // convertit `props.foo` en une ref, puis la passe
  // à un composable
  useSomeFeature(toRef(props, 'foo'))

  // syntaxe accesseur - recommandée en 3.3+
  useSomeFeature(toRef(() => props.foo))
  </script>
  ```

  Lorsque `toRef` est utilisée avec des props de composant, les restrictions classiques concernant la modification des props s'appliquent. Tenter d'assigner une nouvelle valeur à la ref équivaut à essayer de modifier directement la prop et n'est pas autorisé. Dans ce cas, vous pouvez envisager d'utiliser [`computed`](./reactivity-core#computed) avec `get` et `set` à la place. Consultez le guide expliquant comment [utiliser `v-model` avec les composants](/guide/components/v-model) pour plus d'informations.

  En utilisant la signature des propriétés d'objets, `toRef()` retournera une ref utilisable même si la propriété source n'existe pas actuellement. Cela permet de travailler avec des propriétés optionnelles qui ne seraient pas prises en compte par [`toRefs`](#torefs).

## toValue() {#tovalue}

* Only supported in 3.3+

Normalise les valeurs / refs / accesseurs en valeurs. Cela est similaire à [unref()](#unref), sauf que cela normalise aussi les accesseurs. Si l'argument est un accesseur, il sera invoqué et sa valeur de retour sera renvoyée.

Cette fonction peut être utilisée dans les [Composables](/guide/reusability/composables.html) pour normaliser un argument qui peut être soit une valeur, soit une ref, soit un accesseur.

* **Type :**

  ```ts
  function toValue<T>(source: T | Ref<T> | (() => T)): T
  ```

* **Exemple**

  ```js
  toValue(1) //       --> 1
  toValue(ref(1)) //  --> 1
  toValue(() => 1) // --> 1
  ```

  Normalisation des arguments dans les composables :

  ```ts
  import type { MaybeRefOrGetter } from 'vue'

  function useFeature(id: MaybeRefOrGetter<number>) {
    watch(() => toValue(id), id => {
      // réagit aux changements d'id
    })
  }

  // ce composable supporte ces fonctions :
  useFeature(1)
  useFeature(ref(1))
  useFeature(() => 1)
  ```

## toRefs() {#torefs}

Convertit un objet réactif en un objet simple où chaque propriété de l'objet résultant est une ref pointant vers la propriété correspondante de l'objet original. Chaque ref individuelle est créée en utilisant [`toRef()`](#toref).

* **Type :**

  ```ts
  function toRefs<T extends object>(
    object: T
  ): {
    [K in keyof T]: ToRef<T[K]>
  }

  type ToRef = T extends Ref ? T : Ref<T>
  ```

* **Exemple**

  ```js
  const state = reactive({
    foo: 1,
    bar: 2
  })

  const stateAsRefs = toRefs(state)
  /*
  Type de stateAsRefs: {
    foo: Ref<number>,
    bar: Ref<number>
  }
  */

  // La ref et la propriété originale sont "liées"
  state.foo++
  console.log(stateAsRefs.foo.value) // 2

  stateAsRefs.foo.value++
  console.log(state.foo) // 3
  ```

  `toRefs` est utile pour retourner un objet réactif à partir d'une fonction composable afin que le composant consommateur puisse déstructurer / répartir l'objet renvoyé sans perdre sa réactivité :

  ```js
  function useFeatureX() {
    const state = reactive({
      foo: 1,
      bar: 2
    })

    // ...opération logique sur l'état

    // conversion en refs lors du retour
    return toRefs(state)
  }

  // destructuration possible sans perte de réactivité
  const { foo, bar } = useFeatureX()
  ```

  `toRefs` ne générera des refs que pour les propriétés qui sont énumérables sur l'objet source au moment de l'appel. Pour créer une ref pour une propriété qui n'existe peut-être pas encore, utilisez plutôt [`toRef`](#toref).

## isProxy() {#isproxy}

Vérifie si un objet est un proxy créé par [`reactive()`](./reactivity-core#reactive), [`readonly()`](./reactivity-core#readonly), [`shallowReactive()`](./reactivity-advanced#shallowreactive) ou [`shallowReadonly()`](./reactivity-advanced#shallowreadonly).

* **Type :**

  ```ts
  function isProxy(value: any): boolean
  ```

## isReactive() {#isreactive}

Vérifie si un objet est un proxy créé par [`reactive()`](./reactivity-core#reactive) ou [`shallowReactive()`](./reactivity-advanced#shallowreactive).

* **Type :**

  ```ts
  function isReactive(value: unknown): boolean
  ```

## isReadonly() {#isreadonly}

Vérifie si la valeur passée est un objet en lecture seule. Les propriétés d'un objet en lecture seule peuvent varier, mais elles ne peuvent pas être assignées directement via l'objet passé.

Les proxys créés par [`readonly()`](./reactivity-core#readonly) et \[`shallowReadonly()`(./reactivity-advanced#shallowreadonly) sont tous deux considérés comme en lecture seule, tout comme une ref [`computed()`](./reactivity-core#computed) sans fonction `set`.

* **Type :**

  ```ts
  function isReadonly(value: unknown): boolean
  ```

---

---
url: /api/custom-renderer.md
---
# API de rendu personnalisé {#custom-renderer-api}

## createRenderer() {#createrenderer}

Crée un rendu personnalisé. En fournissant des API de création et de manipulation de nœuds spécifiques à la plate-forme, vous pouvez tirer parti du noyau d'exécution de Vue pour cibler les environnements non DOM.

* **Type :**

  ```ts
  function createRenderer<HostNode, HostElement>(
    options: RendererOptions<HostNode, HostElement>
  ): Renderer<HostElement>

  interface Renderer<HostElement> {
    render: RootRenderFunction<HostElement>
    createApp: CreateAppFunction<HostElement>
  }

  interface RendererOptions<HostNode, HostElement> {
    patchProp(
      el: HostElement,
      key: string,
      prevValue: any,
      nextValue: any,
      namespace?: ElementNamespace,
      parentComponent?: ComponentInternalInstance | null
    ): void
    insert(
      el: HostNode,
      parent: HostElement,
      anchor?: HostNode | null
    ): void
    remove(el: HostNode): void
    createElement(
      type: string,
      namespace?: ElementNamespace,
      isCustomizedBuiltIn?: string,
      vnodeProps?: (VNodeProps & { [key: string]: any }) | null
    ): HostElement
    createText(text: string): HostNode
    createComment(text: string): HostNode
    setText(node: HostNode, text: string): void
    setElementText(node: HostElement, text: string): void
    parentNode(node: HostNode): HostElement | null
    nextSibling(node: HostNode): HostNode | null
    querySelector?(selector: string): HostElement | null
    setScopeId?(el: HostElement, id: string): void
    cloneNode?(node: HostNode): HostNode
    insertStaticContent?(
      content: string,
      parent: HostElement,
      anchor: HostNode | null,
      namespace: ElementNamespace,
      start?: HostNode | null,
      end?: HostNode | null
    ): [HostNode, HostNode]
  }
  ```

* **Exemple**

  ```js
  import { createRenderer } from '@vue/runtime-core'

  const { render, createApp } = createRenderer({
    patchProp,
    insert,
    remove,
    createElement
    // ...
  })

  // `render` est l'API de bas niveau
  // `createApp` retourne une instance de l'application
  export { render, createApp }

  // réexporte les API principales de Vue
  export * from '@vue/runtime-core'
  ```

  Le propre `@vue/runtime-dom` de Vue est [implémenté en utilisant la même API](https://github.com/vuejs/core/blob/main/packages/runtime-dom/src/index.ts). Pour une implémentation plus simple, consultez [`@vue/runtime-test`](https://github.com/vuejs/core/blob/main/packages/runtime-test/src/index.ts) qui est un paquet privé pour les tests unitaires de Vue.

---

---
url: /api/custom-elements.md
---
# API des éléments personnalisés {#custom-elements-api}

## defineCustomElement() {#definecustomelement}

Cette méthode accepte le même argument que [`defineComponent`](#definecomponent), mais renvoie à la place un constructeur natif de classe [Élément personnalisé](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements).

* **Type**

  ```ts
  function defineCustomElement(
    component:
      | (ComponentOptions & CustomElementsOptions)
      | ComponentOptions['setup'],
    options?: CustomElementsOptions
  ): {
    new (props?: object): HTMLElement
  }

  interface CustomElementsOptions {
    styles?: string[]

    // les options suivantes sont possibles à partir de la version 3.5
    configureApp?: (app: App) => void
    shadowRoot?: boolean
    nonce?: string
  }
  ```

  > Les types sont simplifiés pour une meilleure lisibilité.

* **Détails**

  En plus des options normales des composants, `defineCustomElement()` supporte également un certain nombre d'options spécifiques aux éléments personnalisés :

  * **`styles`**: un tableau de chaînes CSS pour fournir du CSS à injecter dans la shadow root de l'élément.

  * **`configureApp`** : une fonction qui peut être utilisée pour configurer l'instance de l'application Vue pour l'élément personnalisé.

  * **`shadowRoot`** : `boolean`, par défaut `true`. Définir à `false` pour restituer l'élément personnalisé sans shadow root. Cela signifie que `<style>` dans les SFC d'éléments personnalisés ne sera plus encapsulé.

  * **`nonce`** : `string`, s'il est fourni, sera défini comme l'attribut `nonce` sur les tags de style injectés dans la shadow root.

  Notez qu'au lieu d'être transmises comme une partie du composant lui-même, ces options peuvent également être transmises via un deuxième argument :

  ```js
  import Element from './MyElement.ce.vue'

  defineCustomElement(Element, {
    configureApp(app) {
      // ...
    }
  })
  ```

  La valeur de retour est un constructeur d'élément personnalisé qui peut être enregistré à l'aide de [`customElements.define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).

* **Exemple**

  ```js
  import { defineCustomElement } from 'vue'

  const MyVueElement = defineCustomElement({
    /* options des composants */
  })

  // Enregistrez l'élément personnalisé.
  customElements.define('my-vue-element', MyVueElement)
  ```

* **Voir aussi**

  * [Guide - Créer des éléments personnalisés avec Vue](/guide/extras/web-components#building-custom-elements-with-vue)

  * Notez également que `defineCustomElement()` nécessite une [configuration spéciale](/guide/extras/web-components#sfc-as-custom-element) lorsqu'il est utilisé avec des composants monofichiers.

## useHost()  {#usehost}

Un assistant helper de la Composition API qui renvoie l'élément hôte de l'élément personnalisé Vue actuel.

## useShadowRoot()  {#useshadowroot}

Un assistant helper de la Composition API qui renvoie la shadow root de l'élément personnalisé Vue actuel.

## this.$host  {#this-host}

Une propriété de l'Options API qui expose l’élément hôte de l’élément personnalisé Vue actuel.

---

---
url: /api/ssr.md
---
# API du rendu côté serveur {#server-side-rendering-api}

## renderToString() {#rendertostring}

* **Exporté depuis `vue/server-renderer`**

* **Type :**

  ```ts
  function renderToString(
    input: App | VNode,
    context?: SSRContext
  ): Promise<string>
  ```

* **Exemple**

  ```js
  import { createSSRApp } from 'vue'
  import { renderToString } from 'vue/server-renderer'

  const app = createSSRApp({
    data: () => ({ msg: 'hello' }),
    template: `<div>{{ msg }}</div>`
  })

  ;(async () => {
    const html = await renderToString(app)
    console.log(html)
  })()
  ```

  ### Contexte SSR {#ssr-context}

  Vous pouvez passer un objet facultatif représentant le contexte, et pouvant être utilisé pour enregistrer des données supplémentaires pendant le rendu, par exemple pour [accéder au contenu des Teleports](/guide/scaling-up/ssr#teleports) :

  ```js
  const ctx = {}
  const html = await renderToString(app, ctx)

  console.log(ctx.teleports) // { '#teleported': 'teleported content' }
  ```

  La plupart des autres API de SSR présentées sur cette page acceptent également de manière facultative un objet de contexte. L'objet de contexte est accessible dans le code du composant via l'utilitaire [useSSRContext](#usessrcontext).

* **Voir aussi** [Guide - Rendu côté serveur](/guide/scaling-up/ssr)

## renderToNodeStream() {#rendertonodestream}

Effectue le rendu de l'entrée comme un [*Readable Stream* de Node.js](https://nodejs.org/api/stream.html#stream_class_stream_readable).

* **Exporté depuis `vue/server-renderer`**

* **Type :**

  ```ts
  function renderToNodeStream(
    input: App | VNode,
    context?: SSRContext
  ): Readable
  ```

* **Exemple**

  ```js
  // à l'intérieur d'un gestionnaire http Node.js
  renderToNodeStream(app).pipe(res)
  ```

  :::tip Remarque
  Cette méthode n'est pas supportée dans le build ESM de `vue/server-renderer`, qui est n'est pas couplé aux environnements Node.js. Utilisez plutôt [`pipeToNodeWritable`](#pipetonodewritable).
  :::

## pipeToNodeWritable() {#pipetonodewritable}

Effectue le rendu et le transfert vers une instance existante d'un [*Writable Stream* de Node.js](https://nodejs.org/api/stream.html#stream_writable_streams).

* **Exporté depuis `vue/server-renderer`**

* **Type :**

  ```ts
  function pipeToNodeWritable(
    input: App | VNode,
    context: SSRContext = {},
    writable: Writable
  ): void
  ```

* **Exemple**

  ```js
  // à l'intérieur d'un gestionnaire http Node.js
  pipeToNodeWritable(app, {}, res)
  ```

## renderToWebStream() {#rendertowebstream}

Effectue le rendu de l'entrée sous forme d'un [*Readable Stream* web](https://developer.mozilla.org/fr/docs/Web/API/Streams_API).

* **Exporté depuis `vue/server-renderer`**

* **Type :**

  ```ts
  function renderToWebStream(
    input: App | VNode,
    context?: SSRContext
  ): ReadableStream
  ```

* **Exemple**

  ```js
  // dans un environnement prenant en charge _ReadableStream_
  return new Response(renderToWebStream(app))
  ```

  :::tip Remarque
  Dans les environnements n'exposant pas le constructeur `ReadableStream` dans la portée globale, [`pipeToWebWritable()`](#pipetowebwritable) doit être utilisée à la place.
  :::

## pipeToWebWritable() {#pipetowebwritable}

Effectue le rendu et le transfert à une instance existante d'un [*Writable Stream* web](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream).

* **Exporté depuis `vue/server-renderer`**

* **Type :**

  ```ts
  function pipeToWebWritable(
    input: App | VNode,
    context: SSRContext = {},
    writable: WritableStream
  ): void
  ```

* **Exemple**

  Cette fonction est généralement utilisée en combinaison avec [`TransformStream`](https://developer.mozilla.org/fr/docs/Web/API/TransformStream) :

  ```js
  // TransformStream est disponible dans des environnements tels que les espaces de travail de CloudFlare.
  // dans Node.js, TransformStream doit être explicitement importé à partir de 'stream/web'
  const { readable, writable } = new TransformStream()
  pipeToWebWritable(app, {}, writable)

  return new Response(readable)
  ```

## renderToSimpleStream() {#rendertosimplestream}

Effectue le rendu de l'entrée en mode streaming en utilisant une simple interface lisible.

* **Exporté depuis `vue/server-renderer`**

* **Type :**

  ```ts
  function renderToSimpleStream(
    input: App | VNode,
    context: SSRContext,
    options: SimpleReadable
  ): SimpleReadable

  interface SimpleReadable {
    push(content: string | null): void
    destroy(err: any): void
  }
  ```

* **Exemple**

  ```js
  let res = ''

  renderToSimpleStream(
    app,
    {},
    {
      push(chunk) {
        if (chunk === null) {
          // terminé
          console(`render complete: ${res}`)
        } else {
          res += chunk
        }
      },
      destroy(err) {
        // erreur rencontrée
      }
    }
  )
  ```

## useSSRContext() {#usessrcontext}

Une API d'exécution utilisée pour récupérer l'objet de contexte transmis à `renderToString()` ou à d'autres API de rendu serveur.

* **Type :**

  ```ts
  function useSSRContext<T = Record<string, any>>(): T | undefined
  ```

* **Exemple**

  Le contexte récupéré peut être utilisé pour joindre les informations nécessaires au rendu du HTML final (par exemple, les métadonnées de l'en-tête).

  ```vue
  <script setup>
  import { useSSRContext } from 'vue'

  // ne l'appelez que lors du rendu côté serveur
  // https://vite.dev/guide/ssr.html#conditional-logic
  if (import.meta.env.SSR) {
    const ctx = useSSRContext()
    // ...attache des propriétés au contexte
  }
  </script>
  ```

## data-allow-mismatch  {#data-allow-mismatch}

A special attribute that can be used to suppress [hydration mismatch](/guide/scaling-up/ssr#hydration-mismatch) warnings.

* **Example**

  ```html
  <div data-allow-mismatch="text">{{ data.toLocaleString() }}</div>
  ```

  The value can limit the allowed mismatch to a specific type. Allowed values are:

  * `text`
  * `children` (only allows mismatch for direct children)
  * `class`
  * `style`
  * `attribute`

  If no value is provided, all types of mismatches will be allowed.

---

---
url: /api/render-function.md
---
# API du rendu de fonction {#render-function-apis}

## h() {#h}

Créé des nœuds virtuels du DOM (vnodes).

* **Type :**

  ```ts
  // signature complète
  function h(
    type: string | Component,
    props?: object | null,
    children?: Children | Slot | Slots
  ): VNode

  // en omettant des props
  function h(type: string | Component, children?: Children | Slot): VNode

  type Children = string | number | boolean | VNode | null | Children[]

  type Slot = () => Children

  type Slots = { [name: string]: Slot }
  ```

  > Les types sont simplifiés dans un souci de lisibilité.

* **Détails**

  Le premier argument peut être une chaîne de caractères (pour les éléments natifs) ou une définition de composant Vue. Le deuxième argument est les props à passer, et le troisième argument représente les enfants.

  Lors de la création d'un vnode de composant, les enfants doivent être passés en tant que fonctions slot. Une seule fonction slot peut être transmise si le composant n'attend que le slot par défaut. Sinon, les slots doivent être passés comme un objet de fonctions slot.

  Pour des raisons pratiques, l'argument props peut être omis lorsque les enfants ne sont pas un objet slots.

* **Exemple**

  Création d'éléments natifs :

  ```js
  import { h } from 'vue'

  // tous les arguments, à l'exception du type, sont optionnels
  h('div')
  h('div', { id: 'foo' })

  // les attributs ainsi que les propriétés peuvent être utilisées dans les props
  // Vue choisit automatiquement la bonne façon de les assigner
  h('div', { class: 'bar', innerHTML: 'hello' })

  // pour les classes et les styles, les valeurs d'objet / tableau
  // sont prises en charges, tout comme dans les templates
  h('div', { class: [foo, { bar }], style: { color: 'red' } })

  // les écouteurs d'événements doivent être passés suivant le format onXxx
  h('div', { onClick: () => {} })

  // les enfants peuvent être des chaînes de caractères
  h('div', { id: 'foo' }, 'hello')

  // on peut omettre les props lorsqu'il n'y en a pas
  h('div', 'hello')
  h('div', [h('span', 'hello')])

  // les tableaux d'enfants peuvent contenir à la fois des vnodes et des chaînes de caractères
  h('div', ['hello', h('span', 'hello')])
  ```

  Création d'un composant :

  ```js
  import Foo from './Foo.vue'

  // passage de props
  h(Foo, {
    // équivalent à some-prop="hello"
    someProp: 'hello',
    // équivalent à @update="() => {}"
    onUpdate: () => {}
  })

  // passage d'un unique slot par défaut
  h(Foo, () => 'default slot')

  // passage de slots nommés
  // notez que `null` est nécessaire pour éviter
  // à l'objet de slots d'être traité en tant que props
  h(MyComponent, null, {
    default: () => 'default slot',
    foo: () => h('div', 'foo'),
    bar: () => [h('span', 'one'), h('span', 'two')]
  })
  ```

* **Voir aussi** [Guide - Fonctions de rendu - Créer des Vnodes](/guide/extras/render-function#creating-vnodes)

## mergeProps() {#mergeprops}

Fusionne plusieurs objets de props avec une gestion spéciale pour certaines props.

* **Type :**

  ```ts
  function mergeProps(...args: object[]): object
  ```

* **Détails**

  `mergeProps()` permet de fusionner plusieurs objets de props avec une gestion spéciale pour les props suivantes :

  * `class`
  * `style`
  * Écouteurs d'événements `onXxx` - plusieurs écouteurs avec le même nom seront fusionnés dans un tableau.

  Si vous n'avez pas besoin de la fusion et que vous voulez simplement écraser, la propagation d'objet natif peut être utilisée à la place.

* **Exemple**

  ```js
  import { mergeProps } from 'vue'

  const one = {
    class: 'foo',
    onClick: handlerA
  }

  const two = {
    class: { bar: true },
    onClick: handlerB
  }

  const merged = mergeProps(one, two)
  /**
   {
     class: 'foo bar',
     onClick: [handlerA, handlerB]
   }
   */
  ```

## cloneVNode() {#clonevnode}

Clone un vnode.

* **Type :**

  ```ts
  function cloneVNode(vnode: VNode, extraProps?: object): VNode
  ```

* **Détails**

  Renvoie un vnode cloné, avec éventuellement des props supplémentaires à fusionner avec l'original.

  Les vnodes doivent être considérés comme immuables une fois créés, et vous ne devez pas modifier les propriétés d'un vnode existant. Au lieu de cela, clonez-le avec des props différentes / supplémentaires.

  Les vnodes ont des propriétés internes spéciales, donc les cloner n'est pas aussi simple qu'une copie d'objet. `cloneVNode()` gère la plupart de la logique interne.

* **Exemple**

  ```js
  import { h, cloneVNode } from 'vue'

  const original = h('div')
  const cloned = cloneVNode(original, { id: 'foo' })
  ```

## isVNode() {#isvnode}

Vérifie si une valeur est un vnode ou non.

* **Type :**

  ```ts
  function isVNode(value: unknown): boolean
  ```

## resolveComponent() {#resolvecomponent}

Utilisée pour résoudre manuellement un composant enregistré via son nom.

* **Type :**

  ```ts
  function resolveComponent(name: string): Component | string
  ```

* **Détails**

  **Remarque : cette fonction n'est pas nécessaire si vous pouvez directement importer le composant.**

  `resolveComponent()` doit être appelée à l'intérieurde `setup()` ou de la fonction de rendu afin de résoudre à partir du bon contexte de composant.

  Si le composant n'est pas trouvé, un avertissement exécution est émis lors de l'exécution et le nom est retourné sous forme de chaîne de caractères.

* **Exemple**

  ```js
  import { h, resolveComponent } from 'vue'

  export default {
    setup() {
      const ButtonCounter = resolveComponent('ButtonCounter')

      return () => {
        return h(ButtonCounter)
      }
    }
  }
  ```

  ```js
  import { h, resolveComponent } from 'vue'

  export default {
    render() {
      const ButtonCounter = resolveComponent('ButtonCounter')
      return h(ButtonCounter)
    }
  }
  ```

* **Voir aussi** [Guide - Fonctions de rendu - Composants](/guide/extras/render-function#components)

## resolveDirective() {#resolvedirective}

Utilisée pour résoudre manuellement une directive enregistrée via son nom.

* **Type :**

  ```ts
  function resolveDirective(name: string): Directive | undefined
  ```

* **Détails**

  **Remarque : cette fonction n'est pas nécessaire si vous pouvez directement importer la directive.**

  `resolveDirective()` doit être appelée à l'intérieur dela fonction `setup()` ou la fonction de rendu afin de résoudre à partir du bon contexte de composant.

  Si la directive n'est pas trouvée, un avertissement sera émis lors de l'exécution et la fonction retournera `undefined`.

* **Voir aussi** [Guide - Fonctions de rendu - Directives personnalisées](/guide/extras/render-function#custom-directives)

## withDirectives() {#withdirectives}

Utilisée pour ajouter des directives personnalisées aux vnodes.

* **Type :**

  ```ts
  function withDirectives(
    vnode: VNode,
    directives: DirectiveArguments
  ): VNode

  // [Directive, valeur, argument, modificateurs]
  type DirectiveArguments = Array<
    | [Directive]
    | [Directive, any]
    | [Directive, any, string]
    | [Directive, any, string, DirectiveModifiers]
  >
  ```

* **Détails**

  Enveloppe un vnode existant avec des directives personnalisées. Le second argument est un tableau de directives personnalisées. Chaque directive personnalisée est également représentée par un tableau sous la forme `[Directive, valeur, argument, modificateurs]`. Les éléments finaux du tableau peuvent être omis s'ils ne sont pas nécessaires.

* **Exemple**

  ```js
  import { h, withDirectives } from 'vue'

  // une directive personnalisée
  const pin = {
    mounted() {
      /* ... */
    },
    updated() {
      /* ... */
    }
  }

  // <div v-pin:top.animate="200"></div>
  const vnode = withDirectives(h('div'), [
    [pin, 200, 'top', { animate: true }]
  ])
  ```

* **Voir aussi** [Guide - Fonction de rendu - Directives personnalisées](/guide/extras/render-function#custom-directives)

## withModifiers() {#withmodifiers}

Utilisée pour ajouter des modificateurs natifs [`v-on`](/guide/essentials/event-handling#event-modifiers) à une fonction de gestion d'événements.

* **Type :**

  ```ts
  function withModifiers(fn: Function, modifiers: ModifierGuardsKeys[]): Function
  ```

* **Exemple**

  ```js
  import { h, withModifiers } from 'vue'

  const vnode = h('button', {
    // équivalent à v-on:click.stop.prevent
    onClick: withModifiers(() => {
      // ...
    }, ['stop', 'prevent'])
  })
  ```

* **Voir aussi** [Guide - Fonctions de rendu - Modificateurs d'événement](/guide/extras/render-function#event-modifiers)

---

---
url: /api/general.md
---
# API Globale : Générale {#global-api-general}

## version {#version}

Expose la version actuelle de Vue.

* **Type :** `string`

* **Exemple**

  ```js
  import { version } from 'vue'

  console.log(version)
  ```

## nextTick() {#nexttick}

Un outil pour attendre la prochaine mise à jour du DOM.

* **Type :**

  ```ts
  function nextTick(callback?: () => void): Promise<void>
  ```

* **Détails**

  Lorsque vous modifiez un état réactif dans Vue, les mises à jour du DOM qui en résultent ne sont pas appliquées de manière synchrone. Au lieu de cela, Vue les met en mémoire tampon jusqu'au "next tick" afin de garantir que chaque composant ne soit mis à jour qu'une seule fois, quel que soit le nombre de modifications d'état que vous avez effectuées.

  `nextTick()` peut être utilisé immédiatement après un changement d'état pour attendre que les mises à jour du DOM soient terminées. Vous pouvez soit passer une fonction de rappel comme argument, soit attendre la promesse retournée.

* **Exemple**

  ```vue
  <script setup>
  import { ref, nextTick } from 'vue'

  const count = ref(0)

  async function increment() {
    count.value++

    // DOM pas encore mis à jour
    console.log(document.getElementById('counter').textContent) // 0

    await nextTick()
    // DOM désormais mis à jour
    console.log(document.getElementById('counter').textContent) // 1
  }
  </script>

  <template>
    <button id="counter" @click="increment">{{ count }}</button>
  </template>
  ```

  ```vue
  <script>
  import { nextTick } from 'vue'

  export default {
    data() {
      return {
        count: 0
      }
    },
    methods: {
      async increment() {
        this.count++

        // DOM pas encore mis à jour
        console.log(document.getElementById('counter').textContent) // 0

        await nextTick()
        // DOM désormais mis à jour
        console.log(document.getElementById('counter').textContent) // 1
      }
    }
  }
  </script>

  <template>
    <button id="counter" @click="increment">{{ count }}</button>
  </template>
  ```

* **Voir aussi** [`this.$nextTick()`](/api/component-instance#nexttick)

## defineComponent() {#definecomponent}

Un utilitaire de type pour définir un composant Vue avec l'inférence de type.

* **Type :**

  ```ts
  // options syntax
  function defineComponent(
    component: ComponentOptions
  ): ComponentConstructor

  // function syntax (requires 3.3+)
  function defineComponent(
    setup: ComponentOptions['setup'],
    extraOptions?: ComponentOptions
  ): () => any
  ```

  > Le type est simplifié dans un souci de lisibilité.

* **Détails**

  Le premier argument attend un objet d'options de composant. La valeur retournée sera le même objet d'options, puisque la fonction est essentiellement sans opération à l'exécution pour seulement apporter l'inférence de type.

  Notez que le type retourné est un peu spécial : il s'agit d'un type constructeur dont le type d'instance est le type d'instance du composant déduit en fonction des options. C'est utilisé pour l'inférence de type lorsque le type retourné est utilisé comme balise dans du TSX.

  Vous pouvez extraire le type d'instance d'un composant (équivalent au type de `this` dans ses options) à partir du type retourné par `defineComponent()` de cette façon :

  ```ts
  const Foo = defineComponent(/* ... */)

  type FooInstance = InstanceType<typeof Foo>
  ```

  ### Signature de fonction {#function-signature}

  * Supporté à partir de la version 3.3

  `defineComponent()` possède également une signature alternative destinée à être utilisée avec la Composition API et les [fonctions de rendu ou du JSX](/guide/extras/render-function.html).

  Au lieu de passer un objet d'options, une fonction est attendue à la place. Cette fonction fonctionne de la même manière que la fonction [`setup()`](/api/composition-api-setup.html#composition-api-setup) de la Composition API : elle reçoit les props et le contexte général. La valeur de retour doit être une fonction de rendu - `h()` et JSX sont supportés :

  ```js
  import { ref, h } from 'vue'

  const Comp = defineComponent(
    (props) => {
      // utilisez ici la Composition API comme dans <script setup>
      const count = ref(0)

      return () => {
        // fonction de rendu ou JSX
        return h('div', count.value)
      }
    },
    // options supplémentaires, comme la déclaration des props ou l'émission d'événements
    {
      props: {
        /* ... */
      }
    }
  )
  ```

  Le cas principal d'utilisation de cette signature est lors de l'utilisation de TypeScript (et en particulier avec TSX), car elle prend en charge les génériques :

  ```tsx
  const Comp = defineComponent(
    <T extends string | number>(props: { msg: T; list: T[] }) => {
      // utilisez ici la Composition API comme dans <script setup>
      const count = ref(0)

      return () => {
        // fonction de rendu ou JSX
        return <div>{count.value}</div>
      }
    },
    // la déclaration manuelle des props au moment de l'exécution est encore toutefois nécessaire.
    {
      props: ['msg', 'list']
    }
  )
  ```

  Dans le futur, nous prévoyons de fournir un plugin Babel qui infère et injecte automatiquement les props d'exécution (comme pour `defineProps` dans les SFCs) afin que la déclaration des props d'exécution puisse être omise.

  ### Note sur le treeshaking de webpack {#note-on-webpack-treeshaking}

  Étant donné que `defineComponent()` est un appel de fonction, on pourrait attendre qu'il produise des effets de bord pour certains outils de build, par exemple webpack. Cela empêchera le composant d'être retiré de l'arbre même s'il n'est jamais utilisé.

  Pour indiquer à webpack que cet appel de fonction peut être retirée en toute tranquillité, vous pouvez ajouter un commentaire `/*#__PURE__*/` avant l'appel de fonction :

  ```js
  export default /*#__PURE__*/ defineComponent(/* ... */)
  ```

  Notez que cela n'est pas nécessaire si vous utilisez Vite, car Rollup (le bundler de production sous-jacent utilisé par Vite) est suffisamment intelligent pour déterminer que `defineComponent()` est en fait exempte d'effet de bord sans avoir besoin d'annotations manuelles.

* **Voir aussi** [Guide - Utiliser Vue avec TypeScript](/guide/typescript/overview#general-usage-notes)

## defineAsyncComponent() {#defineasynccomponent}

Définit un composant asynchrone qui est chargé de manière paresseuse uniquement lors de son rendu. L'argument peut être au choix une fonction de chargement, ou bien un objet d'options pour un contrôle plus avancé du comportement de chargement.

* **Type :**

  ```ts
  function defineAsyncComponent(
    source: AsyncComponentLoader | AsyncComponentOptions
  ): Component

  type AsyncComponentLoader = () => Promise<Component>

  interface AsyncComponentOptions {
    loader: AsyncComponentLoader
    loadingComponent?: Component
    errorComponent?: Component
    delay?: number
    timeout?: number
    suspensible?: boolean
    onError?: (
      error: Error,
      retry: () => void,
      fail: () => void,
      attempts: number
    ) => any
  }
  ```

* **See also** [Guide - Async Components](/guide/components/async)

---

---
url: /api/application.md
---
# Application API {#application-api}

## createApp() {#createapp}

Crée une instance d'application.

* **Type :**

  ```ts
  function createApp(rootComponent: Component, rootProps?: object): App
  ```

* **Détails**

  Le premier argument est le composant racine. Le deuxième argument facultatif est les props à transmettre au composant racine.

* **Exemple**

  Avec un composant racine littéral :

  ```js
  import { createApp } from 'vue'

  const app = createApp({
    /* options du composant racine */
  })
  ```

  Avec un composant importé :

  ```js
  import { createApp } from 'vue'
  import App from './App.vue'

  const app = createApp(App)
  ```

* **Voir aussi** [Guide - Créer une application Vue](/guide/essentials/application)

## createSSRApp() {#createssrapp}

Crée une instance d'application en mode [Hydratation SSR](/guide/scaling-up/ssr#client-hydration). L'utilisation est exactement la même que `createApp()`.

## app.mount() {#app-mount}

Monte l'instance d'application dans un élément conteneur.

* **Type :**

  ```ts
  interface App {
    mount(rootContainer: Element | string): ComponentPublicInstance
  }
  ```

* **Détails**

  L'argument peut être soit un élément réel du DOM, soit un sélecteur CSS (le premier élément correspondant sera utilisé). Renvoie l'instance du composant racine.

  Si le composant a un template ou une fonction de rendu défini, il remplacera tous les nœuds du DOM existants à l'intérieur du conteneur. Sinon, si le compilateur est disponible, le `innerHTML` du conteneur sera utilisé comme template.

  En mode hydratation SSR, il hydratera les nœuds DOM existants à l'intérieur du conteneur. S'il y a [des incohérences](/guide/scaling-up/ssr#hydration-mismatch), les nœuds du DOM existants seront transformés pour correspondre à la sortie attendue.

  Pour chaque instance d'application, `mount()` ne peut être appelée qu'une seule fois.

* **Exemple**

  ```js
  import { createApp } from 'vue'
  const app = createApp(/* ... */)

  app.mount('#app')
  ```

  Peut également être montée sur un élément du DOM réel :

  ```js
  app.mount(document.body.firstChild)
  ```

## app.unmount() {#app-unmount}

Démonte une instance d'application montée, déclenchant les hooks de cycle de vie de démontage pour tous les composants de l'arborescence des composants de l'application.

* **Type :**

  ```ts
  interface App {
    unmount(): void
  }
  ```

## app.onUnmount()  {#app-onunmount}

Enregistre une fonction de rappel à exécuter lorsque l'application est démontée.

* **Type**

  ```ts
  interface App {
    onUnmount(callback: () => any): void
  }
  ```

## app.component() {#app-component}

Enregistre un composant global si un nom et une définition de composant sont passés ensemble, ou récupère un composant déjà enregistré si seul le nom est passé.

* **Type :**

  ```ts
  interface App {
    component(name: string): Component | undefined
    component(name: string, component: Component): this
  }
  ```

* **Exemple**

  ```js
  import { createApp } from 'vue'

  const app = createApp({})

  // enregistre un objet d'options
  app.component('MyComponent', {
    /* ... */
  })

  // récupère un composant enregistré
  const MyComponent = app.component('MyComponent')
  ```

* **Voir aussi** [Enregistrement des composants](/guide/components/registration)

## app.directive() {#app-directive}

Enregistre une directive personnalisée globale si un nom et une définition de directive sont passés, ou récupère une directive déjà enregistrée si seul le nom est passé.

* **Type :**

  ```ts
  interface App {
    directive(name: string): Directive | undefined
    directive(name: string, directive: Directive): this
  }
  ```

* **Exemple**

  ```js
  import { createApp } from 'vue'

  const app = createApp({
    /* ... */
  })

  // enregistrement (options de directive)
  app.directive('myDirective', {
    /* custom directive hooks */
  })

  // enregistrement (raccourci d'une fonction de directive)
  app.directive('myDirective', () => {
    /* ... */
  })

  // récupère une directive enregistrée
  const myDirective = app.directive('myDirective')
  ```

* **Voir aussi** [Directives personnalisées](/guide/reusability/custom-directives)

## app.use() {#app-use}

Installe un [plugin](/guide/reusability/plugins).

* **Type :**

  ```ts
  interface App {
    use(plugin: Plugin, ...options: any[]): this
  }
  ```

* **Détails**

  Attend le plugin comme premier argument et les options facultatives du plugin comme deuxième argument.

  Le plugin peut être soit un objet avec une méthode `install()`, soit simplement une fonction qui sera utilisée comme méthode `install()`. Les options (deuxième argument de `app.use()`) seront transmises à la méthode `install()` du plugin.

  Lorsque `app.use()` est appelé plusieurs fois sur le même plugin, le plugin ne sera installé qu'une seule fois.

* **Exemple**

  ```js
  import { createApp } from 'vue'
  import MyPlugin from './plugins/MyPlugin'

  const app = createApp({
    /* ... */
  })

  app.use(MyPlugin)
  ```

* **Voir aussi** [Plugins](/guide/reusability/plugins)

## app.mixin() {#app-mixin}

Applique un mixin global (limité à l'application). Un mixin global applique ses options incluses à chaque instance de composant dans l'application.

:::warning Non recommandé
Les mixins sont pris en charge dans Vue 3 principalement pour la rétrocompatibilité, en raison de leur utilisation répandue dans les bibliothèques de l'écosystème. L'utilisation de mixins, en particulier de mixins globaux, doit être évitée dans le code de l'application.

Pour une réutilisation logique, préférez plutôt les [Composables](/guide/reusability/composables).
:::

* **Type :**

  ```ts
  interface App {
    mixin(mixin: ComponentOptions): this
  }
  ```

## app.provide() {#app-provide}

Fournit une valeur pouvant être injectée dans tous les composants descendants de l'application.

* **Type :**

  ```ts
  interface App {
    provide<T>(key: InjectionKey<T> | symbol | string, value: T): this
  }
  ```

* **Détails**

  Attend la clé d'injection comme premier argument et la valeur fournie comme second. Renvoie l'instance d'application elle-même.

* **Exemple**

  ```js
  import { createApp } from 'vue'

  const app = createApp(/* ... */)

  app.provide('message', 'hello')
  ```

  Dans un composant de l'application :

  ```js
  import { inject } from 'vue'

  export default {
    setup() {
      console.log(inject('message')) // 'hello'
    }
  }
  ```

  ```js
  export default {
    inject: ['message'],
    created() {
      console.log(this.message) // 'hello'
    }
  }
  ```

* **Voir aussi**
  * [Provide / Inject](/guide/components/provide-inject)
  * [App-level Provide](/guide/components/provide-inject#app-level-provide)
  * [app.runWithContext()](#app-runwithcontext)

## app.runWithContext() {#app-runwithcontext}

* Supporté à partir de la version 3.3

Exécute une fonction de rappel avec l'application courante comme contexte injecté.

* **Type**

  ```ts
  interface App {
    runWithContext<T>(fn: () => T): T
  }
  ```

* **Détails**

  Attend une fonction de rappel et l'exécute immédiatement. Lors de l'appel synchrone du rappel, les appels `inject()` sont capables de rechercher des injections à partir des valeurs fournies par l'application actuelle, même lorsqu'il n'y a pas d'instance de composant active actuelle. La valeur de retour du rappel sera également retournée.

* **Exemple**

  ```js
  import { inject } from 'vue'

  app.provide('id', 1)

  const injected = app.runWithContext(() => {
    return inject('id')
  })

  console.log(injected) // 1
  ```

## app.version {#app-version}

Fournit la version de Vue avec laquelle l'application a été créée. Ceci est utile pour les [plugins](/guide/reusability/plugins), où vous pourriez avoir besoin d'une logique conditionnelle basée sur différentes versions de Vue.

* **Type :**

  ```ts
  interface App {
    version: string
  }
  ```

* **Exemple**

  Effectuer une vérification de version à l'intérieur d'un plugin :

  ```js
  export default {
    install(app) {
      const version = Number(app.version.split('.')[0])
      if (version < 3) {
        console.warn('This plugin requires Vue 3')
      }
    }
  }
  ```

* **Voir aussi** [API générale - version](/api/general#version)

## app.config {#app-config}

Chaque instance d'application expose un objet `config` qui contient les paramètres de configuration de cette application. Vous pouvez modifier ses propriétés (documentées ci-dessous) avant de monter votre application.

```js
import { createApp } from 'vue'

const app = createApp(/* ... */)

console.log(app.config)
```

## app.config.errorHandler {#app-config-errorhandler}

Installe un gestionnaire global pour les erreurs non détectées se propageant depuis l'application.

* **Type :**

  ```ts
  interface AppConfig {
    errorHandler?: (
      err: unknown,
      instance: ComponentPublicInstance | null,
      // `info` est spécifique à Vue pour les infos d' erreur,
      // par exemple, de quel hook de cycle de vie l'erreur provient
      info: string
    ) => void
  }
  ```

* **Détails**

  Le gestionnaire d'erreurs attend trois arguments : l'erreur, l'instance de composant qui a déclenché l'erreur et une chaîne d'informations spécifiant le type de source d'erreur.

  Il peut capturer les erreurs provenant des sources suivantes :

  * Rendus de composants
  * Gestionnaires d'événements
  * Les hooks du cycle de vie
  * Fonction `setup()`
  * Observateurs
  * Hooks de directives personnalisés
  * Hooks de transition

  :::tip
  En production, le troisième argument (`info`) sera un code raccourci plutôt que toute la chaîne d'information. Vous pouvez trouver le code correspondant dans la [Référence des erreurs en production](/error-reference/#runtime-errors).
  :::

* **Exemple**

  ```js
  app.config.errorHandler = (err, instance, info) => {
    // gère l'erreur, par exemple pour la reporter à un service tiers
  }
  ```

* **Défaut**

  Le gestionnaire d'erreurs par défaut relancera les erreurs pendant le développement et les affichera dans le journal en production.
  Vous pouvez configurer cela à l'aide de la propriété [throwUnhandledErrorInProduction](#app-config-throwunhandlederrorinproduction).

## app.config.warnHandler {#app-config-warnhandler}

Ajoute un gestionnaire personnalisé pour les avertissements d'exécution de Vue.

* **Type :**

  ```ts
  interface AppConfig {
    warnHandler?: (
      msg: string,
      instance: ComponentPublicInstance | null,
      trace: string
    ) => void
  }
  ```

* **Détails**

  Le gestionnaire d'avertissement attend le message d'avertissement comme premier argument, l'instance du composant source comme deuxième argument et les traces du composant comme troisième.

  Il peut être utilisé pour filtrer des avertissements spécifiques afin de réduire la verbosité de la console. Tous les avertissements de Vue doivent être traités pendant le développement, donc cela n'est recommandé que pendant les sessions de débogage pour se concentrer sur des avertissements spécifiques parmi tant d'autres, et doit être supprimé une fois le débogage terminé.

  :::tip
  Les avertissements ne fonctionnent que pendant le développement, donc cette configuration est ignorée en mode production.
  :::

* **Exemple**

  ```js
  app.config.warnHandler = (msg, instance, trace) => {
    // `trace` est la trace hiérarchique du composant
  }
  ```

## app.config.performance {#app-config-performance}

Définissez-le sur `true` pour activer le suivi des performances d'initialisation, de compilation, de rendu et de correction des composants dans le panneau de performances/timeline de l'outil de développement du navigateur. Fonctionne uniquement en mode développement et dans les navigateurs prenant en charge l'API [performance.mark](https://developer.mozilla.org/fr/docs/Web/API/Performance/mark).

* **Type :** : `boolean`

* **Voir aussi** [Guide - Performance](/guide/best-practices/performance)

## app.config.compilerOptions {#app-config-compileroptions}

Configure des options du compilateur fonctionnant à l'exécution. Les valeurs définies sur cet objet seront transmises au compilateur de template dans le navigateur et affecteront chaque composant de l'application configurée. Notez que vous pouvez également remplacer ces options par composant à l'aide de l'[option `compilerOptions`](/api/options-rendering#compileroptions).

::: warning Important
Cette option de configuration n'est respectée que lors de l'utilisation de la version complète (c'est-à-dire `vue.js` qui peut compiler des templates dans le navigateur). Si vous utilisez le build uniquement à l'exécution avec une configuration de build, les options du compilateur doivent être transmises plutôt à `@vue/compiler-dom` via les configurations de l'outil de build.

* Pour `vue-loader` : [passez via l'option `compilerOptions` du loader](https://vue-loader.vuejs.org/options.html#compileroptions). Aussi, regardez [comment le configurer avec `vue-cli`](https://cli.vuejs.org/guide/webpack.html#modifying-options-of-a-loader).

* Pour `vite` : [passez via les options de `@vitejs/plugin-vue`](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options).
  :::

### app.config.compilerOptions.isCustomElement {#app-config-compileroptions-iscustomelement}

Spécifie une méthode de vérification pour reconnaître les éléments personnalisés (Web Component).

* **Type :** `(tag: string) => boolean`

* **Détails**

  Doit renvoyer `true` si la balise doit être traitée comme un élément personnalisé. Pour une balise qui correspond, Vue la restituera en tant qu'élément natif au lieu d'essayer de la résoudre en tant que composant Vue.

  Les éléments natifs HTML et SVG n'ont pas besoin d'être mis en correspondance dans cette fonction - l'analyseur de Vue les reconnaît automatiquement.

* **Exemple**

  ```js
  // traite toutes les balises commençant par 'ion-' comme des éléments personnalisés
  app.config.compilerOptions.isCustomElement = (tag) => {
    return tag.startsWith('ion-')
  }
  ```

* **Voir aussi** [Vue et les Web Components](/guide/extras/web-components)

### app.config.compilerOptions.whitespace {#app-config-compileroptions-whitespace}

Ajuste le comportement des espaces blancs des templates.

* **Type :** `'condense' | 'preserve'`

* **Par défaut :** `'condense'`

* **Détails**

  Vue supprime/condense les caractères d'espacement dans les templates pour produire une sortie compilée plus efficace. La stratégie par défaut est "condense", avec le comportement suivant :

  1. Les caractères d'espacement de début/fin à l'intérieur d'un élément sont condensés en un seul espace.
  2. Les caractères d'espacement entre les éléments qui contiennent des retours à la ligne sont supprimés.
  3. Les caractères d'espacement consécutifs dans les nœuds de texte sont condensés en un seul espace.

  Régler cette option sur `'preserve'` désactivera (2) et (3).

* **Exemple**

  ```js
  app.config.compilerOptions.whitespace = 'preserve'
  ```

### app.config.compilerOptions.delimiters {#app-config-compileroptions-delimiters}

Ajuste les délimiteurs utilisés pour l'interpolation de texte dans le template.

* **Type :** `[string, string]`

* **Par défaut :** `{{ "['\u007b\u007b', '\u007d\u007d']" }}`

* **Détails**

  Ceci est généralement utilisé pour éviter les conflits avec les frameworks côté serveur qui utilisent également la syntaxe des moustaches.

* **Exemple**

  ```js
  // Délimiteurs changés en style de chaîne de template ES6
  app.config.compilerOptions.delimiters = ['${', '}']
  ```

### app.config.compilerOptions.comments {#app-config-compileroptions-comments}

Ajuste le traitement des commentaires HTML dans les modèles.

* **Type :** `boolean`

* **Par défaut :** `false`

* **Détails**

  Par défaut, Vue supprimera les commentaires en production. Définir cette option sur `true` forcera Vue à conserver les commentaires même en production. Les commentaires sont toujours conservés pendant le développement. Cette option est généralement utilisée lorsque Vue est utilisé avec d'autres bibliothèques qui reposent sur des commentaires HTML.

* **Exemple**

  ```js
  app.config.compilerOptions.comments = true
  ```

## app.config.globalProperties {#app-config-globalproperties}

Un objet qui peut être utilisé pour enregistrer des propriétés globales accessibles sur n'importe quelle instance de composant dans l'application.

* **Type :**

  ```ts
  interface AppConfig {
    globalProperties: Record<string, any>
  }
  ```

* **Détails**

  Il s'agit du remplaçant de `Vue.prototype` de Vue 2 qui n'est plus présent dans Vue 3. Comme pour tout ce qui est global, cela doit être utilisé avec attention.

  Si une propriété globale est en conflit avec la propriété propre d'un composant, la propriété propre du composant aura une priorité plus élevée.

* **Utilisation :**

  ```js
  app.config.globalProperties.msg = 'hello'
  ```

  Cela rend `msg` disponible dans n'importe quel template de composant de l'application, ainsi que sur `this` de n'importe quelle instance de composant :

  ```js
  export default {
    mounted() {
      console.log(this.msg) // 'hello'
    }
  }
  ```

* **Voir aussi** [Guide - Augmenter les propriétés globales](/guide/typescript/options-api#augmenting-global-properties)&#x20;

## app.config.optionMergeStrategies {#app-config-optionmergestrategies}

Objet permettant de définir des stratégies de fusion pour les options de composants personnalisés.

* **Type :**

  ```ts
  interface AppConfig {
    optionMergeStrategies: Record<string, OptionMergeFunction>
  }

  type OptionMergeFunction = (to: unknown, from: unknown) => any
  ```

* **Détails**

  Certains plugins/bibliothèques ajoutent la prise en charge des options de composants personnalisés (en injectant des mixins globaux). Ces options peuvent nécessiter une logique de fusion spéciale lorsque la même option doit être "fusionnée" à partir de plusieurs sources (par exemple, mixins ou héritage de composants).

  Une fonction de stratégie de fusion peut être enregistrée pour une option personnalisée en l'affectant à l'objet `app.config.optionMergeStrategies` en utilisant le nom de l'option comme clé.

  La fonction de stratégie de fusion reçoit la valeur de cette option définie sur les instances parent et enfant comme premier et deuxième arguments, respectivement.

* **Exemple**

  ```js
  const app = createApp({
    // option d'ici
    msg: 'Vue',
    // option d'un mixin
    mixins: [
      {
        msg: 'Hello '
      }
    ],
    mounted() {
      // options fusionnées exposées dans this.$options
      console.log(this.$options.msg)
    }
  })

  // définie une stratégie de fusion personnalisée pour `msg`
  app.config.optionMergeStrategies.msg = (parent, child) => {
    return (parent || '') + (child || '')
  }

  app.mount('#app')
  // logue 'Hello Vue'
  ```

* **Voir aussi** [L'instance de composant - `$options`](/api/component-instance#options)

## app.config.idPrefix  {#app-config-idprefix}

Configurer un préfixe pour tous les identifiants générés via [useId()](/api/composition-api-helpers.html#useid) dans l'application.

* **Type:** `string`

* **Default:** `undefined`

* **Example**

  ```js
  app.config.idPrefix = 'myApp'
  ```

  ```js
  // in a component:
  const id1 = useId() // 'myApp:0'
  const id2 = useId() // 'myApp:1'
  ```

## app.config.throwUnhandledErrorInProduction  {#app-config-throwunhandlederrorinproduction}

Forcer l'envoi des erreurs non gérées en mode production.

* **Type:** `boolean`

* **Default:** `false`

* **Détails**

  Par défaut, les erreurs lancées dans une application Vue mais non gérées explicitement ont un comportement différent entre les modes développement et production :

  * Lors du développement, l'erreur est lancée et peut éventuellement faire planter l'application. Il s'agit de rendre l'erreur plus visible afin qu'elle puisse être remarquée et corrigée au cours du développement.

  * En production, l'erreur ne sera consignée que dans la console afin de minimiser l'impact sur les utilisateurs finaux. Toutefois, cela peut empêcher les erreurs qui ne se produisent qu'en production d'être détectées par les services de surveillance des erreurs.

  En mettant `app.config.throwUnhandledErrorInProduction` à `true`, les erreurs non gérées seront lancées même en mode production.

---

---
url: /guide/components/attrs.md
---

# Attributs implicitement déclarés (Fallthrough Attributes) {#fallthrough-attributes}

> Cette page suppose que vous avez déjà lu les [principes fondamentaux des composants](/guide/essentials/component-basics). Lisez-les d'abord si vous débutez avec les composants.

## Héritage d'attribut {#attribute-inheritance}

Un attribut implicitement déclaré (ou "fallthrough attribute") est un attribut ou un écouteur d'événement `v-on` qui est passé à un composant, mais qui n'est pas explicitement déclaré dans les [props](./props) ou les [émissions](./events#declaring-emitted-events) du composant récepteur. Des exemples courants de ceci incluent les attributs `class`, `style` et `id`.

Lorsqu'un composant affiche un seul élément racine, les attributs implicitement déclarés sont automatiquement ajoutés aux attributs de l'élément racine. Par exemple, le composant `<MyButton>` avec le template suivant :

```vue-html
<!-- template de <MyButton> -->
<button>Cliquez-Moi</button>
```

Et un parent utilisant ce composant avec :

```vue-html
<MyButton class="large" />
```

Le DOM rendu final serait :

```html
<button class="large">Cliquez-Moi</button>
```

Ici, `<MyButton>` n'a pas déclaré `class` comme une prop acceptée. Par conséquent, `class` est traitée comme un attribut implicitement déclaré et automatiquement ajoutée à l'élément racine de `<MyButton>`.

### Fusion de `class` and `style` {#class-and-style-merging}

Si l'élément racine du composant enfant a déjà des attributs `class` ou `style` existants, il sera fusionné avec les valeurs `class` et `style` héritées du parent. Supposons que nous modifions le template de `<MyButton>` dans l'exemple précédent en :

```vue-html
<!-- template de <MyButton> -->
<button class="btn">Cliquez-Moi</button>
```

Ainsi, le DOM final rendu deviendrait :

```html
<button class="btn large">Cliquez-Moi</button>
```

### Héritage de l'écouteur "v-on" {#v-on-listener-inheritance}

La même règle s'applique aux écouteurs d'événements `v-on` :

```vue-html
<MyButton @click="onClick" />
```

L'écouteur de `click` sera ajouté à l'élément racine de `<MyButton>`, c'est-à-dire l'élément natif `<button>`. Lorsque le `<button>` natif est cliqué, il déclenchera la méthode `onClick` du composant parent. Si le `<button>` natif a déjà un écouteur de `click` lié à `v-on`, alors les deux écouteurs se déclencheront.

### Héritage des composants imbriqués {#nested-component-inheritance}

Si un composant rend un autre composant comme son nœud racine, par exemple, nous avons refactorisé `<MyButton>` pour rendre un `<BaseButton>` comme sa racine :

```vue-html
<!-- template de <MyButton/> qui affiche uniquement un autre composant -->
<BaseButton />
```

Alors, les attributs implicitement déclarés reçus par `<MyButton>` seront automatiquement transmis à `<BaseButton>`.

Notez que :

1. Les attributs transférés n'incluent aucun attribut déclaré en tant que props, ou écouteurs `v-on` d'événements déclarés par `<MyButton>` - en d'autres termes, les props et écouteurs déclarés ont été "consommés" par `<MyButton>`.

2. Les attributs transférés peuvent être acceptés comme props par `<BaseButton>`, s'ils sont déclarés par celui-ci.

## Désactivation de l'héritage d'attribut {#disabling-attribute-inheritance}

Si vous **ne souhaitez pas** qu'un composant hérite automatiquement des attributs, vous pouvez définir `inheritAttrs: false` dans les options du composant.

Depuis la version 3.3, vous pouvez également utiliser [`defineOptions`](/api/sfc-script-setup#defineoptions) directement dans `<script setup>`:

```vue
<script setup>
defineOptions({
  inheritAttrs: false
})
// ...setup logic
</script>
```

Le scénario courant de désactivation de l'héritage d'attribut est lorsque les attributs doivent être appliqués à des éléments autres que le nœud racine. En définissant l'option `inheritAttrs` sur `false`, vous pouvez prendre le contrôle total sur l'endroit où les attributs fallthrough doivent être appliqués.

Ces attributs sont accessibles directement dans les expressions de template en tant que `$attrs` :

```vue-html
<span>Fallthrough attributes: {{ $attrs }}</span>
```

L'objet `$attrs` inclut tous les attributs qui ne sont pas déclarés par les `props` du composant ou options `emits` (par exemple, `class`, `style`, les écouteurs `v-on`, etc.).

Quelques notes :

* Contrairement aux props, les attributs implicitement déclarés conservent leur casse d'origine en JavaScript, donc un attribut comme `foo-bar` doit être accédé en tant que `$attrs['foo-bar']`.

* Un écouteur d'événement `v-on` comme `@click` sera exposé sur l'objet en tant que fonction sous `$attrs.onClick`.

En utilisant notre composant exemple `<MyButton>` de la [section précédente](#attribute-inheritance) - nous pouvons parfois avoir besoin d'envelopper l'élément `<button>` réel avec un `<div>` supplémentaire à des fins de style :

```vue-html
<div class="btn-wrapper">
  <button class="btn">Cliquez-Moi</button>
</div>
```

Nous voulons que tous les attributs implicitement déclarés tels que `class` et les écouteurs `v-on` soient appliqués au `<button>` sous-jacent, et non au `<div>`. Nous pouvons y parvenir avec `inheritAttrs: false` et `v-bind="$attrs"`:

```vue-html{2}
<div class="btn-wrapper">
  <button class="btn" v-bind="$attrs">Cliquez-Moi</button>
</div>
```

Rappelez-vous que [`v-bind` sans argument](/guide/essentials/template-syntax#dynamically-binding-multiple-attributes) lie toutes les propriétés d'un objet en tant qu'attributs de l'élément cible.

## Héritage d'attributs sur plusieurs nœuds racine {#attribute-inheritance-on-multiple-root-nodes}

Contrairement aux composants avec un seul nœud racine, les composants avec plusieurs nœuds racine n'ont pas de comportement automatique concenant les attributs impliciitement déclarés. Si `$attrs` n'est pas lié explicitement, un avertissement lors de l'exécution sera émis.

```vue-html
<CustomLayout id="custom-layout" @click="changeValue" />
```

Si `<CustomLayout>` a le template multi-racine suivant, il y aura un avertissement car Vue ne sait pas où appliquer les attributs implicitement déclarés :

```vue-html
<header>...</header>
<main>...</main>
<footer>...</footer>
```

L'avertissement sera supprimé si `$attrs` est explicitement lié :

```vue-html{2}
<header>...</header>
<main v-bind="$attrs">...</main>
<footer>...</footer>
```

## Accéder aux attributs implicitement déclarés en JavaScript {#accessing-fallthrough-attributes-in-javascript}

Si nécessaire, vous pouvez accéder aux attributs implicitement déclarés d'un composant dans `<script setup>` à l'aide de l'API `useAttrs()` :

```vue
<script setup>
import { useAttrs } from 'vue'

const attrs = useAttrs()
</script>
```

Si vous n'utilisez pas `<script setup>`, `attrs` sera exposé en tant que propriété du contexte de `setup()` :

```js
export default {
  setup(props, ctx) {
    // les attributs implicitement déclarés sont exposés en tant que ctx.attrs
    console.log(ctx.attrs)
  }
}
```

Notez que bien que l'objet `attrs` reflète toujours les derniers attributs implicitement déclarés, il n'est pas réactif (pour des raisons de performances). Vous ne pouvez pas utiliser d'observateurs pour observer ses changements. Si vous avez besoin de réactivité, utilisez une prop. De manière alternative, vous pouvez utiliser `onUpdated()` pour effectuer des tâches avec les derniers `attrs` à chaque mise à jour.

Si nécessaire, vous pouvez accéder aux attributs implicitement déclarés d'un composant via la propriété d'instance `$attrs` :

```js
export default {
  created() {
    console.log(this.$attrs)
  }
}
```

---

---
url: /api/built-in-special-attributes.md
---
# Attributs spéciaux natifs {#built-in-special-attributes}

## key {#key}

L'attribut spécial `key` est principalement utilisé comme une indication aidant l'algorithme du DOM virtuel de Vue à identifier les VNodes lors de la comparaison de la nouvelle et de l'ancienne liste de nœuds.

* **Attendu :** `number | string | symbol`

* **Détails**

  Sans clés, Vue utilise un algorithme qui minimise le mouvement des éléments et essaie de remplacer/réutiliser les éléments du même type déjà en place autant que possible. Avec des clés, il réorganisera les éléments en fonction du changement d'ordre des clés, et les éléments dont les clés ne sont plus présentes seront toujours supprimés / détruits.

  Les clés des enfants d'un même parent doivent être **uniques**. Les clés dupliquées entraîneront des erreurs de rendu.

  Le cas d'utilisation le plus courant est en combinaison avec `v-for` :

  ```vue-html
  <ul>
    <li v-for="item in items" :key="item.id">...</li>
  </ul>
  ```

  Elle peut également être utilisée pour forcer le remplacement d'un élément/composant au lieu de le réutiliser. Cela peut être utile lorsque vous voulez :

  * Déclencher correctement les hooks de cycle de vie d'un composant
  * Déclencher des transitions

  Par exemple :

  ```vue-html
  <transition>
    <span :key="text">{{ text }}</span>
  </transition>
  ```

  Quand `text` change, le `<span>` sera toujours remplacé au lieu d'être corrigé, donc une transition sera déclenchée.

* **Voir aussi** [Guide - Rendu de liste - Maintenir l'état avec `key`](/guide/essentials/list#maintaining-state-with-key)

## ref {#ref}

Désigne une [ref du template](/guide/essentials/template-refs).

* **Attendu :** `string | Function`

* **Détails**

  `ref` est utilisée pour enregistrer une référence à un élément ou à un composant enfant.

  Dans l'Options API, la référence sera enregistrée sous l'objet `this.$refs` du composant :

  ```vue-html
  <!-- stockée sous this.$refs.p -->
  <p ref="p">hello</p>
  ```

  Dans la Composition API, la référence sera stockée dans une ref avec le nom correspondant :

  ```vue
  <script setup>
  import { useTemplateRef } from 'vue'

  const pRef = useTemplateRef('p')
  </script>

  <template>
    <p ref="p">hello</p>
  </template>
  ```

  Si elle est utilisée sur un élément simple du DOM, la référence sera cet élément ; si elle est utilisée sur un composant enfant, la référence sera l'instance du composant enfant.

  De manière alternative, `ref` peut accepter une valeur de fonction qui fournit un contrôle total sur l'endroit où la référence sera stockée :

  ```vue-html
  <ChildComponent :ref="(el) => child = el" />
  ```

  Une remarque importante concernant le timing de l'enregistrement des refs : comme les refs elles-mêmes sont créées à la suite de la fonction de rendu, vous devez attendre que le composant soit monté avant d'y accéder.

  `this.$refs` est également non réactive, vous ne devez donc pas l'utiliser dans les templates pour la liaison de données.

* **Voir aussi**
  * [Guide - Template Refs](/guide/essentials/template-refs)
  * [Guide - Typer les refs du template](/guide/typescript/composition-api#typing-template-refs)&#x20;
  * [Guide - Typer les refs du template d'un composant](/guide/typescript/composition-api#typing-component-template-refs)&#x20;

## is {#is}

Utilisé pour lier les [composants dynamiques](/guide/essentials/component-basics#dynamic-components).

* **Attendu :** `string | Component`

* **Utilisation sur des éléments natifs**

  * Supporté à partir de la version 3.1

  Lorsque l'attribut "is" est utilisé sur un élément HTML natif, il sera interprété comme un [élément natif personnalisé](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example), qui est une fonctionnalité native de la plate-forme Web.

  Il existe cependant un cas d'utilisation où vous pouvez avoir besoin que Vue remplace un élément natif par un composant Vue, comme expliqué dans [Mises en garde concernant l'analyse du template DOM](/guide/essentials/component-basics#in-dom-template-parsing-caveats). Vous pouvez préfixer la valeur de l'attribut `is` avec `vue:` pour que Vue rende l'élément comme un composant Vue :

  ```vue-html
  <table>
    <tr is="vue:my-row-component"></tr>
  </table>
  ```

* **Voir aussi**

  * [Éléments spéciaux natifs - `<component>`](/api/built-in-special-elements#component)
  * [Composants dynamiques](/guide/essentials/component-basics#dynamic-components)

---

---
url: /style-guide.md
---

# Bonnes pratiques {#style-guide}

Voici le guide de style officiel pour du code spécifique à Vue. Si vous travaillez sur un projet Vue, c'est une super référence pour éviter les erreurs, les pertes de temps, et les anti-patterns. Toutefois, nous ne pensons pas que des bonnes pratiques puisse être idéales pour n'importe quelle équipe ou projet, donc les écarts faits en pleine conscience en fonction de votre expérience, la pile technique environnante, et vos valeurs personnelles sont encouragés.

La plupart du temps, nous évitons également les suggestions à propos du JavaScript ou de l'HTML en général. Que vous utilisiez des points-virgules ou des virgules ne nous dérange pas. Cela ne nous dérange pas non plus que vous utilisiez des simples ou doubles guillemets pour les valeurs des attributs. Il y a cependant des exceptions pour lesquelles nous pensons qu'un pattern particulier peut aider dans le contexte de Vue.

Pour finir, nous avons divisé les règles en quatre catégories :

## Catégories des règles {#rule-categories}

### Priorité A : Essentielle (Prévention des erreurs) {#priority-a-essential-error-prevention}

Ces règles aident à prévenir les erreurs, donc apprenez les et tenez-y vous coûte que coûte. Il peut y avoir des exceptions, mais elles sont rares et devraient être faites par ceux ayant une expertise à la fois dans JavaScript et dans Vue.

* [Voir toutes les règles de priorité A](./rules-essential)

### Priorité B: Fortement recommandée {#priority-b-strongly-recommended}

Ces règles ont été pensées pour améliorer la lisibilité et/ou l'expérience des développeurs dans la plupart des projets. Votre code fonctionnera toujours sans elles, mais les digressions doivent être rares et bien justifiées.

* [Voir toutes les règles de priorité B](./rules-strongly-recommended)

### Priorité C: Recommandée {#priority-c-recommended}

Lorsqu'il existe plusieurs options correctes, un choix arbitraire peut être fait pour assurer une certaine cohérence. Dans ces règles, nous décrivons chaque option acceptable et suggérons un choix par défaut. Cela signifie que vous être libres de faire un choix différent dans votre code, tant que vous restez cohérent et avez une bonne raison. Vous avez certainement une bonne raison ! En adaptant les standards de la communauté, vous allez :

1. Entraîner votre cerveau à analyser plus facilement la plupart du code que vous rencontrerez
2. Serez capable de copier et coller la plupart du code de la communauté sans modification
3. Réaliserez souvent que les nouvelles recrues sont habituées à votre style de code favori, du moins en ce qui concerne Vue

* [Voir toutes les règles de priorité C](./rules-recommended)

### Priorité D: À utiliser avec précaution {#priority-d-use-with-caution}

Certaines fonctionnalités de Vue existent pour prévoir de rares cas particuliers ou des migrations plus douces depuis une base de code héritée. Toutefois, lorsqu'elles sont surexploitées, elles peuvent rendre le code plus difficile à maintenir ou même devenir une source de bugs. Ces règles mettent en lumière ces fonctionnalités potentiellement risquées, en décrivant quand et pourquoi elles devraient être évitées.

* [Voir toutes les règles de priorité D](./rules-use-with-caution)

---

---
url: /guide/reusability/composables.md
---
# Composables {#composables}

:::tip
Cette section suppose une connaissance de base de la Composition API. Si vous avez appris Vue avec l'Options API uniquement, vous pouvez définir la préférence de l'API sur la Composition API (à l'aide de l'interrupteur en haut de la barre latérale gauche) et relire les [Principes fondamentaux des composants](/guide/essentials/reactivity-fundamentals) et [Les hooks du cycle de vie](/guide/essentials/lifecycle).
:::

## Qu'est-ce qu'un "Composable"? {#what-is-a-composable}

Dans le contexte des applications Vue, un "composable" est une fonction qui exploite la Composition API de Vue pour encapsuler et réutiliser une **logique avec état**.

Lors de la création d'applications frontend, nous devons souvent réutiliser de la logique pour les tâches courantes. Par exemple, nous pouvons avoir besoin de formater des dates à de nombreux endroits, on extrait une fonction réutilisable pour cela. Cette fonction de formatage encapsule la **logique sans état** : elle prend des arguments et renvoie immédiatement la sortie attendue. Il existe de nombreuses bibliothèques pour réutiliser la logique sans état, par exemple [lodash](https://lodash.com/) et [date-fns](https://date-fns.org/), dont vous avez peut-être déjà entendu parler.

En revanche, la logique avec état implique la gestion d'un état qui change au fil du temps. Un exemple simple serait de suivre la position actuelle de la souris sur une page. Dans des scénarios réels, il peut également s'agir d'une logique plus complexe, telle que des interactions tactiles ou l'état de la connexion à une base de données.

## Exemple de suivi de la souris {#mouse-tracker-example}

Si nous devions implémenter la fonctionnalité de suivi de la souris à l'aide de la Composition API directement dans un composant, cela ressemblerait à ceci :

```vue [MouseComponent.vue]
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

const x = ref(0)
const y = ref(0)

function update(event) {
  x.value = event.pageX
  y.value = event.pageY
}

onMounted(() => window.addEventListener('mousemove', update))
onUnmounted(() => window.removeEventListener('mousemove', update))
</script>

<template>Mouse position is at: {{ x }}, {{ y }}</template>
```

Mais que se passe-t-il si nous voulons réutiliser la même logique dans plusieurs composants ? Nous pouvons extraire la logique dans un fichier externe, en tant que fonction composable :

```js [mouse.js]
import { ref, onMounted, onUnmounted } from 'vue'

// par convention, les noms de fonctions composables commencent par "use"
export function useMouse() {
  // état encapsulé et géré par le composable
  const x = ref(0)
  const y = ref(0)

  // un composable peut mettre à jour son état géré au fil du temps.
  function update(event) {
    x.value = event.pageX
    y.value = event.pageY
  }

  // un composable peut également s'accrocher au cycle de vie de son composant
  // propriétaire pour configurer et démonter les effets de bord.
  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  // expose l'état géré comme valeur de retour
  return { x, y }
}
```

Et voici comment il peut être utilisé dans les composants :

```vue [MouseComponent.vue]
<script setup>
import { useMouse } from './mouse.js'

const { x, y } = useMouse()
</script>

<template>Mouse position is at: {{ x }}, {{ y }}</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNqNkj1rwzAQhv/KocUOGKVzSAIdurVjoQUvJj4XlfgkJNmxMfrvPcmJkkKHLrbu69H7SlrEszFyHFDsxN6drDIeHPrBHGtSvdHWwwKDwzfNHwjQWd1DIbd9jOW3K2qq6aTJxb6pgpl7Dnmg3NS0365YBnLgsTfnxiNHACvUaKe80gTKQeN3sDAIQqjignEhIvKYqMRta1acFVrsKtDEQPLYxuU7cV8Msmg2mdTilIa6gU5p27tYWKKq1c3ENphaPrGFW25+yMXsHWFaFlfiiOSvFIBJjs15QJ5JeWmaL/xYS/Mfpc9YYrPxl52ULOpwhIuiVl9k07Yvsf9VOY+EtizSWfR6xKK6itgkvQ/+fyNs6v4XJXIsPwVL+WprCiL8AEUxw5s=)

Comme nous pouvons le voir, la logique de base reste identique, tout ce que nous avions à faire était de la déplacer dans une fonction externe et de renvoyer l'état qui devrait être exposé. Tout comme à l'intérieur d'un composant, vous pouvez utiliser la gamme complète des [Fonctions de la Composition API](/api/#composition-api) dans les composables. La même fonctionnalité `useMouse()` peut désormais être utilisée dans n'importe quel composant.

La partie intéressante des composables est que vous pouvez également les imbriquer : une fonction composable peut appeler une ou plusieurs autres fonctions composables. Cela nous permet de composer une logique complexe à l'aide de petites unités isolées, de la même manière que nous composons une application entière à l'aide de composants. En fait, c'est pourquoi nous avons décidé d'appeler la collection d'API rendant ce modèle possible **Composition API**.

Par exemple, nous pouvons extraire la logique d'ajout et de suppression d'un écouteur d'événement DOM dans son propre composable :

```js [event.js]
import { onMounted, onUnmounted } from 'vue'

export function useEventListener(target, event, callback) {
  // au lieu d'utiliser target, vous pouvez aussi
  // utiliser un sélecteur CSS pour trouver l'élément cible
  onMounted(() => target.addEventListener(event, callback))
  onUnmounted(() => target.removeEventListener(event, callback))
}
```

Et maintenant, notre composable `useMouse()` peut être simplifié en :

```js{2,8-11} [mouse.js]
import { ref } from 'vue'
import { useEventListener } from './event'

export function useMouse() {
  const x = ref(0)
  const y = ref(0)

  useEventListener(window, 'mousemove', (event) => {
    x.value = event.pageX
    y.value = event.pageY
  })

  return { x, y }
}
```

:::tip
Chaque instance de composant appelant `useMouse()` créera ses propres copies de l'état `x` et `y` afin qu'elles n'interfèrent pas l'une avec l'autre. Si vous souhaitez gérer l'état partagé entre les composants, lisez le chapitre [Gestion d'état](/guide/scaling-up/state-management).
:::

## Exemple d'état asynchrone {#async-state-example}

Le composable `useMouse()` ne prend aucun argument, alors regardons un autre exemple qui en utilise un. Lors de la récupération de données asynchrone, nous devons souvent gérer différents états : chargement, succès et erreur :

```vue
<script setup>
import { ref } from 'vue'

const data = ref(null)
const error = ref(null)

fetch('...')
  .then((res) => res.json())
  .then((json) => (data.value = json))
  .catch((err) => (error.value = err))
</script>

<template>
  <div v-if="error">Oops! Error encountered: {{ error.message }}</div>
  <div v-else-if="data">
    Data loaded:
    <pre>{{ data }}</pre>
  </div>
  <div v-else>Loading...</div>
</template>
```

Il serait fastidieux de devoir répéter ce modèle dans chaque composant qui doit récupérer des données. Extrayons-le dans un composable :

```js [fetch.js]
import { ref } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)

  fetch(url)
    .then((res) => res.json())
    .then((json) => (data.value = json))
    .catch((err) => (error.value = err))

  return { data, error }
}
```

Maintenant, dans notre composant, nous pouvons simplement faire :

```vue
<script setup>
import { useFetch } from './fetch.js'

const { data, error } = useFetch('...')
</script>
```

### Acceptation de l'état réactif {#accepting-reactive-state}

`useFetch()` prend une chaîne d'URL statique en entrée, il n'effectue donc la récupération qu'une seule fois. Que se passe-t-il si nous voulons qu'il récupère chaque fois que l'URL change ? Nous pouvons y parvenir en acceptant également une `ref` comme argument :

Par exemple, `useFetch()` devrait être capable d'accepter une ref :

```js
const url = ref('/initial-url')

const { data, error } = useFetch(url)

// cela devrait déclencher un nouveau rendu
url.value = '/new-url'
```

Ou, accepter une fonction [accesseur](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description) :

```js
// nouveau rendu lorsque props.id change
const { data, error } = useFetch(() => `/posts/${props.id}`)
```

Nous pouvons refactoriser notre implémentation avec les API [`watchEffect()`](/api/reactivity-core.html#watcheffect) et [`toValue()`](/api/reactivity-utilities.html#tovalue) :

```js{7,12} [fetch.js]
import { ref, watchEffect, toValue } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)

  const fetchData = () => {
    // réinitialiser l'état avant de récupérer..
    data.value = null
    error.value = null

    fetch(toValue(url))
      .then((res) => res.json())
      .then((json) => (data.value = json))
      .catch((err) => (error.value = err))
  }

  watchEffect(() => {
    fetchData()
  })

  return { data, error }
}
```

`toValue()` est une API ajoutée en 3.3. Elle est conçue pour normaliser les refs ou les accesseurs en valeurs. Si l'argument est une ref, elle retourne la valeur de la ref ; si l'argument est une fonction, elle appellera la fonction et retournera sa valeur de retour. Sinon, elle retourne l'argument tel quel. Son fonctionnement est similaire à celui de [`unref()`](/api/reactivity-utilities.html#unref), mais avec un traitement spécial pour les fonctions.

Notez que `toValue(url)` est appelée **à l'intérieur** du callback `watchEffect`. Cela garantit que toutes les dépendances réactives accédées pendant la normalisation de `toValue()` sont traquées par l'observateur.

Cette version de `useFetch()` accepte maintenant les chaînes d'URL statiques, les refs et les accesseurs, ce qui la rend beaucoup plus flexible. L'effet d'observation s'exécutera immédiatement, et suivra toutes les dépendances accédées pendant `toValue(url)`. Si aucune dépendance n'est suivie (par exemple si l'url est déjà une chaîne), l'effet ne s'exécute qu'une seule fois ; sinon, il s'exécute à nouveau chaque fois qu'une dépendance suivie change.

Voici [la version mise à jour de `useFetch()`](https://play.vuejs.org/#eNp9Vdtu20YQ/ZUpUUA0qpAOjL4YktCbC7Rom8BN8sSHrMihtfZql9iLZEHgv2dml6SpxMiDIWkuZ+acmR2fs1+7rjgEzG6zlaut7Dw49KHbVFruO2M9nMFiu4Ta7LvgsYEeWmv2sKCkxSwoOPwTfb2b/EU5mopHR5GVro12HrbC4UerYA2Lnfeduy3LR2d0p0SNO6MatIU/dbI2DRZUtPSmMa4kgJQuG8qkjvLF28XVaAwRb2wxz69gvZkK/UQ5xUGogBQ/ZpyhEV4sAa01lnpeTwRyApsFWvT2RO6Eea40THBMgfq6NLwlS1/pVZnUJB3ph8c98fNIvwD+MaKBzkQut2xYbYP3RsPhTWvsusokSA0/Vxn8UitZP7GFSX/+8Sz7z1W2OZ9BQt+vypQXS1R+1cgDQciW4iMrimR0wu8270znfoC7SBaJWdAeLTa3QFgxuNijc+IBIy5PPyYOjU19RDEI954/Z/UptKTy6VvqA5XD1AwLTTl/0Aco4s5lV51F5sG+VJJ+v4qxYbmkfiiKYvSvyknPbJnNtoyW+HJpj4Icd22LtV+CN5/ikC4XuNL4HFPaoGsvie3FIqSJp1WIzabl00HxkoyetEVfufhv1kAu3EnX8z0CKEtKofcGzhMb2CItAELL1SPlFMV1pwVj+GROc/vWPoc26oDgdxhfSArlLnbWaBOcOoEzIP3CgbeifqLXLRyICaDBDnVD+3KC7emCSyQ4sifspOx61Hh4Qy/d8BsaOEdkYb1sZS2FoiJKnIC6FbqhsaTVZfk8gDgK6cHLPZowFGUzAQTNWl/BUSrFbzRYHXmSdeAp28RMsI0fyFDaUJg9Spd0SbERZcvZDBRleCPdQMCPh8ARwdRRnBCTjGz5WkT0i0GlSMqixTR6VKyHmmWEHIfV+naSOETyRx8vEYwMv7pa8dJU+hU9Kz2t86ReqjcgaTzCe3oGpEOeD4uyJOcjTXe+obScHwaAi82lo9dC/q/wuyINjrwbuC5uZrS4WAQeyTN9ftOXIVwy537iecoX92kR4q/F1UvqIMsSbq6vo5XF6ekCeEcTauVDFJpuQESvMv53IBXadx3r4KqMrt0w0kwoZY5/R5u3AZejvd5h/fSK/dE9s63K3vN7tQesssnnhX1An9x3//+Hz/R9cu5NExRFf8d5zyIF7jGF/RZ0Q23P4mK3f8XLRmfhg7t79qjdSIobjXLE+Cqju/b7d6i/tHtT3MQ8VrH/Ahstp5A=), avec un délai artificiel et une erreur aléatoire à des fins de démonstration.

## Conventions et bonnes pratiques {#conventions-and-best-practices}

### Nommage {#naming}

C'est une convention de nommer les fonctions composables avec des noms camelCase qui commencent par "use".

### Arguments d'entrée {#input-arguments}

Un composable peut accepter des arguments ref même s'il ne s'appuie pas sur eux pour la réactivité. Si vous écrivez un composable qui peut être utilisé par d'autres développeurs, c'est une bonne idée de gérer le cas où les arguments d'entrée sont des refs au lieu de valeurs brutes. La fonction utilitaire [`toValue()`](/api/reactivity-utilities#tovalue) sera utile à cette fin :

```js
import { toValue } from 'vue'

function useFeature(maybeRefOrGetter) {
  // Si maybeRefOrGetter est une ref ou un accesseur,
  // sa valeur normalisée sera retournée.
  // Sinon, elle sera renvoyée telle quelle.
  const value = toValue(maybeRefOrGetter)
}
```

Si votre composable crée des effets réactifs lorsque l'entrée est une référence ou un accesseur, assurez-vous soit de surveiller explicitement la référence / l'accesseur avec `watch()`, ou d'appeler `toValue()` à l'intérieur d'un `watchEffect()` afin qu'il soit correctement suivi.

L'implémentation [useFetch() présentée précédemment](#accepting-reactive-state) fournit un exemple concret d'un composable qui accepte des refs, des accesseurs et des valeurs simples en tant qu'argument d'entrée.

### Valeurs de retour {#return-values}

Vous avez probablement remarqué que nous utilisons exclusivement `ref()` au lieu de `reactive()` dans les composables. La convention recommandée est que les composables renvoient toujours un objet simple et non réactif contenant plusieurs références. Cela lui permet d'être déstructuré en composants tout en gardant de la réactivité :

```js
// x et y sont des refs
const { x, y } = useMouse()
```

Retourner un objet réactif à partir d'un composable fera perdre à ses membres la connexion de réactivité de l'état à l'intérieur du composable, tandis que les références conserveront cette connexion.

Si vous préférez utiliser l'état renvoyé par les composables en tant que propriétés d'objet, vous pouvez envelopper l'objet renvoyé avec `reactive()` afin que les références soient développées. Par exemple :

```js
const mouse = reactive(useMouse())
// mouse.x est lié à la référence d'origine
console.log(mouse.x)
```

```vue-html
Mouse position is at: {{ mouse.x }}, {{ mouse.y }}
```

### Effets de bord {#side-effects}

C'est OK d'effectuer des effets de bord (par exemple, ajouter des écouteurs d'événements DOM ou récupérer des données) dans les composables, mais faites attention aux règles suivantes :

* Si vous travaillez sur une application qui utilise du [Rendu côté serveur](/guide/scaling-up/ssr) (SSR), assurez-vous d'effectuer des effets de bord spécifiques au DOM dans les hooks de cycle de vie post-montage, par ex. `onMounted()`. Ces hooks ne sont appelés que dans le navigateur, vous pouvez donc être sûr que le code qu'ils contiennent a bien accès au DOM.

* N'oubliez pas de nettoyer les effets de bord dans `onUnmount()`. Par exemple, si un composable configure un écouteur d'événement DOM, il doit supprimer cet écouteur dans `onUnmount()` comme nous l'avons vu dans l'exemple `useMouse()`. Ça peut être une bonne idée d'utiliser un composable qui le fait automatiquement pour vous, comme l'exemple `useEventListener()`.

### Restriction d'usage {#usage-restrictions}

Les composables ne peuvent être appelés que dans `<script setup>` ou dans le hook `setup()`. Ils ne doivent être appelés que de manière **synchrone** dans ces contextes. Dans certains cas, vous pouvez également les appeler dans des hooks de cycle de vie comme `onMounted()`.

Ces restrictions sont importantes car ce sont ces contextes où Vue est capable de déterminer l'instance de composant active actuelle. L'accès à une instance de composant actif est nécessaire pour que :

1. Les hooks de cycle de vie puissent y être enregistrés.

2. Les observateurs puissent y être liés, afin qu'ils puissent être supprimés lorsque l'instance est démontée pour éviter les fuites de mémoire.

:::tip
`<script setup>` est le seul endroit où vous pouvez appeler des composables **après** avoir utilisé `await`. Le compilateur restaure automatiquement le contexte d'instance actif pour vous après l'opération asynchrone.
:::

## Extraction des composables pour l'organisation de son code {#extracting-composables-for-code-organization}

Les composables peuvent être extraits non seulement pour être réutilisés, mais aussi au bénéfice de l'organisation du code. Au fur et à mesure que la complexité de vos composants augmente, vous pouvez vous retrouver avec des composants trop volumineux pour naviguer et raisonner. La Composition API vous offre toute la flexibilité nécessaire pour organiser votre code de composant en fonctions plus petites selon leurs responsabilités logiques :

```vue
<script setup>
import { useFeatureA } from './featureA.js'
import { useFeatureB } from './featureB.js'
import { useFeatureC } from './featureC.js'

const { foo, bar } = useFeatureA()
const { baz } = useFeatureB(foo)
const { qux } = useFeatureC(baz)
</script>
```

Dans une certaine mesure, vous pouvez considérer ces composables extraits comme des services à portée de composant qui peuvent communiquer entre eux.

## Utilisation de composables dans l'Options API {#using-composables-in-options-api}

Si vous utilisez l'Options API, les éléments composables doivent être appelés dans `setup()`, et les liaisons renvoyées doivent être renvoyées par `setup()` afin qu'elles soient exposées à `this` et au template :

```js
import { useMouse } from './mouse.js'
import { useFetch } from './fetch.js'

export default {
  setup() {
    const { x, y } = useMouse()
    const { data, error } = useFetch('...')
    return { x, y, data, error }
  },
  mounted() {
    // Les propriétés exposées de setup() sont accessibles sur `this`
    console.log(this.x)
  }
  // ...autres options
}
```

## Comparaisons avec d'autres techniques {#Comparisons with Other Techniques}

### vs. les mixins {#vs-mixins}

Les utilisateurs venant de Vue 2 sont familiers avec l'option [mixins](/api/options-composition#mixins), qui permet d'extraire la logique des composants dans des unités réutilisables. Les mixins présentent trois principaux inconvénients :

1. **Source de propriétés peu claire** : lors de l'utilisation de nombreux mixins, il devient difficile de savoir quelle propriété d'instance est injectée par quel mixin, ce qui rend difficile le suivi de l'implémentation et la compréhension du comportement du composant. C'est aussi pourquoi nous recommandons d'utiliser le modèle refs + destructure pour les composables : il rend la source de la propriété claire lors de la consommation de composants.

2. **Collisions d'espaces de noms** : plusieurs mixins d'auteurs différents peuvent potentiellement enregistrer les mêmes clés de propriété, provoquant des collisions d'espaces de noms. Avec les composables, vous pouvez renommer les variables déstructurées s'il existe des clés en conflit de différents composables.

3. **Communication implicite inter-mixins** : plusieurs mixins qui doivent interagir les uns avec les autres doivent s'appuyer sur des clés de propriété partagées, ce qui les rend implicitement couplés. Avec les composables, les valeurs renvoyées par un composable peuvent être transmises à un autre en tant qu'arguments, tout comme les fonctions normales.

Pour les raisons ci-dessus, nous ne recommandons plus d'utiliser des mixins dans Vue 3. La fonctionnalité est conservée uniquement pour des raisons de migration et de familiarité.

### vs. Composants sans affichage {#vs-renderless-components}

Dans le chapitre sur les slots de composants, nous avons discuté du modèle du [Composant sans affichage](/guide/components/slots#renderless-components) basé sur des slots délimités. Nous avons même implémenté la même démo de suivi de la souris en utilisant des composants sans affichage.

Le principal avantage des composables par rapport aux composants sans affichage est que les composables n'encourent pas de surcharge d'instance de composant supplémentaire. Lorsqu'il est utilisé dans une application entière, la quantité d'instances de composants supplémentaires créées par le modèle de Composant sans affichage peut devenir une surcharge de performances notable.

La recommandation est d'employer les composables pour centraliser une logique pure, et d'utiliser des composants pour une réutilisation de logique **et** de disposition visuelle.

### vs. les hooks de React {#vs-react-hooks}

Si vous avez de l'expérience avec React, vous remarquerez peut-être que cela ressemble beaucoup aux hooks personnalisés de React. La Composition API a été en partie inspirée des hooks de React, et les composables Vue sont en effet similaires aux hooks de React en termes de capacités de composition logique. Cependant, les composables Vue sont basés sur le système de réactivité de Vue, qui est fondamentalement différent du modèle d'exécution des hooks React. Ceci est discuté plus en détail dans la [FAQ sur la Composition API](/guide/extras/composition-api-faq#comparison-with-react-hooks).

## Lecture complémentaire {#further-reading}

* [La réactivité en détails](/guide/extras/reactivity-in-depth) : pour une compréhension de bas niveau du fonctionnement du système de réactivité de Vue.
* [Gestion d'état](/guide/scaling-up/state-management) : pour les patterns de gestion d'état partagés par plusieurs composants.
* [Tester les composables](/guide/scaling-up/testing#testing-composables) : conseils sur les tests de composables.
* [VueUse](https://vueuse.org/): une collection de composables Vue. Le code source est également une excellente ressource d'apprentissage.

---

---
url: /guide/components/async.md
---
# Composants asynchrones {#async-components}

## Utilisation de base {#basic-usage}

Dans des applications de taille importante, il est parfois judicieux de diviser l'application en plus petits morceaux et ne charger un composant depuis le serveur que lorsque cela est nécessaire. Pour rendre cela possible, Vue a une fonction [`defineAsyncComponent`](/api/general#defineasynccomponent) :

```js
import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() => {
  return new Promise((resolve, reject) => {
    // ...charger le composant depuis le serveur
    resolve(/* composant chargé */)
  })
})
// ... utiliser `AsyncComp` comme un composant normal
```

Comme vous pouvez le voir, `defineAsyncComponent` accepte une fonction de chargement qui renvoie une promesse (Promise). La fonction `resolve` de la promesse doit être appelée lorsque vous avez récupéré la définition de votre composant à partir du serveur. Vous pouvez également appeler `reject(reason)` pour indiquer que le chargement a échoué.

L'[import dynamique des modules ES](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports) renvoie également une promesse, ainsi la plupart du temps, nous l'utiliserons en combinaison avec `defineAsyncComponent`. Les Bundlers comme Vite et webpack prennent également en charge la syntaxe (et l'utiliseront comme méthode de séparation du bundle), nous pouvons donc l'utiliser pour importer des SFC Vue :

```js
import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() =>
  import('./components/MyComponent.vue')
)
```

L'`AsyncComp` résultant est un composant wrapper qui n'appelle la fonction de chargement que lorsque le composant est réellement rendu sur la page. De plus, il transmettra tous les props et slots au composant sous-jacent, de sorte que vous pouvez utiliser le wrapper asynchrone pour remplacer de manière transparente le composant d'origine tout en réalisant un lazy loading.

Comme pour les composants normaux, les composants asynchrones peuvent être [enregistrés globalement](/guide/components/registration#global-registration) à l'aide de `app.component()` :

```js
app.component(
  'MyComponent',
  defineAsyncComponent(() => import('./components/MyComponent.vue'))
)
```

Vous pouvez également utiliser `defineAsyncComponent` lors de l'[enregistrement local d'un composant](/guide/components/registration#local-registration) :

```vue
<script>
import { defineAsyncComponent } from 'vue'

export default {
  components: {
    AdminPage: defineAsyncComponent(() =>
      import('./components/AdminPageComponent.vue')
    )
  }
}
</script>

<template>
  <AdminPage />
</template>
```

Ils peuvent également être définis directement à l'intérieur de leur composant parent :

```vue
<script setup>
import { defineAsyncComponent } from 'vue'

const AdminPage = defineAsyncComponent(() =>
  import('./components/AdminPageComponent.vue')
)
</script>

<template>
  <AdminPage />
</template>
```

## Etats de chargement et d'erreur {#loading-and-error-states}

Les opérations asynchrones impliquent inévitablement des états de chargement et d'erreur - `defineAsyncComponent()` prend en charge la gestion de ces états via des options avancées :

```js
const AsyncComp = defineAsyncComponent({
  // la fonction de chargememnt
  loader: () => import('./Foo.vue'),

  // Un composant à utiliser pendant le chargement du composant asynchrone
  loadingComponent: LoadingComponent,
  // Délai avant l'affichage du composant de chargement. Par défaut : 200 ms.
  delay: 200,

  // Un composant à utiliser si le chargement échoue
  errorComponent: ErrorComponent,
  // Le composant d'erreur sera affiché si un délai d'attente est
  // fourni et dépassé. Par défaut : Infini.
  timeout: 3000
})
```

Si un composant de chargement est fourni, il sera affiché en premier lors du chargement du composant sous-jacent. Il y a un délai par défaut de 200 ms avant que le composant de chargement ne s'affiche - car sur les réseaux rapides, un état de chargement instantané peut être remplacé trop rapidement et finir par apparaitre comme un effet de scintillement à l'écran.

Si un composant d'erreur est fourni, il sera affiché lorsque la promesse renvoyée par la fonction de chargement est rejetée. Vous pouvez également spécifier un délai d'expiration pour afficher le composant d'erreur lorsque la demande prend trop de temps.

## Hydratation paresseuse  {#lazy-hydration}

> Cette section ne s'applique que si vous utilisez [Rendu côté serveur (SSR)](/guide/scaling-up/ssr).

Dans Vue 3.5+, les composants asynchrones peuvent contrôler le moment où ils sont hydratés en fournissant une stratégie d'hydratation.

* Vue fournit un certain nombre de stratégies d'hydratation intégrées. Ces stratégies intégrées doivent être importées individuellement afin qu'elles puissent être supprimées si elles ne sont pas utilisées.

* La conception est intentionnellement de bas niveau pour plus de flexibilité. Le sucre syntaxique du compilateur peut potentiellement être construit sur cette base à l'avenir, soit dans le noyau, soit dans des solutions de plus haut niveau (par exemple, Nuxt).

### Hydratation quand stable  {#hydrate-on-idle}

Hydrate par `requestIdleCallback`:

```js
import { defineAsyncComponent, hydrateOnIdle } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: hydrateOnIdle(/* optionnellement, passer un délai maximum */)
})
```

### Hydratation quand visible {#hydrate-on-visible}

Hydratez lorsque le(s) élément(s) devient(ent) visible(s) via `IntersectionObserver`.

```js
import { defineAsyncComponent, hydrateOnVisible } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: hydrateOnVisible()
})
```

Peut optionnellement passer une valeur d'objet d'options pour l'observateur :

```js
hydrateOnVisible({ rootMargin: '100px' })
```

### Hydrate on Media Query {#hydrate-on-media-query}

Hydrates when the specified media query matches.

```js
import { defineAsyncComponent, hydrateOnMediaQuery } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: hydrateOnMediaQuery('(max-width:500px)')
})
```

### Hydratation à l'interaction {#hydrate-on-interaction}

S'hydrate lorsque le ou les événements spécifiés sont déclenchés sur le ou les éléments du composant. L'événement qui a déclenché l'hydratation sera également rejoué une fois l'hydratation terminée.

```js
import { defineAsyncComponent, hydrateOnInteraction } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: hydrateOnInteraction('click')
})
```

Il peut également s'agir d'une liste de plusieurs types d'événements :

```js
hydrateOnInteraction(['wheel', 'mouseover'])
```

### Stratégie personnalisée {#custom-strategy}

```ts
import { defineAsyncComponent, type HydrationStrategy } from 'vue'

const myStrategy: HydrationStrategy = (hydrate, forEachElement) => {
  // forEachElement est un helper qui permet de parcourir tous les éléments de la racine
  // dans le DOM non hydraté du composant, puisque la racine peut être un fragment
  // au lieu d'un seul élément
  forEachElement(el => {
    // ...
  })
  // appeler `hydrate` lorsqu'il est prêt
  hydrate()
  return () => {
    // retourner une fonction de démontage si nécessaire
  }
}

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: myStrategy
})
```

## Utilisation avec Suspense {#using-with-suspense}

Les composants asynchrones peuvent être utilisés avec le composant fourni `<Suspense>`. L'interaction entre `<Suspense>` et les composants asynchrones est documentée dans le [chapitre dédié à `<Suspense>`](/guide/built-ins/suspense).

---

---
url: /guide/scaling-up/sfc.md
---
# Composants monofichiers {#single-file-components}

## Introduction {#introduction}

Les composants monofichiers (aussi appelés Single-File Components, abrégés en **SFC** avec une extension `.vue`) est un format de fichier spécial qui permet de regrouper la structure HTML, la logique JavaScript **et** le style CSS d'un composant Vue dans un seul fichier. Voici un exemple d'un SFC :

```vue
<script>
export default {
  data() {
    return {
      greeting: 'Hello World!'
    }
  }
}
</script>

<template>
  <p class="greeting">{{ greeting }}</p>
</template>

<style>
.greeting {
  color: red;
  font-weight: bold;
}
</style>
```

```vue
<script setup>
import { ref } from 'vue'
const greeting = ref('Hello World!')
</script>

<template>
  <p class="greeting">{{ greeting }}</p>
</template>

<style>
.greeting {
  color: red;
  font-weight: bold;
}
</style>
```

Comme nous pouvons le voir, les SFC de Vue sont une extension naturelle du trio classique HTML, CSS et JavaScript. Les blocs `<template>`, `<script>` et `<style>` encapsulent et regroupent la vue, la logique et le style d'un composant dans le même fichier. La syntaxe complète est définie dans la [Spécification de la syntaxe SFC](/api/sfc-spec).

## Pourquoi les composants monofichiers (SFC) {#why-sfc}

Si les SFC nécessitent une étape de compilation, les avantages sont nombreux en contrepartie :

* Créer des composants modulaires en utilisant une syntaxe HTML, CSS et JavaScript familière.
* [Collocation de responsabilités couplées](#what-about-separation-of-concerns)
* Templates précompilés sans coût de compilation au runtime
* [CSS à portée limitée au composant](/api/sfc-css-features)
* [Syntaxe plus confortable avec la Composition API](/api/sfc-script-setup)
* Meilleures optimisations à la compilation grâce à l'analyse croisée du template et des scripts.
* [Support des environnements de développement](/guide/scaling-up/tooling#ide-support) avec autocomplétion et vérification des types pour les expressions dans le template.
* Prise en charge nativement du remplacement de modules à chaud (HMR).

SFC est une caractéristique déterminante de Vue en tant que framework, et c'est l'approche recommandée pour utiliser Vue dans les scénarios suivants :

* Applications à page unique (SPA)
* Génération de sites statiques (SSG)
* Tout front-end non trivial pour lequel une étape de construction peut être justifiée pour une meilleure expérience de développement (DX).

Cela dit, nous sommes conscients qu'il y a des scénarios où les SFC peuvent sembler exagérés. C'est pourquoi Vue peut toujours être utilisé via du JavaScript sans industrialisation. Si vous cherchez simplement à agrémenter un HTML largement statique avec des interactions légères, vous pouvez vous pencher sur [petite-vue](https://github.com/vuejs/petite-vue), un sous-ensemble de Vue de 6 kb optimisé pour l'amélioration progressive.

## Comment ça marche {#how-it-works}

Vue SFC est un format de fichier spécifique au framework et doit être précompilé par [@vue/compiler-sfc](https://github.com/vuejs/core/tree/main/packages/compiler-sfc) en JavaScript et CSS standard. Un SFC compilé est un module JavaScript (ES) standard, ce qui signifie qu'avec une configuration de compilation appropriée, vous pouvez importer un SFC comme un module :

```js
import MyComponent from './MyComponent.vue'

export default {
  components: {
    MyComponent
  }
}
```

Les balises `<style>` à l'intérieur des SFC sont généralement injectées comme des balises `<style>` natives pendant le développement pour supporter les mises à jour à chaud. Pour la production, elles peuvent être extraites et fusionnées dans un seul fichier CSS.

Vous pouvez jouer avec les SFC et explorer comment ils sont compilés dans le [Playground de Vue](https://play.vuejs.org/).

Dans les projets concrets, nous intégrons généralement le compilateur SFC à un outil de construction tel que [Vite](https://vite.dev/) ou [Vue CLI](http://cli.vuejs.org/) (qui est basé sur [webpack](https://webpack.js.org/)), et Vue fournit des outils de création officiels pour vous permettre de démarrer avec les SFC aussi vite que possible. Pour plus de détails, consultez la section [Outils pour SFC](/guide/scaling-up/tooling).

## Qu'en est-il de la séparation des responsabilités ? {#what-about-separation-of-concerns}

Certains utilisateurs issus d'un milieu traditionnel de développement web peuvent craindre que les SFC ne mélangent différentes responsabilités au même endroit - ce que HTML/CSS/JS étaient censés séparer !

Pour répondre à cette question, il est important d'être d'accord sur le fait que **la séparation des responsabilités ne signifie pas séparation des types de fichiers.** Le but ultime des principes d'ingénierie est d'améliorer la maintenabilité de la base de code. La séparation des responsabilités, lorsqu'elle est appliquée de manière dogmatique comme la séparation des types de fichiers, ne nous aide pas à atteindre cet objectif dans un contexte d'applications front-end qui deviennent de plus en plus complexes.

Dans le développement d'interfaces utilisateur modernes, nous avons constaté qu'au lieu de diviser la base de code en trois énormes couches qui s'entrecroisent, il est beaucoup plus logique de les diviser en composants faiblement couplés et de les composer. À l'intérieur d'un composant, son template, sa logique et ses styles sont intrinsèquement couplés, et leur regroupement rend le composant plus cohérent et plus facile à maintenir.

Même si vous n'aimez pas l'idée des composants monofichiers, vous pouvez toujours tirer parti des fonctions de rechargement à chaud (HMR) et de précompilation en séparant votre JavaScript et votre CSS dans des fichiers distincts à l'aide de [Imports Src](/api/sfc-spec#src-imports).

---

---
url: /api/built-in-components.md
---

# Composants natifs {#built-in-components}

:::info Enregistrement et utilisation
Les composants natifs peuvent être utilisés directement dans les templates sans avoir besoin d'être enregistrés. Ils ne sont inclus dans le build que lorsqu'ils sont utilisés.

Lorsqu'on les utilise dans les [fonctions de rendu](/guide/extras/render-function), il faut les importer explicitement. Par exemple :

```js
import { h, Transition } from 'vue'

h(Transition, {
  /* props */
})
```

:::

## `<Transition>` {#transition}

Fournit des effets de transition animés à **un seul** élément ou composant.

* **Props :**

  ```ts
  interface TransitionProps {
    /**
     * Utilisé pour générer automatiquement des noms de classe pour les transitions CSS
     * par exemple `name: 'fade'` s'étendra automatiquement à `.fade-enter`,
     * `.fade-enter-active`, etc.
     */
    name?: string
    /**
     * S'il faut appliquer les classes de transition CSS ou non
     * Par défaut: true
     */
    css?: boolean
    /**
     * Spécifie le type d'événements de transition à attendre pour
     * déterminer le moment de la fin de la transition.
     * Le comportement par défaut consiste à détecter automatiquement le type qui a
     * la plus longue durée.
     */
    type?: 'transition' | 'animation'
    /**
     * Spécifie les durées explicites de la transition.
     * Le comportement par défaut consiste à attendre le premier événement `transitionend`.
     * ou `animationend` sur l'élément de transition racine.
     */
    duration?: number | { enter: number; leave: number }
    /**
     * Contrôle la séquence temporelle des transitions de sortie/entrée.
     * Simultané par défaut.
     */
    mode?: 'in-out' | 'out-in' | 'default'
    /**
     * Si la transition doit être appliquée au rendu initial ou non.
     * Par défaut: false
     */
    appear?: boolean

    /**
     * Props pour la personnaliser les classes de transition.
     * Utilisez kebab-case dans les templates, par exemple enter-from-class="xxx"
     */
    enterFromClass?: string
    enterActiveClass?: string
    enterToClass?: string
    appearFromClass?: string
    appearActiveClass?: string
    appearToClass?: string
    leaveFromClass?: string
    leaveActiveClass?: string
    leaveToClass?: string
  }
  ```

* **Événements :**

  * `@before-enter`
  * `@before-leave`
  * `@enter`
  * `@leave`
  * `@appear`
  * `@after-enter`
  * `@after-leave`
  * `@after-appear`
  * `@enter-cancelled`
  * `@leave-cancelled` (`v-show` only)
  * `@appear-cancelled`

* **Exemple**

  Élément simple :

  ```vue-html
  <Transition>
    <div v-if="ok">toggled content</div>
  </Transition>
  ```

  Transition forcée en modifiant l'attribut `key` :

  ```vue-html
  <Transition>
    <div :key="text">{{ text }}</div>
  </Transition>
  ```

  Composant dynamique, avec mode de transition + animation à l'apparition :

  ```vue-html
  <Transition name="fade" mode="out-in" appear>
    <component :is="view"></component>
  </Transition>
  ```

  Écoute des événements de transition :

  ```vue-html
  <Transition @after-enter="onTransitionComplete">
    <div v-show="ok">toggled content</div>
  </Transition>
  ```

* **Voir aussi** [Guide sur `<Transition>`](/guide/built-ins/transition)

## `<TransitionGroup>` {#transitiongroup}

Fournit des effets de transition pour de **multiples** éléments ou composants dans une liste.

* **Props :**

  `<TransitionGroup>` accepte les mêmes props que `<Transition>` à l'exception de `mode`, plus deux props additionnelles :

  ```ts
  interface TransitionGroupProps extends Omit<TransitionProps, 'mode'> {
    /**
     * S'il n'est pas défini, le rendu sera un fragment.
     */
    tag?: string
    /**
     * Pour personnaliser la classe CSS appliquée lors des transitions de mouvement.
     * Utilisez kebab-case dans les templates, par exemple move-class="xxx"
     */
    moveClass?: string
  }
  ```

* **Événements :**

  `<TransitionGroup>` émet les mêmes événements que `<Transition>`.

* **Détails**

  Par défaut, `<TransitionGroup>` ne rend pas d'élément du DOM en enveloppant d'autres, mais on peut en définir un via la prop `tag`.

  Notez que chaque enfant d'un `<transition-group>` doit avoir une [**clé unique**](/guide/essentials/list#maintaining-state-with-key) pour que les animations fonctionnent correctement.

  `<TransitionGroup>` prend en charge les transitions de mouvement via une transformation CSS. Lorsque la position d'un enfant à l'écran a changé après une mise à jour, il se verra appliquer une classe CSS de mouvement (générée automatiquement à partir de l'attribut `name` ou configurée avec la prop `move-class`). Si la propriété CSS `transform` est "transition-able" lorsque la classe de mouvement est appliquée, l'élément sera animé en douceur vers sa destination en utilisant la [technique FLIP](https://aerotwist.com/blog/flip-your-animations/).

* **Exemple**

  ```vue-html
  <TransitionGroup tag="ul" name="slide">
    <li v-for="item in items" :key="item.id">
      {{ item.text }}
    </li>
  </TransitionGroup>
  ```

* **Voir aussi** [Guide - TransitionGroup](/guide/built-ins/transition-group)

## `<KeepAlive>` {#keepalive}

Met en cache les composants activés dynamiquement qui y sont imbriqués.

* **Props :**

  ```ts
  interface KeepAliveProps {
    /**
     * Si spécifié, seuls les composants dont les noms correspondent à
     * `include` seront mis en cache.
     */
    include?: MatchPattern
    /**
     * Un composant avec un nom ne correspondant pas à  `exclude` ne sera
     * pas mis en cache.
     */
    exclude?: MatchPattern
    /**
     * Le nombre maximum d'instances de composant à mettre en cache.
     */
    max?: number | string
  }

  type MatchPattern = string | RegExp | (string | RegExp)[]
  ```

* **Détails**

  Lorsqu'il enveloppe un composant dynamique, `<KeepAlive>` met en cache les instances inactives du composant sans les détruire.

  Il ne peut y avoir qu'une seule instance de composant active comme enfant direct de `<KeepAlive>` à un moment donné.

Lorsqu'un composant est activé/désactivé à l'intérieur de `<KeepAlive>`, ses hooks de cycle de vie `activated` et `deactivated` seront invoqués en conséquence, fournissant une alternative à `mounted` et `unmounted`, qui ne sont pas appelés. Ceci s'applique à l'enfant direct de `<KeepAlive>` ainsi qu'à tous ses descendants.

* **Exemple**

  Utilisation basique :

  ```vue-html
  <KeepAlive>
    <component :is="view"></component>
  </KeepAlive>
  ```

  Lorsqu'il est utilisé avec les branches `v-if` / `v-else`, il ne doit y avoir qu'un seul composant rendu à la fois :

  ```vue-html
  <KeepAlive>
    <comp-a v-if="a > 1"></comp-a>
    <comp-b v-else></comp-b>
  </KeepAlive>
  ```

  Utilisé en combinaison avec `<Transition>` :

  ```vue-html
  <Transition>
    <KeepAlive>
      <component :is="view"></component>
    </KeepAlive>
  </Transition>
  ```

  En utilisant `include` / `exclude` :

  ```vue-html
  <!-- chaîne de caractères délimitée par des virgules -->
  <KeepAlive include="a,b">
    <component :is="view"></component>
  </KeepAlive>

  <!-- regex (utilisez `v-bind`) -->
  <KeepAlive :include="/a|b/">
    <component :is="view"></component>
  </KeepAlive>

  <!-- Tableau (utilisez `v-bind`) -->
  <KeepAlive :include="['a', 'b']">
    <component :is="view"></component>
  </KeepAlive>
  ```

  Utilisation avec `max` :

  ```vue-html
  <KeepAlive :max="10">
    <component :is="view"></component>
  </KeepAlive>
  ```

* **Voir aussi** [Guide - KeepAlive](/guide/built-ins/keep-alive)

## `<Teleport>` {#teleport}

Rend le contenu de son slot à une autre partie du DOM.

* **Props :**

  ```ts
  interface TeleportProps {
    /**
     * Requis. Spécifie le conteneur cible.
     * Peut être un sélecteur ou un élément.
     */
    to: string | HTMLElement
    /**
     * S'il vaut `true`, le contenu restera à son emplacement
     * original au lieu d'être déplacé dans le conteneur cible.
     * Peut être changé de manière dynamique.
     */
    disabled?: boolean
    /**
     * Lorsque la valeur est `true`, le traitement de Teleport sera reporté jusqu'à ce que d'autres
     * parties de l'application aient été montées avant
     * de résoudre sa cible. (A partir de la version 3.5)
     */
    defer?: boolean
  }
  ```

* **Exemple**

  En spécifiant le conteneur cible :

  ```vue-html
  <Teleport to="#some-id" />
  <Teleport to=".some-class" />
  <Teleport to="[data-teleport]" />
  ```

  En le désactivant de manière conditionnelle :

  ```vue-html
  <Teleport to="#popup" :disabled="displayVideoInline">
    <video src="./my-movie.mp4">
  </Teleport>
  ```

  Différer la résolution du conteneur cible  :

  ```vue-html
  <Teleport defer to="#late-div">...</Teleport>

  <!-- plus loins dans le template -->
  <div id="late-div"></div>
  ```

* **Voir aussi** [Guide - Teleport](/guide/built-ins/teleport)

## `<Suspense>`  {#suspense}

Utilisé pour orchestrer des dépendances asynchrones imbriquées dans un arbre de composants.

* **Props :**

  ```ts
  interface SuspenseProps {
    timeout?: string | number
    suspensible?: boolean
  }
  ```

* **Événements :**

  * `@resolve`
  * `@pending`
  * `@fallback`

* **Détails**

  `<Suspense>` accepte deux slots : le slot `#default` et le slot `#fallback`. Il affichera le contenu du slot de secours tout en rendant le slot par défaut en mémoire.

  S'il rencontre des dépendances asynchrones ([Composants asynchrones](/guide/components/async) et des composants avec [`async setup()`](/guide/built-ins/suspense#async-setup)) lors du rendu du slot par défaut, il attendra qu'elles soient toutes résolues avant d'afficher le slot par défaut.

  En définissant Suspense comme `suspensible`, toutes les dépendances asynchrones seront gérées par le Suspense parent. Voir [les détails d'implémentation](https://github.com/vuejs/core/pull/6736)

* **Voir aussi** [Guide - Suspense](/guide/built-ins/suspense)

---

---
url: /api/composition-api-setup.md
---
# Composition API : setup() {#composition-api-setup}

## Utilisation basique {#basic-usage}

:::info Note
Cette page documente l'usage de `setup`. Si vous utilisez la Composition API avec les composants monofichiers, [`<script setup>`](/api/sfc-script-setup) est recommandé pour une syntaxe plus succincte et ergonomique.
:::

Dans les cas suivants, le hook `setup()` sert de point d'entrée pour la Composition API dans les composants :

1. Si vous souhaitez utiliser la Composition API sans outil de build;
2. Si vous intégrez du code avec la Composition API dans un composant utilisant l'Options API.

On peut déclarer un état réactif en utilisant [l'API de réactivité](./reactivity-core) et l'exposer dans le template en retournant l'objet depuis `setup()`. Les propriétés retournées par l'objet seront aussi disponibles dans l'instance du composant (si aucune autre option n'est utilisée) :

```vue
<script>
import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)

    // expose la variable count dans le template
    // et dans tous les autres hooks de l'Options API
    return {
      count
    }
  },

  mounted() {
    console.log(this.count) // 0
  }
}
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>
```

Les [refs](/api/reactivity-core#ref) renvoyées par `setup` sont [automatiquement distribuées](/guide/essentials/reactivity-fundamentals#deep-reactivity) lorsqu'elles sont invoquées dans le template, vous n'avez donc pas besoin d'utiliser `.value` lorsque vous souhaitez y accéder. Elles sont également déballées de la même façon lorsqu'elles sont invoquées sur `this`.

`setup()` n'a pas accès à l'instance du composant - `this` aura une valeur `undefined` à l'intérieur de `setup()`. Vous pouvez accéder aux valeurs exposées par la Composition API depuis l'Options, mais pas l'inverse.

`setup()` doit renvoyer un objet *synchrone*. Le seul cas où `async setup()` peut être utilisé est lorsque le composant est un descendant d'un composant [Suspense](../guide/built-ins/suspense).

## Accéder aux props {#accessing-props}

Le premier argument dans la fonction `setup` est l'argument `props`. Tout comme l'on s'y attendrait dans un composant standard, les `props` à l'intérieur d'une fonction `setup` sont réactives et seront mises à jour lorsque de nouvelles props seront transmises.

```js
export default {
  props: {
    title: String
  },
  setup(props) {
    console.log(props.title)
  }
}
```

Notez que si vous déstructurez l'objet `props`, les variables déstructurées perdront leur réactivité. Il est donc recommandé d'accéder aux props sous la forme de `props.xxx`.

Si vous avez vraiment besoin de déstructurer les props, ou si vous devez passer une prop dans une fonction externe tout en conservant la réactivité, vous pouvez le faire avec les utilitaires de l'API de Réactivité [toRefs()](./reactivity-utilities#torefs) et [toRef()](/api/reactivity-utilities#toref).

```js
import { toRefs, toRef } from 'vue'

export default {
  setup(props) {
    // transforme props en un objet de refs puis le déstructure
    const { title } = toRefs(props)
    // `title` est une ref rattachée à `props.title` 
    console.log(title.value)

    // Ou, transformer l'une des props en une ref
    const title = toRef(props, 'title')
  }
}
```

## Contexte de la fonction setup {#setup-context}

Le deuxième argument passé à la fonction `setup` est un objet **Setup Context**. Cet objet expose d'autres valeurs qui peuvent être utiles à l'intérieur de `setup` :

```js
export default {
  setup(props, context) {
    // Attributs (objet non réactif, équivalent à $attrs)
    console.log(context.attrs)

    // Slots (objet non réactif, équivalent à $slots)
    console.log(context.slots)

    // Émettre des événements (fonction, équivalent à $emit)
    console.log(context.emit)

    // Exposer des propriétés publiques (fonction)
    console.log(context.expose)
  }
}
```

L'objet contexte n'est pas réactif et peut être déstructuré en toute sécurité :

```js
export default {
  setup(props, { attrs, slots, emit, expose }) {
    ...
  }
}
```

`attrs` et `slots` sont des objets d'état qui sont toujours mis à jour lorsque le composant lui-même est mis à jour. Cela signifie que vous devriez éviter de les déstructurer et toujours faire référence aux propriétés via `attrs.x` ou `slots.x`. Notez également que, contrairement aux `props`, les propriétés d'`attrs` et de `slots` **ne sont pas réactives**. Si vous avez l'intention d'appliquer des effets de bord en fonction des changements apportés à `attrs` ou `slots`, vous devriez le faire à l'intérieur du hook de cycle de vie `onBeforeUpdate`.

### Exposer des propriétés publiques {#exposing-public-properties}

`expose` est une fonction qui peut être utilisée pour limiter explicitement les propriétés exposées lorsque l'instance de composant est accédée par un composant parent via [les refs du template](/guide/essentials/template-refs#ref-on-component) :

```js{5,10}
export default {
  setup(props, { expose }) {
    // rend l'instance inaccessible
    // c.-à-d. n'exposera rien au parent
    expose()

    const publicCount = ref(0)
    const privateCount = ref(0)
    // n'expose qu'une sélection de l'état local
    expose({ count: publicCount })
  }
}
```

## Utilisation avec les fonctions de rendu {#usage-with-render-functions}

`setup` peut également retourner [une fonction de rendu](/guide/extras/render-function) qui peut directement utiliser l'état réactif déclaré dans le scope partagé :

```js{6}
import { h, ref } from 'vue'

export default {
  setup() {
    const count = ref(0)
    return () => h('div', count.value)
  }
}
```

Retourner une fonction de rendu nous empêche de retourner autre chose. En pratique, cela ne devrait pas poser de problème mais cela peut être problématique si nous voulons exposer des méthodes de ce composant enfant au composant parent via les refs du template.

Nous pouvons résoudre ce problème en appellant [`expose()`](#exposing-public-properties) :

```js{8-10}
import { h, ref } from 'vue'

export default {
  setup(props, { expose }) {
    const count = ref(0)
    const increment = () => ++count.value

    expose({
      increment
    })

    return () => h('div', count.value)
  }
}
```

La méthode `increment` sera dès lors disponible dans le composant parent via une référence.

---

---
url: /api/composition-api-helpers.md
---
# Composition API: Helpers {#composition-api-helpers}

## useAttrs() {#useattrs}

Retourne l'objet `attrs` du [contexte de la fonction setup](/api/composition-api-setup#setup-context), qui inclut les [attributs implicitement déclarés (Fallthrough Attributes)](/guide/components/attrs#fallthrough-attributes) du composant courant. Il est destiné à être utilisé dans `<script setup>` lorsque l'objet setup context n'est pas disponible.

* **Type**

  ```ts
  function useAttrs(): Record<string, unknown>
  ```

## useSlots() {#useslots}

Retourne l'objet `slots` du [contexte de la fonction setup](/api/composition-api-setup#setup-context), qui inclut les slots passés par les parents comme des fonctions appelables qui retournent des noeuds virtuels du DOM. Il est destiné à être utilisé dans `<script setup>` lorsque l'objet setup context n'est pas disponible.

Si vous utilisez TypeScript, [`defineSlots()`](/api/sfc-script-setup#defineslots) devrait être préféré.

* **Type**

  ```ts
  function useSlots(): Record<string, (...args: any[]) => VNode[]>
  ```

## useModel() {#usemodel}

C'est le helper sous-jacent qui alimente [`defineModel()`](/api/sfc-script-setup#definemodel). Si vous utilisez `<script setup>`, `defineModel()` devrait être préféré.

* Disponible à partir de la version 3.4

* **Type**

  ```ts
  function useModel(
    props: Record<string, any>,
    key: string,
    options?: DefineModelOptions
  ): ModelRef

  type DefineModelOptions<T = any> = {
    get?: (v: T) => any
    set?: (v: T) => any
  }

  type ModelRef<T, M extends PropertyKey = string, G = T, S = T> = Ref<G, S> & [
    ModelRef<T, M, G, S>,
    Record<M, true | undefined>
  ]
  ```

* **Exemple**

  ```js
  export default {
    props: ['count'],
    emits: ['update:count'],
    setup(props) {
      const msg = useModel(props, 'count')
      msg.value = 1
    }
  }
  ```

* **Détails**

  `useModel()` peut être utilisé dans les composants non-SFC, par exemple lors de l'utilisation de la fonction raw `setup()`. Elle attend l'objet `props` comme premier argument, et le nom du modèle comme second argument. Le troisième argument optionnel peut être utilisé pour déclarer des getter et setter personnalisés pour le modèle ref résultant. Notez que contrairement à `defineModel()`, vous êtes responsable de la déclaration des objets props et emits vous-même.

## useTemplateRef()  {#usetemplateref}

Renvoie une ref peu profonde dont la valeur sera synchronisée avec l'élément ou le composant du template ayant un attribut ref correspondant.

* **Type**

  ```ts
  function useTemplateRef<T>(key: string): Readonly<ShallowRef<T | null>>
  ```

* **Exemple**

  ```vue
  <script setup>
  import { useTemplateRef, onMounted } from 'vue'

  const inputRef = useTemplateRef('input')

  onMounted(() => {
    inputRef.value.focus()
  })
  </script>

  <template>
    <input ref="input" />
  </template>
  ```

* **Voir aussi**
  * [Guide - Les refs du template](/guide/essentials/template-refs)
  * [Guide - Typer les refs de template](/guide/typescript/composition-api#typing-template-refs)&#x20;
  * [Guide - Typer les refs de template d'un composant](/guide/typescript/composition-api#typing-component-template-refs)&#x20;

## useId()  {#useid}

Utilisé pour générer des identifiants uniques par application pour les attributs d'accessibilité ou les éléments de formulaire.

* **Type**

  ```ts
  function useId(): string
  ```

* **Exemple**

  ```vue
  <script setup>
  import { useId } from 'vue'

  const id = useId()
  </script>

  <template>
    <form>
      <label :for="id">Name:</label>
      <input :id="id" type="text" />
    </form>
  </template>
  ```

* **Détails**

  Les identifiants générés par `useId()` sont uniques pour chaque application. Il peut être utilisé pour générer des identifiants pour les éléments de formulaire et les attributs d'accessibilité. Plusieurs appels dans le même composant génèreront des ID différents ; plusieurs instances du même composant appelant `useId()` auront également des ID différents.

  Les identifiants générés par `useId()` sont également garantis stables entre les rendus du serveur et du client, de sorte qu'ils peuvent être utilisés dans des applications SSR sans entraîner de disparités d'hydratation.

  Si vous avez plus d'une instance d'application Vue sur la même page, vous pouvez éviter les conflits d'ID en donnant à chaque application un préfixe d'ID via [`app.config.idPrefix`](/api/application#app-config-idprefix).

  :::warning Caution
  `useId()` ne doit pas être appelé à l'intérieur d'une propriété `computed()` car elle peut causer des conflits d'instance. A la place, il faut déclarer l'ID en dehors de `computed()` et le référencer dans la fonction calculée.
  :::

---

---
url: /api/composition-api-dependency-injection.md
---
# Composition API: Injection de dépendances {#composition-api-dependency-injection}

## provide() {#provide}

Fournit une valeur qui peut être injectée par les composants descendants.

* **Type :**

  ```ts
  function provide<T>(key: InjectionKey<T> | string, value: T): void
  ```

* **Détails**

  `provide()` prend deux arguments : la clé, qui peut être une chaîne de caractères ou un symbole, et la valeur à injecter.

  En utilisant TypeScript, la clé peut être un symbole casté en tant que `InjectionKey` - un type utilitaire fourni par Vue qui étend `Symbol`, qui peut être utilisé pour synchroniser le type de valeur entre `provide()` et `inject()`.

  Comme pour les API d'enregistrement des hooks de cycle de vie, `provide()` doit être appelée de manière synchrone pendant la phase `setup()` d'un composant.

* **Exemple**

  ```vue
  <script setup>
  import { ref, provide } from 'vue'
  import { countSymbol } from './injectionSymbols'

  // fournit une valeur statique
  provide('path', '/project/')

  // fournit une valeur réactive
  const count = ref(0)
  provide('count', count)

  // fournit des clés de symboles
  provide(countSymbol, count)
  </script>
  ```

* **Voir aussi**
  * [Guide - Provide / Inject](/guide/components/provide-inject)
  * [Guide - Typer Provide / Inject](/guide/typescript/composition-api#typing-provide-inject)&#x20;

## inject() {#inject}

Injecte une valeur fournie par un composant ancêtre ou par l'application (via `app.provide()`).

* **Type :**

  ```ts
  // sans valeur par défaut
  function inject<T>(key: InjectionKey<T> | string): T | undefined

  // avec valeur par défaut
  function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T

  // en utilisant une fonction factory
  function inject<T>(
    key: InjectionKey<T> | string,
    defaultValue: () => T,
    treatDefaultAsFactory: true
  ): T
  ```

* **Détails**

  Le premier argument est la clé d'injection. Vue remontera la chaîne des parents pour localiser une valeur fournie avec une clé correspondante. Si plusieurs composants de la chaîne des parents fournissent la même clé, celui qui est le plus proche du composant qui injecte la valeur l'emportera sur ceux qui sont plus haut dans la chaîne. Si aucune valeur avec la clé correspondante n'a été trouvée, `inject()` renvoie `undefined` sauf si une valeur par défaut est fournie.

  Le second argument est optionnel et représente la valeur par défaut à utiliser si aucune valeur correspondante n'a été trouvée.

  Il peut aussi être une fonction *factory* pour retourner des valeurs qui sont coûteuses à créer. Dans ce cas, la valeur `true` doit être passée comme troisième argument pour indiquer que la fonction doit être utilisée comme une *factory* au lieu de la valeur elle-même.

  Comme pour les API d'enregistrement des hooks de cycle de vie, `inject()` doit être appelée de manière synchrone pendant la phase `setup()` d'un composant.

  En utilisant TypeScript, la clé peut être de type `InjectionKey` - un type utilitaire fourni par Vue qui étend `Symbol`, qui peut être utilisé pour synchroniser le type de valeur entre `provide()` et `inject()`.

* **Exemple**

  En supposant qu'un composant parent a fourni des valeurs comme indiqué dans l'exemple précédent concernant `provide()` :

  ```vue
  <script setup>
  import { inject } from 'vue'
  import { countSymbol } from './injectionSymbols'

  // injecte une valeur statique par défaut
  const path = inject('path')

  // injecte une valeur réactive
  const count = inject('count')

  // injection avec des clés de symboles
  const count2 = inject(countSymbol)

  // injection avec une valeur par défaut
  const bar = inject('path', '/default-path')

  // injection avec une valeur par défaut via une fonction factory
  const baz = inject('foo', () => new Map())

  // injection avec la valeur par défaut de la fonction, en passant le 3ème argument
  const fn = inject('function', () => {}, false)
  </script>
  ```

* **Voir aussi**
  * [Guide - Provide / Inject](/guide/components/provide-inject)
  * [Guide - Typer Provide / Inject](/guide/typescript/composition-api#typing-provide-inject)&#x20;

## hasInjectionContext() {#has-injection-context}

* Supporté à partir de la version 3.3

Retourne vraie si [inject()](#inject) peut être utilisé sans avertissement sur le fait d'être appelée au mauvais endroit (par exemple en dehors de `setup()`). Cette méthode est conçue pour être utilisée par les bibliothèques qui veulent utiliser `inject()` en interne sans déclencher d'avertissement pour l'utilisateur final.

* **Type**

  ```ts
  function hasInjectionContext(): boolean
  ```

---

---
url: /api/composition-api-lifecycle.md
---
# Composition API: Les hooks du cycle de vie {#composition-api-lifecycle-hooks}

:::info Note d'utilisation
Toutes les API listées sur cette page doivent être appelées de manière synchrone pendant la phase `setup()` d'un composant. Consultez [Guide - Les hooks du cycle de vie](/guide/essentials/lifecycle) pour plus de détails.
:::

## onMounted() {#onmounted}

Enregistre une fonction de rappel qui sera appelée après le montage du composant.

* **Type :**

  ```ts
  function onMounted(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Détails**

  Un composant est considéré comme monté après que :

  * Tous ses composants enfants synchrones ont été montés (n'inclut pas les composants asynchrones ou les composants à l'intérieur des arbres `<Suspense>`).

  * Son propre arbre du DOM a été créé et inséré dans le conteneur parent. Notez que cela garantit que seulement l'arbre du DOM du composant est déjà placé dans le document, même si le conteneur racine de l'application y est.

  Ce hook est généralement utilisé pour effectuer des effets de bord qui nécessitent un accès au DOM rendu du composant, ou pour limiter le code lié au DOM au client dans une [application rendue par le serveur](/guide/scaling-up/ssr).

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

* **Exemple**

  Accès à un élément via une ref de template :

  ```vue
  <script setup>
  import { ref, onMounted } from 'vue'

  const el = ref()

  onMounted(() => {
    el.value // <div>
  })
  </script>

  <template>
    <div ref="el"></div>
  </template>
  ```

## onUpdated() {#onupdated}

Enregistre une fonction de rappel à appeler après que le composant ait mis à jour son arbre du DOM en raison d'un changement d'état réactif.

* **Type :**

  ```ts
  function onUpdated(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Détails**

  Le hook de mise à jour d'un composant parent est appelé après celui de ses composants enfants.

  Ce hook est appelé après toute mise à jour du DOM du composant, qui peut être causée par différents changements d'état. Si vous devez accéder au DOM mis à jour après un changement d'état spécifique, utilisez plutôt [nextTick()](/api/general#nexttick).

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

  :::warning
  Ne modifiez pas l'état du composant dans le hook *updated* - cela conduirait à une boucle de mises à jour infinie !
  :::

* **Exemple**

  Accès au DOM mis à jour :

  ```vue
  <script setup>
  import { ref, onUpdated } from 'vue'

  const count = ref(0)

  onUpdated(() => {
    // le contenu du texte devrait être égal à `count.value`
    console.log(document.getElementById('count').textContent)
  })
  </script>

  <template>
    <button id="count" @click="count++">{{ count }}</button>
  </template>
  ```

## onUnmounted() {#onunmounted}

Enregistre une fonction de rappel qui sera appelée après le démontage du composant.

* **Type :**

  ```ts
  function onUnmounted(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Détails**

  Un composant est considéré comme démonté après que :

  * Tous ses composants enfants ont été démontés.

  * Tous ses effets réactifs associés (effet de rendu et propriétés calculées / observateurs créés pendant `setup()`) ont été arrêtés.

  Utilisez ce hook pour nettoyer manuellement les effets de bord créés, tels que les minuteurs, les écouteurs d'événements du DOM ou les connexions au serveur.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

* **Exemple**

  ```vue
  <script setup>
  import { onMounted, onUnmounted } from 'vue'

  let intervalId
  onMounted(() => {
    intervalId = setInterval(() => {
      // ...
    })
  })

  onUnmounted(() => clearInterval(intervalId))
  </script>
  ```

## onBeforeMount() {#onbeforemount}

Enregistre un hook qui sera appelé juste avant le montage du composant.

* **Type :**

  ```ts
  function onBeforeMount(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Détails**

  Lorsque ce hook est appelé, le composant a fini de configurer son état réactif, mais aucun noeud du DOM n'a encore été créé. Il est sur le point d'exécuter son effet de rendu du DOM pour la première fois.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## onBeforeUpdate() {#onbeforeupdate}

Enregistre un hook qui sera appelé juste avant que le composant ne soit sur le point de mettre à jour son arbre du DOM en raison d'un changement d'état réactif.

* **Type :**

  ```ts
  function onBeforeUpdate(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Détails**

  Ce hook peut être utilisé pour accéder à l'état du DOM avant que Vue ne le mette à jour. Il est également possible de modifier l'état d'un composant à l'intérieur de ce hook.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## onBeforeUnmount() {#onbeforeunmount}

Enregistre un hook à appeler juste avant le démontage d'une instance de composant.

* **Type :**

  ```ts
  function onBeforeUnmount(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Détails**

  Lorsque ce hook est appelé, l'instance du composant est toujours totalement fonctionnelle.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## onErrorCaptured() {#onerrorcaptured}

Enregistre un hook qui sera appelé lorsqu'une erreur venant d'un composant descendant a été interceptée.

* **Type :**

  ```ts
  function onErrorCaptured(callback: ErrorCapturedHook): void

  type ErrorCapturedHook = (
    err: unknown,
    instance: ComponentPublicInstance | null,
    info: string
  ) => boolean | void
  ```

* **Détails**

  Les erreurs peuvent être capturées à partir des sources suivantes :

  * Rendu de composants
  * Gestionnaires d'événements
  * Hooks de cycle de vie
  * Fonction `setup()`
  * Observateurs
  * Hooks de directives personnalisées
  * Hooks de transition

  Ce hook reçoit trois arguments : l'erreur, l'instance du composant qui a déclenché l'erreur, et une information sous forme de chaînes de caractères spécifiant le type de source de l'erreur.

  :::tip
  En production, le troisième argument (`info`) sera un code raccourci plutôt que toute la chaîne d'information. Vous pouvez trouver le code correspondant dans la [Référence des erreurs en production](/error-reference/#runtime-errors).
  :::

  Vous pouvez modifier l'état du composant dans `onErrorCaptured()` pour afficher un état d'erreur à l'utilisateur. Cependant, il est important de ne pas rendre le contenu original à l'origine de l'erreur, sinon le composant sera bloqué dans une boucle de rendu infinie.

  Le hook peut retourner `false` pour empêcher la propagation de l'erreur. Consultez les détails sur la propagation des erreurs ci-dessous.

  **Règles concernant la propagation des erreurs**

  * Par défaut, toutes les erreurs sont envoyées à [`app.config.errorHandler`](/api/application#app-config-errorhandler) au niveau de l'application si elle est définie, afin qu'elles puissent être signalées et analysées par un seul service à un seul endroit.

  * Si plusieurs hooks `errorCaptured` existent sur la chaîne descendante ou la chaîne ascendante d'un composant, ils seront tous invoqués sur la même erreur, suivant un ordre allant de bas en haut. Cela est comparable au mécanisme de *bubbling* des événements natifs du DOM.

  * Si le hook `errorCaptured` lui-même lance une erreur, cette erreur et l'erreur capturée originellement sont envoyées à `app.config.errorHandler`.

  * Un hook `errorCaptured` peut retourner `false` pour empêcher l'erreur de se propager plus loin. Cela revient à dire "cette erreur a été traitée et doit être ignorée". Cela empêchera tout autre hook `errorCaptured` ou `app.config.errorHandler` d'être invoqué pour cette erreur.

## onRenderTracked()  {#onrendertracked}

Enregistre un hook de débogage qui sera appelé lorsqu'une dépendance réactive a été tracée par l'effet de rendu du composant.

**Ce hook est réservé au mode développement et n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  function onRenderTracked(callback: DebuggerHook): void

  type DebuggerHook = (e: DebuggerEvent) => void

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TrackOpTypes /* 'get' | 'has' | 'iterate' */
    key: any
  }
  ```

* **Voir aussi** [La réactivité en détails](/guide/extras/reactivity-in-depth)

## onRenderTriggered()  {#onrendertriggered}

Enregistre un hook de débogage qui sera appelé lorsqu'une dépendance réactive déclenche la ré-exécution de l'effet de rendu du composant.

**Ce hook est réservé au mode développement et n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  function onRenderTriggered(callback: DebuggerHook): void

  type DebuggerHook = (e: DebuggerEvent) => void

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TriggerOpTypes /* 'set' | 'add' | 'delete' | 'clear' */
    key: any
    newValue?: any
    oldValue?: any
    oldTarget?: Map<any, any> | Set<any>
  }
  ```

* **Voir aussi** [La réactivité en détails](/guide/extras/reactivity-in-depth)

## onActivated() {#onactivated}

Enregistre une fonction de rappel qui sera appelée après que l'instance du composant ait été insérée dans le DOM en tant que partie d'un arbre mis en cache par [`<KeepAlive>`](/api/built-in-components#keepalive).

**Ce hook n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  function onActivated(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Voir aussi** [Guide - Cycle de vie d'une instance mise en cache](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## onDeactivated() {#ondeactivated}

Enregistre une fonction de rappel à appeler après que l'instance du composant ait été retirée du DOM en tant que partie d'un arbre mis en cache par [`<KeepAlive>`](/api/built-in-components#keepalive).

**Ce hook n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  function onDeactivated(
    callback: () => void,
    target?: ComponentInternalInstance | null
  ): void
  ```

* **Voir aussi** [Guide - Cycle de vie d'une instance mise en cache](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## onServerPrefetch()  {#onserverprefetch}

Enregistre une fonction asynchrone à résoudre avant que l'instance du composant ne soit rendue sur le serveur.

* **Type :**

  ```ts
  function onServerPrefetch(callback: () => Promise<any>): void
  ```

* **Détails**

  Si la fonction de rappel renvoie une promesse, le moteur de rendu du serveur attendra qu'elle soit résolue avant de rendre le composant.

  Ce hook n'est appelé que pendant le rendu côté serveur et peut être utilisé pour effectuer une récupération de données sur le serveur uniquement.

* **Exemple**

  ```vue
  <script setup>
  import { ref, onServerPrefetch, onMounted } from 'vue'

  const data = ref(null)

  onServerPrefetch(async () => {
    // le composant est rendu dans le cadre de la requête initiale
    // les données sont pré-récupérées sur le serveur car cela est plus rapide que via le client.
    data.value = await fetchOnServer(/* ... */)
  })

  onMounted(async () => {
    if (!data.value) {
      // si les données ne sont pas définies au moment du montage, cela signifie que le composant
      // est rendu dynamiquement sur le client.
      // Effectue la récupération côté client.
      data.value = await fetchOnClient(/* ... */)
    }
  })
  </script>
  ```

* **Voir aussi** [Rendu côté serveur](/guide/scaling-up/ssr)

---

---
url: /guide/essentials/application.md
---
# Créer une application Vue {#creating-a-vue-application}

## L'instance de l'application {#the-application-instance}

Chaque application Vue commence par créer une nouvelle **instance d'application** avec la fonction [`createApp`](/api/application#createapp) :

```js
import { createApp } from 'vue'

const app = createApp({
  /* options du composant racine */
})
```

## Le composant racine {#the-root-component}

L'objet que nous passons dans `createApp` est en fait un composant. Chaque application nécessite un "composant racine" qui peut contenir d'autres composants en tant qu'enfants.

Si vous utilisez des composants monofichiers, nous importons généralement le composant racine à partir d'un autre fichier :

```js
import { createApp } from 'vue'
// import du composant racine App à partir d'un composant monofichier.
import App from './App.vue'

const app = createApp(App)
```

Bien que de nombreux exemples de ce guide ne nécessitent qu'un seul composant, la plupart des applications réelles sont organisées en une arborescence de composants imbriqués et réutilisables. Par exemple, l'arborescence des composants d'une application Todo pourrait ressembler à ceci :

```
App (composant racine)
├─ TodoList
│  └─ TodoItem
│     ├─ TodoDeleteButton
│     └─ TodoEditButton
└─ TodoFooter
   ├─ TodoClearButton
   └─ TodoStatistics
```

Nous discuterons de la façon de définir et de composer plusieurs composants ensemble dans les sections ultérieures du guide. Avant cela, nous allons nous concentrer sur ce qui se passe à l'intérieur d'un seul composant.

## Montage de l'application {#mounting-the-app}

Une instance d'application n'affichera rien tant que sa méthode `.mount()` ne sera pas appelée. Elle attend un argument "conteneur", qui peut être soit un élément du DOM réel, soit une chaîne de sélection :

```html
<div id="app"></div>
```

```js
app.mount('#app')
```

Le contenu du composant racine de l'application sera rendu à l'intérieur de l'élément conteneur. Ce dernier n'est pas considéré comme faisant partie de l'application.

La méthode `.mount()` doit toujours être appelée après les différentes configurations (de l'application et des ressources). Notez également que sa valeur de retour, contrairement aux méthodes d'enregistrement des ressources, est l'instance du composant racine au lieu de l'instance de l'application.

### Template de composant racine depuis le DOM {#in-dom-root-component-template}

Le template du composant racine fait généralement partie du composant lui-même, mais il est également possible de fournir le template séparément en l'écrivant directement dans le conteneur monté :

```html
<div id="app">
  <button @click="count++">{{ count }}</button>
</div>
```

```js
import { createApp } from 'vue'

const app = createApp({
  data() {
    return {
      count: 0
    }
  }
})

app.mount('#app')
```

Vue utilisera automatiquement le contenu HTML du conteneur comme template si le composant racine n'a pas déjà une option `template`.

Les templates dans le DOM sont souvent utilisés dans les applications qui [utilisent Vue sans outils de build](/guide/quick-start.html#using-vue-from-cdn). Ils peuvent également être utilisés conjointement avec des frameworks côté serveur, où le template racine peut être généré dynamiquement par le serveur.

## Configurations d'application {#app-configurations}

L'instance d'application expose un objet `.config` qui nous permet de configurer quelques options au niveau de l'application, par exemple en définissant un gestionnaire d'erreurs au niveau de l'application qui capture les erreurs de tous les composants descendants :

```js
app.config.errorHandler = (err) => {
  /* gérer l'erreur */
}
```

L'instance d'application fournit également quelques méthodes pour enregistrer les ressources propres à l'application. Par exemple, enregistrer un composant :

```js
app.component('TodoDeleteButton', TodoDeleteButton)
```

Cela rend `TodoDeleteButton` disponible pour une utilisation n'importe où dans notre application. Nous discuterons de l'enregistrement des composants et d'autres types de ressources dans les sections ultérieures du guide. Vous pouvez également parcourir la liste complète des API concernant l'instance d'application dans sa [référence API](/api/application).

Assurez-vous d'appliquer toutes les configurations d'application avant de monter l'application !

## Instances multiples d'une application {#multiple-application-instances}

Rien ne vous limite à n'avoir qu'une seule instance d'application sur la même page. L'API `createApp` permet à plusieurs applications Vue de coexister sur la même page, chacune avec son propre scope pour la configuration et les ressources globales :

```js
const app1 = createApp({
  /* ... */
})
app1.mount('#container-1')

const app2 = createApp({
  /* ... */
})
app2.mount('#container-2')
```

Si vous utilisez Vue pour améliorer l'HTML rendu par le serveur et que vous n'avez besoin de Vue que pour contrôler des parties spécifiques d'une grande page, évitez de monter une seule instance d'application Vue sur la page entière. Au lieu de cela, créez plusieurs petites instances d'application et montez-les sur les éléments dont elles sont responsables.

---

---
url: /guide/quick-start.md
---

# Démarrage rapide {#quick-start}

## En ligne {#try-vue-online}

* Pour vous familiariser rapidement avec Vue, vous pouvez l'essayer directement dans notre [Playground](https://play.vuejs.org/#eNo9jcEKwjAMhl/lt5fpQYfXUQfefAMvvRQbddC1pUuHUPrudg4HIcmXjyRZXEM4zYlEJ+T0iEPgXjn6BB8Zhp46WUZWDjCa9f6w9kAkTtH9CRinV4fmRtZ63H20Ztesqiylphqy3R5UYBqD1UyVAPk+9zkvV1CKbCv9poMLiTEfR2/IXpSoXomqZLtti/IFwVtA9A==).

* Si vous préférez une configuration HTML simple sans outil de build, vous pouvez utiliser [JSFiddle](https://jsfiddle.net/yyx990803/2ke1ab0z/) comme point de départ.

* Si vous êtes déjà familiarisé avec Node.js et le concept des outils de construction, vous pouvez également essayer une configuration de build complète directement dans votre navigateur sur [StackBlitz](https://vite.new/vue).

* Pour découvrir la configuration recommandée, regardez ce tutoriel interactif [Scrimba](http://scrimba.com/links/vue-quickstart) qui vous montre comment exécuter, modifier et déployer votre première application Vue.

## Créer une application Vue {#creating-a-vue-application}

:::tip Pré-requis

* Être familier avec l'invite de commandes
* Avoir installé [Node.js](https://nodejs.org/) version `^20.19.0 || >=22.12.0`
  :::

Dans cette section, nous allons vous présenter comment créer une [Single Page Application avec Vue](/guide/extras/ways-of-using-vue#single-page-application-spa) sur votre machine locale. Le projet créé utilisera une configuration de build basée sur [Vite](https://vite.dev) et nous permettra d'utiliser les [composants monofichiers](/guide/scaling-up/sfc) (SFCs).

Assurez-vous d'avoir une version à jour de [Node.js](https://nodejs.org/) d'installée et que votre répertoire de travail courant est bien celui où vous souhaitez créer un projet. Exécutez la commande suivante dans votre invite de commandes (sans le symbole `$`) :

::: code-group

```sh [npm]
$ npm create vue@latest
```

```sh [pnpm]
$ pnpm create vue@latest
```

```sh [yarn]
# Avec Yarn (v1+)
$ yarn create vue

# Avec Yarn Moderne (v2+)
$ yarn create vue@latest

# Avec Yarn ^v4.11
$ yarn dlx create-vue@latest
```

```sh [bun]
$ bun create vue@latest
```

:::

Cette commande installera et exécutera [create-vue](https://github.com/vuejs/create-vue), l'outil officiel de création de projets Vue. Des questions (en anglais) vous seront posées pour un certain nombre de fonctionnalités optionnelles telles que la prise en charge de TypeScript et des tests :

Si vous n'êtes pas sûr d'une option, choisissez simplement `No` en appuyant sur entrée pour le moment. Une fois le projet créé, suivez les instructions pour installer les dépendances et démarrer le serveur de développement :

::: code-group

```sh-vue [npm]
$ cd {{'<votre-nouveau-projet>'}}
$ npm install
$ npm run dev
```

```sh-vue [pnpm]
$ cd {{'<votre-nouveau-projet>'}}
$ pnpm install
$ pnpm run dev
```

```sh-vue [yarn]
$ cd {{'<votre-nouveau-projet>'}}
$ yarn
$ yarn dev
```

```sh-vue [bun]
$ cd {{'<votre-nouveau-projet>'}}
$ bun install
$ bun run dev
```

:::

Vous devriez maintenant avoir votre premier projet Vue en cours d'exécution ! Notez que les composants d'exemple dans le projet généré sont écrits avec la [Composition API](/guide/introduction#composition-api) et `<script setup>`, plutôt que l'[Options API](/guide/introduction#options-api). Voici quelques conseils supplémentaires :

* L'environnement de développement recommandé est [Visual Studio Code](https://code.visualstudio.com/) + [l'extension Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar). Si vous utilisez d'autres éditeurs, lisez la [section sur le support des environnements de développement](/guide/scaling-up/tooling#ide-support).
* [Guide - Outils](/guide/scaling-up/tooling) fournit plus de détails sur les utilitaires, notamment sur l'intégration avec les frameworks back-end.
* Pour en savoir plus sur l'outil de compilation Vite, consultez la [documentation Vite](https://vite.dev).
* Si vous avez choisi d'utiliser TypeScript, consultez le [Guide d'utilisation de TypeScript](typescript/overview).

Dès que vous êtes prêts à livrer votre application en production, exécutez la commande suivante :

::: code-group

```sh [npm]
$ npm run build
```

```sh [pnpm]
$ pnpm run build
```

```sh [yarn]
$ yarn build
```

```sh [bun]
$ bun run build
```

:::

Cela créera une version de votre application prête pour la production dans le répertoire `./dist` du projet. Consultez le [Guide du déploiement en production](/guide/best-practices/production-deployment) pour en savoir plus sur l'envoi de votre application en production.

[Étapes suivantes >](#next-steps)

## Utiliser Vue depuis un CDN {#using-vue-from-cdn}

Vous pouvez utiliser Vue directement depuis un CDN via une balise script :

```html
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
```

Ici nous utilisons [unpkg](https://unpkg.com/), mais vous pouvez utiliser tout autre CDN qui sert des paquets NPM, par exemple [jsdelivr](https://www.jsdelivr.com/package/npm/vue) ou [cdnjs](https://cdnjs.com/libraries/vue). Bien évidemment, vous pouvez également télécharger le fichier pour le servir par vous-même.

Lorsque Vue est utilisé depuis un CDN, aucun outil de build n'est nécessaire. Cela permet d'avoir une configuration plus simple, et plus adaptée pour enrichir du HTML statique ou intégrer un framework backend. Par contre, vous n'aurez pas la possibilité de bénéficier de la syntaxe des components monofichiers (SFC).

### Utiliser le build global {#using-the-global-build}

Le lien ci-dessus charge le *build global* de Vue, où toutes les API haut-niveau sont exposées comme des propriétés sur l'objet global `Vue`. Ci-dessous, un exemple utilisant le build global :

```html
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>

<div id="app">{{ message }}</div>

<script>
  const { createApp } = Vue

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>
```

[CodePen Demo >](https://codepen.io/vuejs-examples/pen/QWJwJLp)

```html
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>

<div id="app">{{ message }}</div>

<script>
  const { createApp, ref } = Vue

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>
```

[CodePen Demo >](https://codepen.io/vuejs-examples/pen/eYQpQEG)

:::tip
De nombreux exemples de la Composition API tout au long du guide utiliseront la syntaxe `<script setup>`, qui nécessite des outils de génération. Si vous avez l'intention d'utiliser la Composition API sans outil de build, consultez l'utilisation de l'option [`setup()`](/api/composition-api-setup).
:::

### Utiliser le build des modules ES {#using-the-es-module-build}

Bien que le build global fonctionne, nous utiliserons principalement la syntaxe des [modules ES](https://developer.mozilla.org/fr/docs/Web/JavaScript/Guide/Modules) dans le reste de la documentation par souci de cohérence. La plupart des navigateurs supportant désormais les modules ES nativement, nous pouvons utiliser Vue depuis un CDN via les modules ES natifs :

```html{3,4}
<div id="app">{{ message }}</div>

<script type="module">
  import { createApp } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>
```

```html{3,4}
<div id="app">{{ message }}</div>

<script type="module">
  import { createApp, ref } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>
```

Notez que nous utilisons `<script type="module">`, et que l'url CDN importée pointe vers le **build des modules ES** de Vue.

[CodePen Demo >](https://codepen.io/vuejs-examples/pen/VwVYVZO)

[CodePen Demo >](https://codepen.io/vuejs-examples/pen/MWzazEv)

### Activer l'Import maps {#enabling-import-maps}

Dans l'exemple ci-dessus, nous importons depuis l'URL CDN complète, mais dans le reste de la documentation, vous verrez un code comme celui-ci :

```js
const { createApp, ref } = Vue
```

Nous pouvons dire au navigateur où trouver l'import `vue` par l'usage de l'[Import Maps](https://caniuse.com/import-maps) :

```html{1-7,12}
<script type="importmap">
  {
    "imports": {
      "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
    }
  }
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp } from 'vue'

  createApp({
    data() {
      return {
        message: 'Hello Vue!'
      }
    }
  }).mount('#app')
</script>
```

[CodePen Demo >](https://codepen.io/vuejs-examples/pen/wvQKQyM)

```html{1-7,12}
<script type="importmap">
  {
    "imports": {
      "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
    }
  }
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp, ref } from 'vue'

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>
```

[CodePen Demo >](https://codepen.io/vuejs-examples/pen/YzRyRYM)

Vous pouvez ajouter des entrées pour d'autres dépendances à l'Import Map, assurez-vous simplement qu'elles pointent vers la version des modules ES de la bibliothèque que vous avez l'intention d'utiliser.

:::tip Support navigateur de l'Import Maps
Pour le moment, les Import Maps ne sont disponibles que dans les navigateurs basés sur Chromium, nous vous recommandons donc d'utiliser Chrome ou Edge pendant le processus d'apprentissage.

Si vous utilisez Firefox, c'est supporté par défaut à partir de la version 108+ sinon vous devez l'activer via la config `dom.importMaps.enabled` dans `about:config` pour les versions 102 et supérieures.

Si votre navigateur préféré ne prend pas encore en charge les Import Maps, vous pouvez ajouter le support (polyfill) avec [es-module-shims](https://github.com/guybedford/es-module-shims).

:::warning À éviter en production
L'usage des Import Maps est destiné à l'apprentissage uniquement. Si vous avez l'intention d'utiliser Vue sans outils de compilation en production, consultez le [Guide de déploiement en production](/guide/best-practices/production-deployment#without-build-tools).

Bien qu'il soit possible d'utiliser Vue sans outil de build, une alternative à considérer consiste à utiliser [`vuejs/petite-vue`](https://github.com/vuejs/petite-vue) qui pourrait mieux convenir au contexte dans lequel [`jquery/jquery`](https://github.com/jquery/jquery) (dans le passé) ou [`alpinejs/alpine`](https://github.com/alpinejs/alpine) (actuellement) pourrait plutôt être utilisée.
:::

### Séparation des modules {#splitting-up-the-modules}

Au fur et à mesure que nous progressons dans le guide, il se peut que nous devions diviser notre code en plusieurs fichiers JavaScript distincts afin d'en faciliter la gestion. Par exemple :

```html [index.html]
<div id="app"></div>

<script type="module">
  import { createApp } from 'vue'
  import MyComponent from './my-component.js'

  createApp(MyComponent).mount('#app')
</script>
```

```js [my-component.js]
export default {
  data() {
    return { count: 0 }
  },
  template: `<div>Count est égal à {{ count }}</div>`
}
```

```js [my-component.js]
import { ref } from 'vue'
export default {
  setup() {
    const count = ref(0)
    return { count }
  },
  template: `<div>Count est égal à {{ count }}</div>`
}
```

Si vous tentez d'ouvrir le fichier `index.html` ci-dessus dans votre navigateur, vous trouverez des erreurs relevées parce que les modules ES ne peuvent fonctionner via le protocol `file://`, qui est le protocole utilisé par le navigateur lorsque vous ouvrez un fichier local.

Pour des raisons de sécurité, les modules ES ne peuvent fonctionner que sur le protocole `http://`, qui est celui que les navigateurs utilisent lors de l'ouverture de pages sur le Web. Pour que les modules ES fonctionnent sur notre machine locale, nous devons servir le `index.html` sur le protocole `http://`, avec un serveur HTTP local.

Pour démarrer un serveur HTTP local, installez d'abord [Node.js](https://nodejs.org/en/), puis exécutez `npx serve` depuis la ligne de commande dans le même répertoire que votre fichier HTML. Vous pouvez également utiliser n'importe quel autre serveur HTTP qui peut servir des fichiers statiques avec les types MIME corrects.

Vous avez peut-être remarqué que le template du composant importé est souligné comme une chaîne JavaScript. Si vous utilisez VS Code, vous pouvez installer l'extension [es6-string-html](https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html) et préfixer les chaînes avec un commentaire `/*html*/` pour obtenir la coloration syntaxique.

## Étapes suivantes {#next-steps}

Si vous avez raté l'[Introduction](/guide/introduction), nous vous recommandons fortement d'en prendre connaissance avant de continuer sur la documentation.

---

---
url: /guide/best-practices/production-deployment.md
---
# Déploiement en production {#production-deployment}

## Développement vs. Production {#development-vs-production}

Durant le développement, Vue fournit un certain nombre de fonctionnalités pour améliorer l'expérience de développement :

* Avertissement pour les erreurs et les pièges
* Validation des props et des événements
* [Déboguer la réactivité](/guide/extras/reactivity-in-depth#reactivity-debugging)
* Intégration des Devtools

Cependant, ces fonctionnalités deviennent inutiles en production. Certains warnings peuvent également entraîner une petite baisse de performances générales. Lors du déploiement en production, nous devrions supprimer toutes les branches de code de développement inutilisées pour profiter d'une charge moins élevée et de meilleures performances.

## Sans les outils de build {#without-build-tools}

Si vous utilisez Vue sans outil de build, en le chargeant à partir d'un CDN ou d'un script local, assurez-vous d'utiliser le build de production (fichiers `dist` d'extension `.prod.js`) en déployant en production. Les builds de production sont pré-minifiés et toutes les branches de développement y sont supprimées.

* Si vous utilisez un build global (accédé via le `Vue` global) : utilisez `vue.global.prod.js`.
* Si vous utilisez un build ESM (accédé via les imports ESM natifs) : utilisez `vue.esm-browser.prod.js`.

Consultez le [guide des fichiers dist](https://github.com/vuejs/core/tree/main/packages/vue#which-dist-file-to-use) pour plus de précisions.

## Avec les outils de build {#with-build-tools}

Les projets crées par `create-vue` (basé sur Vite) ou Vue CLI (basé sur webpack) sont préconfigurés pour les builds de production.

Si vous utilisez une configuration personnalisée, assurez-vous que :

1. `vue` soit résolu par `vue.runtime.esm-bundler.js`.
2. Les [flags de temps de compilation](/api/compile-time-flags) sont configurés correctement.
3. process.env.NODE\_ENV est remplacé par `"production"` dans le build.

Références supplémentaires :

* [Guide de build de production Vite](https://vite.dev/guide/build.html)
* [Guide déploiement Vite](https://vite.dev/guide/static-deploy.html)
* [Guide de déploiement Vue CLI](https://cli.vuejs.org/guide/deployment.html)

## Suivi des erreurs d'exécution {#tracking-runtime-errors}

Le [gestionnaire d'erreur au niveau applicatif](/api/application#app-config-errorhandler) peut être utilisé pour signaler les erreurs aux services tiers de suivi :

```js
import { createApp } from 'vue'

const app = createApp(...)

app.config.errorHandler = (err, instance, info) => {
  // par exemple, signaler l'erreur à un service de suivi
}
```

Des services comme [Sentry](https://docs.sentry.io/platforms/javascript/guides/vue/) et [Bugsnag](https://docs.bugsnag.com/platforms/javascript/vue/) fournissent également des intégrations officielles de Vue.

---

---
url: /api/built-in-directives.md
---
# Directives natives {#built-in-directives}

## v-text {#v-text}

Met à jour le contenu texte d'un élément.

* **Attendu :** `string`

* **Détails**

  `v-text` fonctionne en définissant la propriété [textContent](https://developer.mozilla.org/fr/docs/Web/API/Node/textContent) de l'élément, ce qui écrase tout contenu existant à l'intérieur de l'élément. Si vous devez mettre à jour uniquement une partie du `textContent`, vous devez plutôt utiliser les [interpolations de texte](/guide/essentials/template-syntax#text-interpolation) (c'est-à-dire `<span>Conserver ceci mais mettre à jour {{dynamicPortion}}</span>`).

* **Exemple**

  ```vue-html
  <span v-text="msg"></span>
  <!-- same as -->
  <span>{{msg}}</span>
  ```

* **Voir aussi** [Syntaxe de template - Interpolation de texte](/guide/essentials/template-syntax#text-interpolation)

## v-html {#v-html}

Met à jour [innerHTML](https://developer.mozilla.org/fr/docs/Web/API/Element/innerHTML) de l'élément.

* **Attendu :** `string`

* **Détails**

  Le contenu de `v-html` est inséré en tant qu'HTML simple - la syntaxe des templates de Vue ne sera pas traitée. Si vous vous retrouvez à essayer de composer des templates en utilisant `v-html`, essayez de repenser la solution en utilisant plutôt des composants.

  ::: warning Remarque sur la sécurité
  Rendre dynamiquement du HTML arbitraire sur votre site web peut être très dangereux car cela peut facilement conduire à des [attaques XSS](https://fr.wikipedia.org/wiki/Cross-site_scripting). N'utilisez `v-html` que sur du contenu de confiance et **jamais** sur du contenu fourni par l'utilisateur.
  :::

  Dans les [composants monofichiers](/guide/scaling-up/sfc), les styles `scoped` ne s'appliqueront pas au contenu de `v-html`, car ce HTML n'est pas traité par le compilateur de templates de Vue. Si vous souhaitez cibler le contenu de `v-html` avec un CSS scopé, vous pouvez utiliser des [modules CSS](./sfc-css-features#css-modules) ou un élément `<style>` global supplémentaire avec une stratégie de scoping manuelle telle que BEM.

* **Exemple**

  ```vue-html
  <div v-html="html"></div>
  ```

* **Voir aussi** [Syntaxe de template - HTML brut](/guide/essentials/template-syntax#raw-html)

## v-show {#v-show}

Fait basculer la visibilité de l'élément en fonction de la valeur évaluée à vrai ou faux de l'expression.

* **Attendu :** `any`

* **Détails**

  `v-show` fonctionne en fixant la propriété CSS `display` via des styles littéraux, et essaiera de respecter la valeur initiale `display` lorsque l'élément est visible. Elle déclenche également des transitions lorsque sa condition change.

* **Voir aussi** [Rendu conditionnel - v-show](/guide/essentials/conditional#v-show)

## v-if {#v-if}

Rend conditionnellement un élément ou un fragment de template en fonction de la valeur de l'expression, évaluée à vrai ou faux.

* **Attendu :** `any`

* **Détails**

  Lorsqu'un élément comportant `v-if` est activé / désactivé, l'élément et les directives / composants qu'il contient sont détruits et reconstruits. Si la condition initiale est fausse, le contenu interne ne sera pas rendu du tout.

  Peut être utilisée sur `<template>` pour désigner un bloc conditionnel contenant uniquement du texte ou plusieurs éléments.

  Cette directive déclenche des transitions lorsque sa condition change.

  Lorsqu'elles sont utilisées ensemble, `v-if' a une priorité plus élevée que `v-for'. Il est déconseillé d'utiliser ces deux directives ensemble sur un même élément - voir le [guide du rendu de liste](/guide/essentials/list#v-for-with-v-if) pour plus de détails.

* **Voir aussi** [Rendu conditionnel - v-if](/guide/essentials/conditional#v-if)

## v-else {#v-else}

Représente le bloc "else" pour `v-if` ou une chaîne `v-if` / `v-else-if`.

* **N'attend pas d'expression**

* **Détails**

  * Restriction : l'élément frère précédent doit posséder `v-if` ou `v-else-if`.

  * Peut être utilisée sur `<template>` pour désigner un bloc conditionnel contenant uniquement du texte ou plusieurs éléments.

* **Exemple**

  ```vue-html
  <div v-if="Math.random() > 0.5">
    Now you see me
  </div>
  <div v-else>
    Now you don't
  </div>
  ```

* **Voir aussi** [Rendu conditionnel - v-else](/guide/essentials/conditional#v-else)

## v-else-if {#v-else-if}

Désigne le bloc "else if" pour `v-if`. Peut être chaîné.

* **Attendu :** `any`

* **Détails**

  * Restriction : l'élément frère précédent doit avoir `v-if` ou `v-else-if`.

  * Peut être utilisé sur `<template>` pour désigner un bloc conditionnel contenant uniquement du texte ou plusieurs éléments.

* **Exemple**

  ```vue-html
  <div v-if="type === 'A'">
    A
  </div>
  <div v-else-if="type === 'B'">
    B
  </div>
  <div v-else-if="type === 'C'">
    C
  </div>
  <div v-else>
    Not A/B/C
  </div>
  ```

* **Voir aussi** [Rendu conditionnel - v-else-if](/guide/essentials/conditional#v-else-if)

## v-for {#v-for}

Rend l'élément ou le bloc d'un template plusieurs fois en fonction des données sources.

* **Attendu :** `Array | Object | number | string | Iterable`

* **Détails**

  La valeur de la directive doit utiliser la syntaxe spéciale `alias in expression` pour fournir un alias pour l'élément courant sur lequel on itère :

  ```vue-html
  <div v-for="item in items">
    {{ item.text }}
  </div>
  ```

  De manière alternative, vous pouvez également spécifier un alias pour l'index (ou la clé si elle est utilisée sur un objet) :

  ```vue-html
  <div v-for="(item, index) in items"></div>
  <div v-for="(value, key) in object"></div>
  <div v-for="(value, name, index) in object"></div>
  ```

  Le comportement par défaut de `v-for` essaiera de corriger les éléments en place sans les déplacer. Pour forcer la réorganisation des éléments, vous devez fournir un indice d'ordre avec l'attribut spécial `key` :

  ```vue-html
  <div v-for="item in items" :key="item.id">
    {{ item.text }}
  </div>
  ```

  `v-for` peut également fonctionner sur les valeurs qui implémentent le [protocole d'itération](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol), y compris les `Map` et `Set` natifs.

* **Voir aussi**
  * [Rendu de liste](/guide/essentials/list)

## v-on {#v-on}

Attache un écouteur d'événements à l'élément.

* **Raccourci :** `@`

* **Attendu :** `Function | Inline Statement | Object (sans argument)`

* **Argument :** `event` (optionnel lors de l'utilisation de la syntaxe objet)

* **Modificateurs**

  * `.stop` - appelle `event.stopPropagation()`.
  * `.prevent` - appelle `event.preventDefault()`.
  * `.capture` - ajoute un écouteur d'événements en mode capture.
  * `.self` - ne déclenche le gestionnaire que si l'événement a été envoyé par cet élément.
  * `.{keyAlias}` - ne déclenche le gestionnaire que sur certaines clés.
  * `.once` - déclenche le gestionnaire au moins une fois.
  * `.left` - ne déclenche le gestionnaire que pour les événements liés au bouton gauche de la souris.
  * `.right` - ne déclenche le gestionnaire que pour les événements liés au bouton droit de la souris.
  * `.middle` - ne déclenche le gestionnaire que pour les événements liés au bouton du milieu de la souris.
  * `.passive` - attache un événement DOM avec `{ passive : true }`.

* **Détails**

  Le type d'événement est indiqué par l'argument. L'expression peut être un nom de méthode, une déclaration littérale, ou omise si des modificateurs sont présents.

  Lorsqu'elle est utilisée sur un élément normal, elle écoute uniquement les [**événements natifs du DOM**](https://developer.mozilla.org/fr/docs/Web/Events). Lorsqu'elle est utilisée sur un composant d'éléments personnalisés, elle écoute les **événements personnalisés** émis sur ce composant enfant.

  Lorsqu'elle écoute les événements natifs du DOM, la méthode reçoit l'événement natif comme seul argument. Si vous utilisez une déclaration en ligne, la déclaration a accès à la propriété spéciale `$event` : `v-on:click="handle('ok', $event)"`.

  `v-on` supporte également la liaison à un objet de paires événement / écouteur sans argument. Notez que lorsque vous utilisez la syntaxe objet, elle ne supporte aucun modificateur.

* **Exemple**

  ```vue-html
  <!-- méthode gestionnaire -->
  <button v-on:click="doThis"></button>

  <!-- événement dynamique -->
  <button v-on:[event]="doThis"></button>

  <!-- expression littérale -->
  <button v-on:click="doThat('hello', $event)"></button>

  <!-- raccourci -->
  <button @click="doThis"></button>

  <!-- raccourci d'un événement dynamique -->
  <button @[event]="doThis"></button>

  <!-- arrête la propagation -->
  <button @click.stop="doThis"></button>

  <!-- empêche le comportement par défaut -->
  <button @click.prevent="doThis"></button>

  <!-- empêche le comportement par défaut sans expression -->
  <form @submit.prevent></form>

  <!-- modificateurs enchaînés -->
  <button @click.stop.prevent="doThis"></button>

  <!-- modificateur de clé en utilisant keyAlias -->
  <input @keyup.enter="onEnter" />

  <!-- l'événement de clic sera déclenché seulement une fois -->
  <button v-on:click.once="doThis"></button>

  <!-- syntaxe objet -->
  <button v-on="{ mousedown: doThis, mouseup: doThat }"></button>
  ```

  Écoute des événements personnalisés sur un composant enfant (le gestionnaire est appelé lorsque "my-event" est émis sur l'enfant) :

  ```vue-html
  <MyComponent @my-event="handleThis" />

  <!-- expression en ligne -->
  <MyComponent @my-event="handleThis(123, $event)" />
  ```

* **Voir aussi**
  * [Gestion d'événement](/guide/essentials/event-handling)
  * [Composants - Événements personnalisés](/guide/essentials/component-basics#listening-to-events)

## v-bind {#v-bind}

Lie dynamiquement un ou plusieurs attributs, ou une prop d'un composant à une expression.

* **Raccourci :**
  * `:` ou `.` (lorsqu'on utilise le modificateur `.prop`)
  * En omettant la valeur (lorsque l'attribut et la valeur liée portent le même nom, requière 3.4+)

* **Attendu :** `any (avec argument) | Object (sans argument)`

* **Argument :** `attrOrProp (optionnel)`

* **Modificateurs**

  * `.camel` - transforme le nom de l'attribut kebab-case en camelCase.
  * `.prop` - force une liaison à être définie comme une propriété du DOM (3.2+).
  * `.attr` - force une liaison à être définie comme un attribut du DOM (3.2+).

* **Utilisation :**

  Lorsqu'elle est utilisée pour lier l'attribut `class` ou `style`, `v-bind` supporte des types de valeurs supplémentaires comme Array ou Objects. Voir la section du guide lié ci-dessous pour plus de détails.

  Lors de la mise en place d'une liaison sur un élément, Vue va vérifier par défaut si l'élément a la clé définie comme une propriété en faisant une vérification de l'opérateur `in`. Si la propriété est définie, Vue définira la valeur comme une propriété du DOM au lieu d'un attribut. Cela devrait fonctionner dans la plupart des cas, mais vous pouvez outrepasser ce comportement en utilisant explicitement les modificateurs `.prop` ou `.attr`. Cela est parfois nécessaire, notamment lorsque vous [travaillez avec des éléments personnalisés](/guide/extras/web-components#passing-dom-properties).

  Lorsqu'elle est utilisée pour lier les props du composant, la prop doit être correctement déclarée dans le composant enfant.

  Lorsqu'elle est utilisée sans argument, elle peut être utilisée pour lier un objet contenant des paires nom-valeur d'attributs.

* **Exemple**

  ```vue-html
  <!-- lie un attribut -->
  <img v-bind:src="imageSrc" />

  <!-- nom d'attribut dynamique -->
  <button v-bind:[key]="value"></button>

  <!-- raccourci -->
  <img :src="imageSrc" />

  <!-- raccourci même nom (3.4+), se transforme en :src="src" -->
  <img :src />

  <!-- raccourci d'un nom d'attribut dynamique -->
  <button :[key]="value"></button>

  <!-- avec une concaténation de chaînes de caractères en ligne -->
  <img :src="'/path/to/images/' + fileName" />

  <!-- liaison de classe -->
  <div :class="{ red: isRed }"></div>
  <div :class="[classA, classB]"></div>
  <div :class="[classA, { classB: isB, classC: isC }]"></div>

  <!-- liaison de style -->
  <div :style="{ fontSize: size + 'px' }"></div>
  <div :style="[styleObjectA, styleObjectB]"></div>

  <!-- liaison d'un objet d'attributs -->
  <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>

  <!-- liaison de prop. "prop" doit être déclaré dans le composant enfant. -->
  <MyComponent :prop="someThing" />

  <!-- transmet les props du parent en commun avec un composant enfant -->
  <MyComponent v-bind="$props" />

  <!-- XLink -->
  <svg><a :xlink:special="foo"></a></svg>
  ```

  Le modificateur `.prop` a également un raccourci dédié, `.` :

  ```vue-html
  <div :someProperty.prop="someObject"></div>

  <!-- équivalent à -->
  <div .someProperty="someObject"></div>
  ```

  Le modificateur `.camel` permet de formatter un nom d'attribut `v-bind` en camelCase lors de l'utilisation de templates à l'intérieur du DOM, par exemple l'attribut SVG `viewBox` :

  ```vue-html
  <svg :view-box.camel="viewBox"></svg>
  ```

  `.camel` n'est pas nécessaire si vous utilisez des templates en chaînes de caractères, ou si vous pré-compilez le template avec un outil de build.

* **Voir aussi**
  * [Liaison de classes et de styles](/guide/essentials/class-and-style)
  * [Composant - Détails sur le passage de props](/guide/components/props#prop-passing-details)

## v-model {#v-model}

Crée une liaison bidirectionnelle sur un élément de saisie de formulaire ou un composant.

* **Attendu :** varie en fonction de la valeur de l'élément d'entrée du formulaire ou de la sortie des composants

* **Limitée à :**

  * `<input>`
  * `<select>`
  * `<textarea>`
  * composants

* **Modificateurs**

  * [`.lazy`](/guide/essentials/forms#lazy) - écoute les événements `change` au lieu de `input`.
  * [`.number`](/guide/essentials/forms#number) - convertit une entrée valide en chaînes de caractères en nombres
  * [`.trim`](/guide/essentials/forms#trim) - élague l'entrée

* **Voir aussi**

  * [Liaisons des entrées d'un formulaire](/guide/essentials/forms)
  * [Événements du composant - Utilisation avec `v-model`](/guide/components/v-model)

## v-slot {#v-slot}

Désigne les slots nommés ou les slots scopés qui s'attendent à recevoir des props.

* **Raccourci :** `#`

* **Attendu :** Une expression JavaScript valide en tant qu'argument de fonction, y compris concernant la déstructuration. Facultatif - uniquement nécessaire si l'on s'attend à ce que des props soient passés au slot.

* **Argument :** nom du slot (facultatif, la valeur par défaut est `default`)

* **Limitée à :**

  * `<template>`
  * [composants](/guide/components/slots#scoped-slots) (pour un seul slot par défaut avec des props)

* **Exemple**

  ```vue-html
  <!-- Slots nommés -->
  <BaseLayout>
    <template v-slot:header>
      Header content
    </template>

    <template v-slot:default>
      Default slot content
    </template>

    <template v-slot:footer>
      Footer content
    </template>
  </BaseLayout>

  <!-- Slot nommé recevant des props -->
  <InfiniteScroll>
    <template v-slot:item="slotProps">
      <div class="item">
        {{ slotProps.item.text }}
      </div>
    </template>
  </InfiniteScroll>

  <!-- Slot par défaut recevant des props, via la déstructuration -->
  <Mouse v-slot="{ x, y }">
    Mouse position: {{ x }}, {{ y }}
  </Mouse>
  ```

* **Voir aussi**
  * [Composants - Slots](/guide/components/slots)

## v-pre {#v-pre}

Ignore la compilation pour cet élément et tous ses enfants.

* **N'attend pas d'expression**

* **Détails**

  À l'intérieur de l'élément contenant `v-pre`, toute la syntaxe du template Vue sera préservée et rendue telle quelle. Le cas d'utilisation le plus courant est l'affichage brut des balises moustaches.

* **Exemple**

  ```vue-html
  <span v-pre>{{ this will not be compiled }}</span>
  ```

## v-once {#v-once}

Rend l'élément et le composant une seule fois, et ignore les mises à jour futures.

* **N'attend pas d'expression**

* **Détails**

  Lors des rendus suivants, l'élément/composant et tous ses enfants seront traités comme du contenu statique et ignorés. Cela peut être utilisé pour optimiser les performances de mise à jour.

  ```vue-html
  <!-- élément simple -->
  <span v-once>This will never change: {{msg}}</span>
  <!-- l'élément a des enfants -->
  <div v-once>
    <h1>Comment</h1>
    <p>{{msg}}</p>
  </div>
  <!-- composant -->
  <MyComponent v-once :comment="msg"></MyComponent>
  <!-- directive `v-for` -->
  <ul>
    <li v-for="i in list" v-once>{{i}}</li>
  </ul>
  ```

  Depuis la version 3.2, vous pouvez également mémoriser une partie du template avec des conditions d'invalidation en utilisant [`v-memo`](#v-memo).

* **Voir aussi**
  * [Syntaxe de la liaison bidirectionnelle - interpolations](/guide/essentials/template-syntax#text-interpolation)
  * [v-memo](#v-memo)

## v-memo {#v-memo}

* Supporté à partir de la version 3.2

* **Attendu :** `any[]`

* **Détails**

  Mémorise une sous-arborescence du template. Peut être utilisée à la fois sur les éléments et les composants. La directive attend un tableau de longueur connue composé de valeurs de dépendances à comparer pour la mémorisation. Si toutes les valeurs du tableau sont identiques à celles du dernier rendu, les mises à jour de l'ensemble du sous-arbre seront ignorées. Par exemple :

  ```vue-html
  <div v-memo="[valueA, valueB]">
    ...
  </div>
  ```

  Lors du rendu du composant, si `valueA` et `valueB` restent les mêmes, toutes les mises à jour de cette `<div>` et de ses enfants seront ignorées. En fait, même la création du VNode du DOM virtuel sera ignorée puisque la copie mémorisée de la sous-arborescence peut être réutilisée.

  Il est important de spécifier le tableau de mémorisation correctement, sinon nous pourrions sauter des mises à jour qui devraient normalement être appliquées. `v-memo` avec un tableau de dépendances vide (`v-memo="[]"`) serait fonctionnellement équivalent à `v-once`.

  **Utilisation avec `v-for`**

  `v-memo` est fourni uniquement pour des micro-optimisations dans des scénarios de performances critiques et devrait être rarement utilisée. Le cas le plus courant où cela peut s'avérer utile est lors du rendu de grandes listes `v-for` (où `length > 1000`) :

  ```vue-html
  <div v-for="item in list" :key="item.id" v-memo="[item.id === selected]">
    <p>ID: {{ item.id }} - selected: {{ item.id === selected }}</p>
    <p>...more child nodes</p>
  </div>
  ```

  Lorsque l'état `selected` du composant change, une grande quantité de VNodes sera créée même si la plupart des éléments restent exactement les mêmes. L'utilisation de `v-memo` ici consiste essentiellement à dire "met à jour cet élément seulement s'il est passé de non sélectionné à sélectionné, ou vice-versa". Cela permet à chaque élément non affecté de réutiliser son précédent VNode et d'éviter de changer entièrement. Notez que nous n'avons pas besoin d'inclure `item.id` dans le tableau de dépendances des mémos ici puisque Vue le déduit automatiquement à partir de `:key`.

  :::warning
  Lorsque vous utilisez les directives `v-memo` avec `v-for`, assurez-vous qu'elles sont utilisées sur le même élément. **`v-memo` ne fonctionne pas à l'intérieur de `v-for`.**
  :::

  `v-memo` peut également être utilisée sur les composants pour empêcher manuellement les mises à jour non désirées dans certains cas limites où la vérification de la mise à jour du composant enfant n'est pas optimisée. Mais une fois de plus, il est de la responsabilité du développeur de spécifier des tableaux de dépendances corrects pour éviter d'ignorer des mises à jour nécessaires.

* **Voir aussi**
  * [v-once](#v-once)

## v-cloak {#v-cloak}

Utilisée pour cacher un template non compilé jusqu'à ce qu'il soit prêt.

* **N'attend pas d'expression**

* **Détails**

  **Cette directive n'est nécessaire que dans les configurations sans étape de build.**

  Lors de l'utilisation de templates à l'intérieur du DOM, il peut y avoir un "flash de templates non compilés" : l'utilisateur peut voir des balises moustaches brutes jusqu'à ce que le composant monté les remplace par du contenu rendu.

  `v-cloak` restera sur l'élément jusqu'à ce que l'instance du composant associé soit montée. Combiné à des règles CSS telles que `[v-cloak] { display : none }`, elle peut être utilisée pour masquer les templates bruts jusqu'à ce que le composant soit prêt.

* **Exemple**

  ```css
  [v-cloak] {
    display: none;
  }
  ```

  ```vue-html
  <div v-cloak>
    {{ message }}
  </div>
  ```

  La `<div>` ne sera pas visible tant que la compilation n'est pas terminée.

---

---
url: /guide/reusability/custom-directives.md
---
# Directives personnalisées {#custom-directives}

## Introduction {#introduction}

En plus du jeu de directives par défaut fourni par Vue (comme `v-model` ou `v-show`), Vue permet également d'enregistrer vos propres directives personnalisées.

Nous avons introduit deux formes de code réutilisable dans Vue : [les composants](/guide/essentials/component-basics) et [les composables](./composables). Les composants sont les principaux éléments de construction, alors que les composables sont axés sur la réutilisation de la logique d'état. Les directives personnalisées, quant à elles, sont principalement destinées à réutiliser la logique qui implique un accès de bas niveau au DOM sur des éléments simples.

Une directive personnalisée se définit comme un objet contenant des hooks du cycle de vie, similaires à ceux d'un composant. Les hooks reçoivent l'élément auquel la directive est liée. Voici un exemple de directive qui ajoute une classe à un élément lorsqu'il est inséré dans le DOM par Vue :

```vue
<script setup>
// active v-highlight dans les templates
const vHighlight = {
  mounted: (el) => {
    el.classList.add('is-highlight')
  }
}
</script>

<template>
  <p v-highlight>Cette phrase est importante !</p>
</template>
```

```js
const highlight = {
  mounted: (el) => el.classList.add('is-highlight')
}

export default {
  directives: {
    // active v-highlight dans le template
    highlight
  }
}
```

```vue-html
<p v-highlight>Cette phrase est importante !</p>
```

Dans `<script setup>`, toute variable camelCase qui commence par le préfixe `v` peut être utilisée comme une directive personnalisée. Dans l'exemple ci-dessus, `vHighlight` peut être utilisé dans le template via `v-highlight`.

Si vous n'utilisez pas `<script setup>`, les directives personnalisées peuvent être enregistrées grâce à l'option `directives` :

```js
export default {
  setup() {
    /*...*/
  },
  directives: {
    // active v-highlight dans le template
    highlight: {
      /* ... */
    }
  }
}
```

Comme pour les composants, les directives personnalisées doivent être enregistrées afin de pouvoir être utilisées dans les modèles. Dans l'exemple ci-dessus, nous utilisons l'enregistrement local via l'option `directives`.

Il est également courant d'enregistrer globalement des directives personnalisées au niveau de l'application :

```js
const app = createApp({})

// rendre v-highlight utilisable dans tous les composants
app.directive('highlight', {
  /* ... */
})
```

Il est possible de saisir des directives personnalisées globales en étendant l'interface `GlobalDirectives` à partir de `vue`.

Plus de détails : [Typer les directives globales personnalisées](/guide/typescript/composition-api#typing-global-custom-directives)&#x20;

## Quand utiliser les directives personnalisées {#when-to-use}

Les directives personnalisées ne doivent être utilisées que lorsque la fonctionnalité souhaitée ne peut être obtenue que par une manipulation directe du DOM.

Un exemple courant est la directive personnalisée `v-focus` qui met un élément au premier plan.

```vue
<script setup>
// active v-focus dans le template
const vFocus = {
  mounted: (el) => el.focus()
}
</script>
<template>
  <input v-focus />
</template>
```

```js
const focus = {
  mounted: (el) => el.focus()
}

export default {
  directives: {
    // active v-focus dans le template
    focus
  }
}
```

```vue-html
<input v-focus />
```

Cette directive est plus utile que l'attribut `autofocus` car elle ne fonctionne pas seulement au chargement de la page - elle fonctionne également lorsque l'élément est inséré dynamiquement par Vue !

La déclaration de template avec des directives intégrées telles que `v-bind` est recommandé lorsque c'est possible, car il est plus efficace et plus facile à gérer pour le serveur.

## Hooks des directives {#directive-hooks}

La définition d'un objet directive peut fournir plusieurs fonctions de hook (toutes optionnelles) :

```js
const myDirective = {
  // appelé avant les attributs de l'élément lié
  // ou que les écouteurs d'événements soient appliqués
  created(el, binding, vnode) {
    // voir ci-dessous pour plus de détails sur les arguments
  },
  // appelé juste avant que l'élément ne soit inséré dans le DOM.
  beforeMount(el, binding, vnode) {},
  // appelé lorsque le composant parent de l'élément lié
  // et tous ses enfants sont montés.
  mounted(el, binding, vnode) {},
  // appelé avant que le composant parent ne soit mis à jour
  beforeUpdate(el, binding, vnode, prevVnode) {},
  // appelé après que le composant parent et
  // tous ses enfants aient été mis à jour
  updated(el, binding, vnode, prevVnode) {},
  // appelé avant que le composant parent ne soit démonté
  beforeUnmount(el, binding, vnode) {},
  // appelé lorsque le composant parent est démonté
  unmounted(el, binding, vnode) {}
}
```

### Arguments d'un hook {#hook-arguments}

Les hooks des directives fournissent ces différents arguments :

* `el`: l'élément auquel la directive est liée. Il peut être utilisé pour manipuler le DOM directement.

* `binding`: un objet contenant les propriétés suivantes.

  * `value`: La valeur transmise à la directive. Par exemple, dans `v-my-directive="1 + 1"`, la valeur sera `2`.
  * `oldValue`: La valeur précédente, disponible uniquement dans `beforeUpdate` et `updated`. Elle est disponible que la valeur ait changé ou non.
  * `arg`: L'argument passé à la directive, s'il y en a un. Par exemple, dans `v-my-directive:foo`, l'argument sera `"foo"`.
  * `modifiers`: Un objet contenant des modificateurs, s'il y en a. Par exemple, dans `v-my-directive.foo.bar`, l'objet modificateur sera `{ foo : true, bar : true }`.
  * `instance`: L'instance du composant où la directive est utilisée.
  * `dir`: l'objet de définition de la directive.

* `vnode`: le VNode sous-jacent représentant l'élément lié.

* `prevVnode`: le VNode représentant l'élément lié du rendu précédent. Disponible uniquement dans les hooks `beforeUpdate` et `updated`.

En guise d'exemple, considérez l'utilisation de la directive suivante :

```vue-html
<div v-example:foo.bar="baz">
```

L'argument `binding` serait un objet de la forme de :

```js
{
  arg: 'foo',
  modifiers: { bar: true },
  value: /* valeur de `baz` */,
  oldValue: /* valeur de `baz` de la mise à jour précédente */
}
```

De la même manière que pour les directives natives, les arguments des directives personnalisées peuvent être dynamiques. Par exemple :

```vue-html
<div v-example:[arg]="value"></div>
```

Ici, l'argument de la directive sera mis à jour de manière réactive en fonction de la propriété `arg` dans l'état de notre composant.

:::tip Remarque
En dehors de `el`, vous devez traiter ces arguments comme étant en lecture seule et ne jamais les modifier. Si vous devez partager des informations entre plusieurs hooks, il est recommandé de le faire par le biais de [dataset](https://developer.mozilla.org/fr/docs/Web/API/HTMLElement/dataset) de l'élément.
:::

## Abréviations de fonctions {#function-shorthand}

Il est courant qu'une directive personnalisée ait le même comportement pour `mounted` et `updated`, sans avoir besoin des autres hooks. Dans ce cas, nous pouvons définir la directive comme une fonction :

```vue-html
<div v-color="color"></div>
```

```js
app.directive('color', (el, binding) => {
  // sera appelée à la fois au `mounted` et au `updated`
  el.style.color = binding.value
})
```

## Littéraux d'un objet {#object-literals}

Si votre directive a besoin de plusieurs valeurs, vous pouvez également lui passer un objet JavaScript littéral. Souvenez-vous, les directives peuvent prendre n'importe quelle expression JavaScript valide.

```vue-html
<div v-demo="{ color: 'white', text: 'hello!' }"></div>
```

```js
app.directive('demo', (el, binding) => {
  console.log(binding.value.color) // => "blanc"
  console.log(binding.value.text) // => "bonjour!"
})
```

## Utilisation sur les composants {#usage-on-components}

:::warning Non recommandé
L'utilisation de directives personnalisées sur les composants n'est pas recommandée. Un comportement inattendu peut se produire lorsqu'un composant a plusieurs nœuds racine.
:::

Lorsqu'elles sont utilisées sur des composants, les directives personnalisées s'appliquent toujours au nœud racine du composant, comme dans les [attributs implicitement déclarés](/guide/components/attrs).

```vue-html
<MyComponent v-demo="test" />
```

```vue-html
<!-- template de MyComponent -->

<div> <!-- la directive v-demo sera appliquée ici -->
  <span>My component content</span>
</div>
```

Notez que les composants peuvent potentiellement avoir plus d'un nœud racine. Lorsqu'elle est appliquée à un composant multi-racine, une directive sera ignorée et un avertissement sera envoyé. Contrairement aux attributs, les directives ne peuvent pas être passées à un autre élément avec `v-bind="$attrs"`.

---

---
url: /api/built-in-special-elements.md
---
# Éléments spéciaux natifs {#built-in-special-elements}

:::info Pas des composants
`<component>`, `<slot>` et `<template>` sont des fonctionnalités semblables aux composants et font partie de la syntaxe des templates. Ce ne sont pas de véritables composants et ils sont supprimés lors de la compilation des templates. En tant que tels, ils sont conventionnellement écrits en minuscules dans les templates.
:::

## `<component>` {#component}

Un "méta-composant" pour rendre des composants ou éléments dynamiques.

* **Props :**

  ```ts
  interface DynamicComponentProps {
    is: string | Component
  }
  ```

* **Détails**

  Le composant à rendre est déterminé par la propriété "is".

  * Lorsque `is` est une chaîne de caractères, il peut s'agir du nom d'une balise HTML ou du nom d'un composant enregistré.

  * De manière alternative, `is` peut également être directement lié à la définition d'un composant.

* **Exemple**

  Rendu des composants par nom d'enregistrement (Options API) :

  ```vue
  <script>
  import Foo from './Foo.vue'
  import Bar from './Bar.vue'

  export default {
    components: { Foo, Bar },
    data() {
      return {
        view: 'Foo'
      }
    }
  }
  </script>

  <template>
    <component :is="view" />
  </template>
  ```

  Rendu de composants par définition (Composition API avec `<script setup>`) :

  ```vue
  <script setup>
  import Foo from './Foo.vue'
  import Bar from './Bar.vue'
  </script>

  <template>
    <component :is="Math.random() > 0.5 ? Foo : Bar" />
  </template>
  ```

  Rendu d'éléments HTML :

  ```vue-html
  <component :is="href ? 'a' : 'span'"></component>
  ```

  Les [composants natifs](./built-in-components) peuvent tous être passés à `is`, mais vous devez les enregistrer si vous voulez les passer par leur nom. Par exemple :

  ```vue
  <script>
  import { Transition, TransitionGroup } from 'vue'

  export default {
    components: {
      Transition,
      TransitionGroup
    }
  }
  </script>

  <template>
    <component :is="isGroup ? 'TransitionGroup' : 'Transition'">
      ...
    </component>
  </template>
  ```

  L'enregistrement n'est pas nécessaire si vous passez directement le composant à `is` plutôt que son nom, par exemple dans `<script setup>`.

  Si `v-model` est utilisée sur une balise `<component>`, le compilateur de templates le transformera en une prop `modelValue` et un écouteur d'événements `update:modelValue`, comme il le ferait pour tout autre composant. Cependant, cela ne sera pas compatible avec les éléments HTML natifs, tels que `<input>` ou `<select>`. Par conséquent, l'utilisation de `v-model` avec un élément natif créé dynamiquement ne fonctionnera pas :

  ```vue
  <script setup>
  import { ref } from 'vue'

  const tag = ref('input')
  const username = ref('')
  </script>

  <template>
    <!-- Cela ne fonctionnera pas car "input" est un élément HTML natif. -->
    <component :is="tag" v-model="username" />
  </template>
  ```

  En pratique, ce cas de figure n'est pas courant car les champs de formulaire natifs sont généralement enveloppés dans des composants dans les applications réelles. Si vous avez besoin d'utiliser directement un élément natif, vous pouvez diviser manuellement le "v-model" en un attribut et un événement.

* **Voir aussi** [Composants dynamiques](/guide/essentials/component-basics#dynamic-components)

## `<slot>` {#slot}

Indique l'emplacement du contenu d'un slot dans les templates.

* **Props :**

  ```ts
  interface SlotProps {
    /**
     * Toutes les props passées à <slot> à passer comme arguments
     * aux slots scopés
     */
    [key: string]: any
    /**
     * Réservé pour spécifier le nom du slot.
     */
    name?: string
  }
  ```

* **Détails**

  L'élément `<slot>` peut utiliser l'attribut `name` pour spécifier un nom de slot. Si aucun `name` n'est spécifié, l'élément rendra le slot par défaut. Les attributs supplémentaires passés à l'élément slot seront passés comme des props de slot au slot scopé défini dans le parent.

  L'élément lui-même sera remplacé par le contenu du slot correspondant.

  Les éléments `<slot>` dans les templates Vue sont compilés en JavaScript, ils ne doivent donc pas être confondus avec les [éléments `<slot>` natifs](https://developer.mozilla.org/fr/docs/Web/HTML/Element/slot).

* **Voir aussi** [Composant - Slots](/guide/components/slots)

## `<template>` {#template}

La balise `<template>` est utilisée comme placeholder lorsque nous voulons utiliser une directive native sans rendre un élément dans le DOM.

* **Détails**

  Le traitement spécial de `<template>` n'est déclenché que s'il est utilisé avec l'une de ces directives :

  * `v-if`, `v-else-if`, or `v-else`
  * `v-for`
  * `v-slot`

  Si aucune de ces directives n'est présente, il sera rendu comme un [élément natif `<template>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/template) à la place.

  Un `<template>` avec un `v-for` peut aussi avoir un attribut [`key`](/api/built-in-special-attributes#key). Tous les autres attributs et directives seront rejetés, car ils n'ont pas de sens sans l'élément correspondant.

  Les composants monofichiers utilisent une [top-level `<template>` tag](/api/sfc-spec#language-blocks) pour envelopper l'ensemble du template. Cette utilisation est distincte de l'utilisation de `<template>` décrite ci-dessus. Cette balise de haut niveau ne fait pas partie du modèle lui-même et ne supporte pas la syntaxe template, comme les directives.

* **Voir aussi**
  * [Guide - `v-if` avec `<template>`](/guide/essentials/conditional#v-if-on-template)
  * [Guide - `v-for` avec `<template>`](/guide/essentials/list#v-for-on-template)
  * [Guide - Slots nommés](/guide/components/slots#named-slots)

---

---
url: /guide/components/registration.md
---
# Enregistrement des composants {#component-registration}

> Cette page suppose que vous avez déjà lu les [principes fondamentaux des composants](/guide/essentials/component-basics). Lisez-les d'abord si vous débutez avec les composants.

Un composant Vue doit être "enregistré" afin que Vue sache où localiser son implémentation lorsqu'il est rencontré dans un template. Il existe deux façons d'enregistrer des composants : globale et locale.

## Enregistrement global {#global-registration}

Nous pouvons rendre les composants disponibles globalement dans l'[application Vue](/guide/essentials/application) actuelle en utilisant la méthode `.component()` :

```js
import { createApp } from 'vue'

const app = createApp({})

app.component(
  // le nom enregistré
  'MyComponent',
  // l'implémentation
  {
    /* ... */
  }
)
```

Si vous utilisez des SFC, vous enregistrerez les fichiers `.vue` importés :

```js
import MyComponent from './App.vue'

app.component('MyComponent', MyComponent)
```

La méthode `.component()` peut être chaînée :

```js
app
  .component('ComponentA', ComponentA)
  .component('ComponentB', ComponentB)
  .component('ComponentC', ComponentC)
```

Les composants enregistrés globalement peuvent être utilisés dans le template de n'importe quel composant de cette application :

```vue-html
<!-- cela fonctionnera dans n'importe quel composant de l'application -->
<ComponentA/>
<ComponentB/>
<ComponentC/>
```

Cela s'applique même à tous les sous-composants, ce qui signifie que ces trois composants seront également disponibles *dans chacun d'eux*.

## Enregistrement local {#local-registration}

Bien que pratique, l'enregistrement global présente quelques inconvénients :

1. L'enregistrement global empêche les systèmes de build de supprimer les composants inutilisés (alias "tree-shaking"). Si vous enregistrez globalement un composant mais que vous ne l'utilisez nulle part dans votre application, il sera toujours inclus dans le bundle final.

2. L'enregistrement global rend les relations entre dépendances moins explicites dans les applications de taille importante. Cela rend difficile la localisation de l'implémentation d'un composant enfant à partir d'un composant parent qui l'utilise. Cela peut affecter la maintenabilité à long terme, de la même manière que si vous utilisiez trop de variables globales.

L'enregistrement local limite la disponibilité des composants enregistrés au composant actuel uniquement. Cela rend la relation de dépendance plus explicite et est plus adaptée au tree-shaking.

Lors de l'utilisation de SFC avec `<script setup>`, les composants importés peuvent être utilisés localement sans enregistrement :

```vue
<script setup>
import ComponentA from './ComponentA.vue'
</script>

<template>
  <ComponentA />
</template>
```

Dans une configuration sans `<script setup>`, vous devrez utiliser l'option `components` :

```js
import ComponentA from './ComponentA.js'

export default {
  components: {
    ComponentA
  },
  setup() {
    // ...
  }
}
```

L'enregistrement local se fait à l'aide de l'option `components` :

```vue
<script>
import ComponentA from './ComponentA.vue'

export default {
  components: {
    ComponentA
  }
}
</script>

<template>
  <ComponentA />
</template>
```

Pour chaque propriété de l'objet `components`, la clé sera le nom enregistré du composant, tandis que la valeur contiendra l'implémentation du composant. L'exemple ci-dessus utilise le raccourci de propriété ES2015 et équivaut à :

```js
export default {
  components: {
    ComponentA: ComponentA
  }
  // ...
}
```

Notez que **les composants enregistrés localement *ne* sont *pas* également disponibles dans les composants descendants**. Dans ce cas, `ComponentA` ne sera disponible que dans le composant actuel, et non pas dans tous autres de ses composants enfants ou descendants.

## Casse des noms des composants {#component-name-casing}

Tout au long de ce guide, nous utilisons des noms en casse Pascal (PascalCase) lors de l'enregistrement des composants. Ceci est dû au fait que :

1. Les noms en casse Pascal sont des identifiants JavaScript valides. Cela facilite l'import et l'enregistrement des composants en JavaScript. Il aide également les IDE avec l'auto-complétion.

2. `<PascalCase />` rend plus évident qu'il s'agit d'un composant Vue au lieu d'un élément HTML natif dans les templates. Il différencie également les composants Vue des custom elements (web components).

Il s'agit du style recommandé lorsque vous travaillez avec des templates à base de SFC ou de chaînes de caractères. Cependant, comme indiqué dans [les mises en garde concernant l'analyse du template DOM](/guide/essentials/component-basics#in-dom-template-parsing-caveats), les balises déclarées en casse Pascal ne sont pas utilisables dans les templates DOM.

Heureusement, Vue prend en charge la résolution des balises au format kebab-case et leur équivalent composants enregistrés à la condition qu'ils utilisent la casse Pascal. Cela signifie qu'un composant enregistré en tant que `MyComponent` peut être référencé à l'intérieur du template (ou à l'intérieur d'un élément HTML rendu par Vue) via à la fois `<MyComponent>` et `<my-component>`. Cela nous permet d'utiliser le même code d'enregistrement de composant JavaScript quelle que soit la source du template.

---

---
url: /guide/extras/composition-api-faq.md
---

# FAQ sur la Composition API {#composition-api-faq}

:::tip
Cette FAQ part du principe que avez déjà une expérience avec Vue - en particulier, une expérience avec Vue 2, en utilisant principalement l'Options API.
:::

## Qu'est-ce que la Composition API ? {#what-is-composition-api}

La Composition API est un ensemble d'API qui nous permet de créer des composants Vue en utilisant des fonctions importées au lieu de déclarer des options. Il s'agit d'un terme générique rassemblant les API suivantes :

* [API de la réactivité](/api/reactivity-core), par exemple `ref()` et `reactive()`, qui nous permettent de créer directement un état réactif, un état calculé et des observateurs.

* [Les hooks du cycle de vie ](/api/composition-api-lifecycle), par exemple `onMounted()` et `onUnmounted()`, qui nous permettent de nous implanter dans le cycle de vie du composant.

* [Injection de dépendances](/api/composition-api-dependency-injection), c'est-à-dire `provide()` et `inject()`, qui nous permettent de tirer parti du système d'injection de dépendances de Vue tout en utilisant les API de la Réactivité.

La Composition API est une fonctionnalité intégrée de Vue 3 et [Vue 2.7](https://blog.vuejs.org/posts/vue-2-7-naruto.html). Pour les anciennes versions de Vue 2, utilisez le plugin [`@vue/composition-api`](https://github.com/vuejs/composition-api) maintenu par l'équipe officielle. Dans Vue 3, elle est principalement utilisée avec la syntaxe [`<script setup>`](/api/sfc-script-setup) dans les composants monofichiers. Voici un exemple de base d'un composant utilisant la Composition API :

```vue
<script setup>
import { ref, onMounted } from 'vue'

// état réactif
const count = ref(0)

// fonctions mutant l'état et déclenchant des mises à jour
function increment() {
  count.value++
}

// hooks du cycle de vie
onMounted(() => {
  console.log(`The initial count is ${count.value}.`)
})
</script>

<template>
  <button @click="increment">Count is: {{ count }}</button>
</template>
```

Malgré un style d'API basé sur la composition de fonctions, **la Composition API n'est PAS de la programmation fonctionnelle**. La Composition API est basée sur le paradigme de réactivité mutable et à grain fin de Vue, alors que la programmation fonctionnelle met l'accent sur l'immuabilité.

Si vous souhaitez apprendre à utiliser Vue avec la Composition API, vous pouvez définir la préférence API pour l'ensemble du site sur la Composition API à l'aide du bouton situé en haut de la barre latérale gauche, puis parcourir le guide depuis le début.

## Pourquoi la Composition API? {#why-composition-api}

### Une meilleure réutilisation de la logique {#better-logic-reuse}

Le principal avantage de la Composition API est qu'elle permet une réutilisation de la logique propre et efficace via des [fonctions composables](/guide/reusability/composables). Elle résout [tous les inconvénients des mixins](/guide/reusability/composables#vs-mixins), le principal mécanisme de réutilisation de la logique pour l'Options API.

La capacité de réutilisation de la logique de la Composition API a donné naissance à d'impressionnants projets communautaires tels que [VueUse](https://vueuse.org/), une collection toujours plus grande d'utilitaires composables. Elle sert également de mécanisme propre pour intégrer facilement des services ou des bibliothèques tiers possédant un état dans le système de réactivité de Vue, par exemple des [données persistantes](/guide/extras/reactivity-in-depth#immutable-data), [des machines d'état](/guide/extras/reactivity-in-depth#state-machines) et [RxJS](/guide/extras/reactivity-in-depth#rxjs).

### Une organisation du code plus flexible {#more-flexible-code-organization}

De nombreux utilisateurs apprécient le fait que nous écrivions du code qui est organisé par défaut avec l'Options API : chaque élément a sa place en fonction de l'option dont il relève. Cependant, l'Options API présente de sérieuses limitations lorsque la logique d'un seul composant dépasse un certain seuil de complexité. Cette limitation est particulièrement importante pour les composants qui doivent gérer de multiples **préoccupations logiques**, ce dont nous avons été les témoins directs dans de nombreuses applications Vue 2 en production.

Prenons l'exemple du composant explorateur de dossiers de l'interface graphique de Vue CLI : ce composant entraîne les préoccupations logiques suivantes :

* Traque de l'état actuel du dossier et affichage de son contenu
* Gestion de la navigation dans les dossiers (ouverture, fermeture, rafraîchissement...)
* Gestion de la création de nouveaux dossiers
* N'afficher seulement que les dossiers favoris
* Afficher les dossiers cachés
* Gestion des modifications du répertoire de travail actuel

La [version originale](https://github.com/vuejs/vue-cli/blob/a09407dd5b9f18ace7501ddb603b95e31d6d93c0/packages/@vue/cli-ui/src/components/folder/FolderExplorer.vue#L198-L404) du composant a été écrite en Options API. Si nous donnons à chaque ligne de code une couleur basée sur la préoccupation logique qu'elle entraîne, voici à quoi cela ressemble :

Remarquez comment le code s'occupant de la même préoccupation logique est obligé d'être divisé via différentes options, situées dans différentes parties du fichier. Dans un composant de plusieurs centaines de lignes, comprendre et naviguer dans une seule préoccupation logique nécessite de faire constamment défiler le fichier de haut en bas, ce qui rend la tâche beaucoup plus difficile qu'elle ne devrait l'être. En outre, si nous avons l'intention d'extraire une préoccupation logique dans un utilitaire réutilisable, il faut beaucoup de travail pour trouver et extraire les bons morceaux de code à partir de différentes parties du fichier.

Voici le même composant, avant et après la [refactorisation en Composition API](https://gist.github.com/yyx990803/8854f8f6a97631576c14b63c8acd8f2e) :

![folder component after](./images/composition-api-after.png)

Remarquez comment le code lié à la même préoccupation logique peut maintenant être regroupé : nous n'avons plus besoin de passer d'un bloc d'options à un autre lorsque nous travaillons sur une préoccupation logique spécifique. De plus, nous pouvons maintenant déplacer un groupe de code dans un fichier externe avec un effort moindre, puisque nous n'avons plus besoin de mélanger le code pour l'extraire. Cette réduction de la friction pour le remaniement est essentielle à la maintenabilité à long terme des grandes bases de code.

### Une meilleure inférence de type {#better-type-inference}

Ces dernières années, de plus en plus de développeurs frontend adoptent [TypeScript](https://www.typescriptlang.org/) car il nous aide à écrire un code plus robuste, à effectuer des modifications avec plus de confiance et à offrir une excellente expérience de développement grâce au support des environnements de développement. Cependant, l'Options API, a été initialement conçue en 2013 sans inférence de type. Nous avons dû mettre en œuvre une [gymnastique de type absurdement complexe](https://github.com/vuejs/core/blob/44b95276f5c086e1d88fa3c686a5f39eb5bb7821/packages/runtime-core/src/componentPublicInstance.ts#L132-L165) pour que l'inférence de type fonctionne avec l'Options API. Même avec tous ces efforts, l'inférence de type pour l'Options API peut encore causer des problèmes lors de l'utilisation des mixins et des injections de dépendances.

Cela avait conduit de nombreux développeurs qui voulaient utiliser Vue avec TS à se pencher sur l'API de classe alimentée par `vue-class-component`. Cependant, une API basée sur les classes s'appuie fortement sur les décorateurs ES, une fonctionnalité du langage qui n'était qu'une proposition de stade 2 lorsque Vue 3 était en cours de développement en 2019. Nous avons estimé qu'il était trop risqué de baser une API officielle sur une proposition instable. Depuis lors, la proposition de décorateurs a subi une autre révision complète, pour finalement atteindre le stade 3 en 2022. En outre, l'API basée sur les classes souffre de limitations de réutilisation de la logique et d'organisation similaires à celles de l'Options API.

À titre de comparaison, la Composition API utilise principalement des variables et des fonctions simples, qui sont naturellement adaptées aux types. Le code écrit dans la Composition API peut bénéficier d'une inférence de type complète, avec un faible besoin d'utiliser des indications de type manuelles. La plupart du temps, le code de la Composition API aura une apparence similaire en TypeScript et en JavaScript. Cela permet également aux utilisateurs de JavaScript ordinaire de bénéficier d'une inférence de type partielle.

### Un paquet de production réduit {#smaller-production-bundle-and-less-overhead}

Le code écrit en Composition API et `<script setup>` est également plus efficace et plus facile à compresser que son équivalent en Options API. En effet, le template d'un composant `<script setup>` est compilé en une fonction dans le même scope que le code `<script setup>`. Contrairement à l'accès aux propriétés à partir de `this`, le code du template compilé peut accéder directement aux variables déclarées à l'intérieur de `<script setup>`, sans proxy d'instance entre les deux. Cela conduit également à une meilleure compression, car tous les noms de variables peuvent être raccourcis en toute sécurité.

## Relations avec l'Options API {#relationship-with-options-api}

### Compromis {#trade-offs}

Certains utilisateurs passant de l'Options API à la Composition API ont trouvé leur code moins bien organisé, et en ont conclu que la Composition API était "moins bien" en termes d'organisation du code. Nous recommandons aux utilisateurs ayant une telle opinion de considérer ce problème sous un angle différent.

Il est vrai que la Composition API ne fournit plus les "garde-fous" qui vous guident pour placer votre code dans les emplacements adaptés. En contrepartie, vous pouvez écrire du code de composant comme vous le feriez avec du JavaScript normal. Cela signifie que **vous pouvez et devez appliquer toutes les meilleures pratiques d'organisation du code à votre code Composition API comme vous le feriez pour écrire du JavaScript normal**. Si vous pouvez écrire du JavaScript bien organisé, vous devriez également être en mesure d'écrire du code de même facture en Composition API.

L'Options API vous permet de "moins réfléchir" lorsque vous écrivez du code de composant, ce qui explique pourquoi de nombreux utilisateurs l'adorent. Toutefois, en réduisant la charge mentale, elle vous enferme également dans le modèle d'organisation du code prescrit sans échappatoire, ce qui peut rendre difficile la refactorisation ou l'amélioration de la qualité du code dans les projets à grande échelle. À cet égard, la Composition API offre une meilleure évolutivité à long terme.

### Est-ce que la Composition API couvre tous les cas d'utilisation ? {#does-composition-api-cover-all-use-cases}

Oui, en termes de logique avec état. Lorsque vous utilisez la Composition API, seules quelques options peuvent encore être nécessaires : `props`, `emits`, `name`, et `inheritAttrs`.

:::tip

Depuis la version 3.3, vous pouvez directement utiliser `defineOptions` dans `<script setup>` pour définir le nom du composant ou la propriété `inheritAttrs`

:::

Si vous avez l'intention d'utiliser exclusivement la Composition API (ainsi que les options énumérées ci-dessus), vous pouvez réduire de quelques kilobits votre paquet de production grâce à un [flag de compilation](/api/compile-time-flags) qui supprime le code lié à l'Options API de Vue. Notez que cela affecte également les composants Vue dans vos dépendances.

### Puis-je utiliser les deux API simultanément ? {#can-i-use-both-apis-together}

Oui. Vous pouvez utiliser la Composition API via l'option [`setup()`](/api/composition-api-setup) dans un composant en Options API.

Toutefois, nous vous recommandons de le faire que si vous disposez d'une base de code existante en Options API qui doit s'intégrer à de nouvelles fonctionnalités / bibliothèques externes écrites avec la Composition API.

### L'Options API va-t-elle être dépréciée ? {#will-options-api-be-deprecated}

Non, nous n'avons pas l'intention de le faire. L'Options API fait partie intégrante de Vue et c'est la raison pour laquelle de nombreux développeurs l'apprécient. Nous sommes également conscients que de nombreux avantages de la Composition API ne se manifestent que dans les projets à grande échelle, et l'Options API reste un choix solide pour de nombreux scénarios de complexité faible à moyenne.

## Relations avec la Class API {#relationship-with-class-api}

Nous ne recommandons plus l'utilisation de la Class API avec Vue 3, étant donné que la Composition API offre une excellente intégration de TypeScript avec des avantages supplémentaires en matière de réutilisation de la logique et d'organisation du code.

## Comparaison avec les hooks de React {#comparison-with-react-hooks}

La Composition API offre le même niveau de capacités de composition logique que les hooks de React, mais avec quelques différences importantes.

Les hooks React sont invoqués de manière répétée à chaque fois qu'un composant se met à jour. Cela crée un certain nombre de réserves qui peuvent dérouter même les développeurs React chevronnés. Cela conduit également à des problèmes d'optimisation des performances qui peuvent gravement affecter l'expérience de développement. Voici quelques exemples :

* Les hooks sont appelés dans un certain ordre et ne peuvent pas être conditionnels.

* Les variables déclarées dans un composant React peuvent être interceptées par un hook et devenir "périmées" si le développeur ne transmet pas correctement le tableau de dépendances. Cela conduit les développeurs React à s'appuyer sur les règles ESLint pour s'assurer que les dépendances correctes sont transmises. Cependant, la règle n'est souvent pas assez intelligente et sur-compense l'exactitude, ce qui entraîne une invalidation inutile et des maux de tête lorsque des cas limites sont rencontrées.

* Les calculs coûteux requièrent l'utilisation de `useMemo`, qui nécessite à nouveau de passer manuellement le bon tableau de dépendances.

* Les gestionnaires d'événements passés aux composants enfants provoquent par défaut des mises à jour inutiles des enfants, et nécessitent l'utilisation explicite de `useCallback` pour optimiser. Cela est presque toujours nécessaire, et nécessite à nouveau un tableau de dépendances correct. Négliger cela conduit à sur-rendre les applications par défaut et peut causer des problèmes de performance sans que l'on s'en rende compte.

* Le problème des fermetures périmées, combiné aux fonctionnalités concurrentes, rend difficile de repérer le moment où un morceau de code d'un hook est exécuté, et rend difficile de travailler avec un état mutable qui devrait persister à travers les rendus (via `useRef`).

> Note: certains des problèmes mentionnés ci-dessus liés à la mémoïsation peuvent être résolus par le prochain système de mémoïsation [React Compiler](https://react.dev/learn/react-compiler).

En comparaison, la Composition API de Vue :

* Appelle le code de `setup()` ou de `<script setup>` une seule fois. Cela permet au code de mieux s'aligner avec les intuitions d'une utilisation idiomatique de JavaScript, car il n'y a pas de fermetures périmées à craindre. Les appels de la Composition API ne sont pas non plus dans un ordre figé et peuvent être conditionnels.

* Le système de réactivité à l'exécution de Vue collecte automatiquement les dépendances réactives utilisées dans les propriétés calculées et les observateurs, de sorte qu'il n'est pas nécessaire de déclarer manuellement les dépendances.

* Il n'est pas nécessaire de mettre manuellement en cache les fonctions de rappel pour éviter les mises à jour inutiles des enfants. En général, le système de réactivité à grain fin de Vue garantit que les composants enfants ne sont mis à jour que lorsqu'ils en ont besoin. L'optimisation manuelle des mises à jour des enfants est rarement une préoccupation pour les développeurs Vue.

Nous reconnaissons la créativité des hooks de React, et c'est une source d'inspiration majeure pour la Composition API. Cependant, les problèmes mentionnés ci-dessus existent dans leur conception et nous avons remarqué que le modèle de réactivité de Vue fournit un moyen de les contourner.

---

---
url: /about/faq.md
---
# Foire aux questions {#frequently-asked-questions}

## Qui maintient Vue? {#who-maintains-vue}

Vue est un projet indépendant, piloté par la communauté. Il a été créé par [Evan You](https://x.com/youyuxi) en 2014 comme un projet personnel. Aujourd’hui, Vue est activement maintenu par [une équipe composée de membres à temps plein et de bénévoles du monde entier](/about/team), où Evan occupe le poste de chef de projet. Vous pouvez en apprendre davantage sur l'histoire de Vue dans ce [documentaire](https://www.youtube.com/watch?v=OrxmtDw4pVI).

Le développement de Vue est principalement financé par des sponsors et nous sommes financièrement viables depuis 2016. Si vous ou votre entreprise bénéficiez de Vue, envisagez de [nous sponsoriser](/sponsor/) pour soutenir son développement !

## Quelles sont les différences entre Vue 2 et Vue 3? {#what-s-the-difference-between-vue-2-and-vue-3}

Vue 3 est la dernière version majeure de Vue. Elle contient de nouvelles fonctionnalités qui ne sont pas présentes dans Vue 2, comme Teleport, Suspense, et la possibilité de combiner plusieurs éléments racines par template. Elle contient également des changements importants qui la rendent incompatible avec Vue 2. Tous les détails sont documentés dans le [Guide de migration vers Vue 3](https://v3-migration.vuejs.org/).

Malgré les différences, la majorité des API de Vue sont partagées entre les deux versions majeures, donc la plupart de vos connaissances de Vue 2 continueront à fonctionner dans Vue 3. Notamment, la Composition API était à l'origine une fonctionnalité réservée à Vue 3, mais elle a été intégrée à Vue 2 de façon rétroactive et est disponible avec [Vue 2.7](https://github.com/vuejs/vue/blob/main/CHANGELOG.md#270-2022-07-01).

En général, Vue 3 offre des paquets plus petits, de meilleures performances, une meilleure évolutivité et une meilleure prise en charge de TypeScript / intégration avec l'environnement de développement. Si vous démarrez un nouveau projet, Vue 3 est recommandé. Il n'y a que quelques raisons pour lesquelles vous pourriez considérer d'utiliser Vue 2 :

* Vous devez prendre en charge IE11. Vue 3 exploite les fonctionnalités JavaScript modernes et ne prend pas en charge IE11.

## Est-ce que Vue 2 est toujours maintenu ? {#is-vue-2-still-supported}

Si vous avez l'intention de migrer une application Vue 2 existante vers Vue 3, consultez le [guide de migration](https://v3-migration.vuejs.org/).

Vue 2.7, qui a été publiée en juillet 2022, est la dernière version mineure de Vue 2. Vue 2 est maintenant entré en mode maintenance : de nouvelles fonctionnalités ne seront plus publiées, mais Vue 2 continuera à recevoir des corrections de bugs critiques et des mises à jour de sécurité pendant 18 mois à partir de la date de sortie de la version 2.7. Cela signifie que **Vue 2 a atteint sa fin de vie le 31 décembre 2023**.

Nous pensons que cela devrait laisser suffisamment de temps à la majeure partie de l'écosystème pour migrer vers Vue 3. Cependant, nous comprenons également que certaines équipes ou certains projets ne peuvent pas effectuer la mise à niveau dans ce délai tout en devant répondre aux exigences de sécurité et de conformité. Nous nous associons à des experts du secteur pour fournir un support étendu pour Vue 2 aux équipes ayant de tels besoins. Si votre équipe prévoit d'utiliser Vue 2 au-delà de la fin de l'année 2023, assurez-vous d'anticiper et d'en savoir plus sur [Vue 2 Extended LTS](https://v2.vuejs.org/lts/).

## Sous quelle licence Vue est publié ? {#what-license-does-vue-use}

Vue est un projet libre et open source publié sous la [Licence MIT](https://opensource.org/licenses/MIT).

## Quels navigateurs supporte Vue ? {#what-browsers-does-vue-support}

La dernière version de Vue (3.x) ne prend en charge que les [navigateurs avec support ES2016 natif](https://caniuse.com/es2016). Cela exclut IE11. Vue 3.x utilise des fonctionnalités ES2016 qui ne peuvent pas recevoir de polyfills dans les anciens navigateurs, donc si vous avez besoin de prendre en charge les anciens navigateurs, vous devrez utiliser Vue 2.x à la place.

## Est-ce que Vue est fiable ? {#is-vue-reliable}

Vue est un framework mature et éprouvé. C'est l'un des frameworks JavaScript les plus utilisés en production aujourd’hui, avec plus de 1,5 million d'utilisateurs dans le monde, et il est téléchargé près de 10 millions de fois par mois sur npm.

Vue est utilisé en production par des organisations renommées dans le monde entier, notamment la Wikimedia Foundation, la NASA, Apple, Google, Microsoft, GitLab, Zoom, Tencent, Weibo, Bilibili, Kuaishou, et bien d'autres encore.

## Est-ce que Vue est rapide ? {#is-vue-fast}

Vue 3 est l'un des frameworks frontend grand public les plus performants, et gère la plupart des cas d'utilisation des applications web avec facilité, sans nécessiter d'optimisations manuelles.

Dans les scénarios de test de stress, Vue surpasse React et Angular avec une marge décente dans le [js-framework-benchmark](https://krausest.github.io/js-framework-benchmark/current.html). Il est également au coude à coude avec certains des frameworks sans DOM virtuel les plus rapides du benchmark.

Notez que les benchmarks synthétiques comme ceux présentés ci-dessus se concentrent sur les performances de rendu brutes avec des optimisations dédiées et peuvent ne pas être totalement représentatifs des résultats de performance du monde réel. Si vous vous intéressez davantage aux performances de chargement des pages, vous pouvez vérifier ce qui est avancé sur ce site à l'aide de [WebPageTest](https://www.webpagetest.org/lighthouse) ou de [PageSpeed Insights](https://pagespeed.web.dev/). Ce site est propulsé par Vue lui-même, avec un pré-rendu SSG, une hydratation complète de la page et une navigation côté client SPA. Il obtient un score de 100 en termes de performances sur un Moto G4 émulé avec une accélération du processeur de 4x sur des réseaux 4G lents.

Vous pouvez en savoir plus sur la façon dont Vue optimise automatiquement les performances d'exécution dans la section [Mécanismes de rendu](/guide/extras/rendering-mechanism), et sur la façon d'optimiser une application Vue dans des cas particulièrement exigeants dans le [Guide sur l'optimisation des performances](/guide/best-practices/performance).

## Est-ce que Vue est léger ? {#is-vue-lightweight}

Lorsque vous utilisez un outil de build, de nombreuses API de Vue peuvent être ["retirées de l'arbre"](https://developer.mozilla.org/fr/docs/Glossary/Tree_shaking). Par exemple, si vous n'utilisez pas le composant natif `<Transition>`, il ne sera pas inclus dans le paquet de production final.

Une application Vue "hello world" qui n'utilise que les API absolument nécessaires a une taille de base d'environ **16 Ko** seulement, après minification et compression Brotli. La taille réelle de l'application dépendra du nombre de fonctionnalités optionnelles que vous utilisez dans le framework. Dans le cas improbable où une application utilise toutes les fonctionnalités de Vue, la taille totale lors de l'exécution sera d'environ **27 Ko**.

Lorsque Vue est utilisé sans outil de build, non seulement nous perdons la possibilité d'alléger l'arbre, mais nous devons également envoyer le compilateur de templates au navigateur. Cela fait gonfler la taille à environ **41 Ko**. Par conséquent, si vous utilisez Vue principalement pour l'amélioration progressive sans outil de build, envisagez d'utiliser [petite-vue](https://github.com/vuejs/petite-vue) (seulement **6 Ko**) à la place.

Certains frameworks, comme Svelte, utilisent une stratégie de compilation qui produit un résultat extrêmement léger dans les scénarios à un seul composant. Cependant, [notre recherche](https://github.com/yyx990803/vue-svelte-size-analysis) montre que la différence de taille dépend fortement du nombre de composants dans l'application. Bien que Vue ait une taille de base plus importante, il génère moins de code par composant. Dans les scénarios réels, une application Vue peut très bien finir par être plus légère.

## Est-ce que Vue est scalable ? {#does-vue-scale}

Oui. Bien que l'on pense souvent à tort que Vue ne convient qu'aux cas d'utilisation simples, Vue est parfaitement capable de gérer des applications à grande échelle :

* Les [composants monofichiers](/guide/scaling-up/sfc) fournissent un modèle de développement modulaire qui permet de développer différentes parties d'une application de manière isolée.

* La [Composition API](/guide/reusability/composables) offre une intégration TypeScript de qualité et permet de créer des modèles propres pour organiser, extraire et réutiliser une logique complexe.

* [Le support complet des outils](/guide/scaling-up/tooling) garantit une expérience de développement fluide au fur et à mesure que l'application se développe.

* Une barrière à l'entrée moins élevée et une excellente documentation se traduisent par une intégration et une formation des nouveaux développeurs facilitées.

## Comment puis-je contribuer à Vue ? {#how-do-i-contribute-to-vue}

Merci pour votre intérêt ! Veuillez consulter notre [Guide de la communauté](/about/community-guide).

## Devrais-je plutôt utiliser l'Options API ou la Composition API ? {#should-i-use-options-api-or-composition-api}

Si vous ne connaissez pas Vue, nous vous proposons une comparaison de haut niveau entre les deux styles [ici](/guide/introduction#which-to-choose).

Si vous avez déjà utilisé l'Options API et que vous envisagez actuellement d'utiliser la Composition API, consultez [cette FAQ](/guide/extras/composition-api-faq).

## Devrais-je plutôt utiliser JavaScript ou TypeScript avec Vue ? {#should-i-use-javascript-or-typescript-with-vue}

Bien que Vue lui-même soit implémenté en TypeScript et fournisse une prise en charge de TypeScript de qualité, nous n'encourageons pas particulièrement l'utilisation de TypeScript ou de JavaScript.

La prise en charge de TypeScript est une considération importante lorsque de nouvelles fonctionnalités sont ajoutées à Vue. Les API conçues avec TypeScript en tête sont généralement plus faciles à comprendre pour les environnement de développement et les linters, même si vous n'utilisez pas TypeScript vous-même. Tout le monde y gagne. Les API de Vue sont également conçues pour fonctionner de la même manière en JavaScript et en TypeScript dans la mesure du possible.

L'adoption de TypeScript implique un compromis entre la complexité de l'intégration et les gains de maintenabilité à long terme. La justification d'un tel compromis peut varier en fonction des antécédents de votre équipe et de l'ampleur du projet, mais Vue n'est pas vraiment un facteur d'influence pour prendre cette décision.

## Comment Vue se compare-t-il aux Web Components ? {#how-does-vue-compare-to-web-components}

Vue a été créé avant que les Web Components ne soient disponibles de manière native, et certains aspects de la conception de Vue (par exemple, les slots) ont été inspirés par le modèle des Web Components.

Les spécifications des Web Components sont de relativement bas niveau, car elles sont centrées sur la définition d'éléments personnalisés. En tant que framework, Vue répond à des préoccupations supplémentaires de plus haut niveau, telles que le rendu efficace du DOM, la gestion réactive de l'état, les outils, le routage côté client et le rendu côté serveur.

Vue prend également en charge la consommation ou l'exportation vers des éléments personnalisés natifs. Consultez le [guide sur Vue et les Web Components](/guide/extras/web-components) pour plus de détails.

---

---
url: /guide/extras/render-function.md
---

# Fonctions de rendu et JSX {#render-functions-jsx}

Vue recommande d'utiliser des templates pour construire des applications dans la plupart des cas. Cependant, il existe des situations où nous avons besoin de toute la puissance programmatique de JavaScript. C'est alors que nous pouvons utiliser la fonction **render**.

> Si les concepts de DOM virtuel et de fonctions de rendu vous sont inconnus, lisez d'abord le chapitre [Mécanismes de rendu](/guide/extras/rendering-mechanism).

## Utilisation basique {#basic-usage}

### Créer des vnodes {#creating-vnodes}

Vue fournit une fonction `h()` afin de créer des nœuds virtuels, également appelés vnodes :

```js
import { h } from 'vue'

const vnode = h(
  'div', // type
  { id: 'foo', class: 'bar' }, // props
  [
    /* enfants */
  ]
)
```

`h()` est l'abréviation de **hyperscript** - ce qui signifie "JavaScript produisant du HTML (langage de balises pour l'hypertexte)". Ce nom est hérité de conventions partagées par de nombreuses implémentations du DOM virtuel. Un nom plus descriptif serait `createVNode()`, mais un nom plus court aide lorsque vous devez appeler cette fonction plusieurs fois dans une fonction de rendu.

La fonction `h()` est conçue pour être très flexible :

```js
// tous les arguments, sauf le type, sont facultatifs
h('div')
h('div', { id: 'foo' })

// les attributs et les propriétés peuvent être utilisés dans les props
// Vue choisit automatiquement la bonne façon de les assigner
h('div', { class: 'bar', innerHTML: 'hello' })

// des modificateurs de props tels que .prop et .attr peuvent être ajoutés
// via les préfixes '.' et `^' respectivement
h('div', { '.name': 'some-name', '^width': '100' })

// la classe et le style ont la même prise en charge pour la valeur d'objet / tableau
// qu'ils ont dans les templates
h('div', { class: [foo, { bar }], style: { color: 'red' } })

// les écouteurs d'événements doivent être passés suivant le format onXxx
h('div', { onClick: () => {} })

// les enfants peuvent être une chaîne de caractères
h('div', { id: 'foo' }, 'hello')

// les props peuvent être omises lorsqu'il n'y en a pas
h('div', 'hello')
h('div', [h('span', 'hello')])

// le tableau représentant les enfants peut contenir un mélange de vnodes et de chaînes de caractères.
h('div', ['hello', h('span', 'hello')])
```

Le vnode résultant a la forme suivante :

```js
const vnode = h('div', { id: 'foo' }, [])

vnode.type // 'div'
vnode.props // { id: 'foo' }
vnode.children // []
vnode.key // null
```

:::warning Remarque
L'interface complète `VNode` contient de nombreuses autres propriétés internes, mais il est fortement recommandé d'éviter de s'appuyer sur d'autres propriétés que celles listées ici. Cela permet d'éviter les ruptures involontaires en cas de modification des propriétés internes.
:::

### Déclarer des fonctions de rendu {#declaring-render-functions}

Lorsque vous utilisez des templates avec la Composition API, la valeur retournée par le hook `setup()` est utilisée pour exposer les données au template. Cependant, lors de l'utilisation de fonctions de rendu, nous pouvons retourner directement la fonction de rendu à la place :

```js
import { ref, h } from 'vue'

export default {
  props: {
    /* ... */
  },
  setup(props) {
    const count = ref(1)

    // retourne la fonction de rendu
    return () => h('div', props.msg + count.value)
  }
}
```

La fonction de rendu est déclarée à l'intérieur de `setup()`, elle a donc naturellement accès aux props et à tout état réactif déclaré dans la même portée.

En plus de retourner un seul vnode, vous pouvez également retourner des chaînes de caractères ou des tableaux :

```js
export default {
  setup() {
    return () => 'hello world!'
  }
}
```

```js
import { h } from 'vue'

export default {
  setup() {
    // utiliser un tableau pour retourner plusieurs nœuds racines
    return () => [h('div'), h('div'), h('div')]
  }
}
```

:::tip
Assurez-vous de retourner une fonction au lieu de retourner directement des valeurs ! La fonction `setup()` n'est appelée qu'une seule fois par composant, alors que la fonction de rendu retournée sera appelée plusieurs fois.
:::

Nous pouvons déclarer des fonctions de rendu en utilisant l'option `render` :

```js
import { h } from 'vue'

export default {
  data() {
    return {
      msg: 'hello'
    }
  },
  render() {
    return h('div', this.msg)
  }
}
```

La fonction `render()` a accès à l'instance du composant via `this`.

En plus de retourner un seul vnode, vous pouvez également retourner des chaînes de caractères ou des tableaux :

```js
export default {
  render() {
    return 'hello world!'
  }
}
```

```js
import { h } from 'vue'

export default {
  render() {
    // utiliser un tableau pour retourner plusieurs nœuds racines
    return [h('div'), h('div'), h('div')]
  }
}
```

Si un composant d'une fonction de rendu n'a pas besoin d'état d'instance, il peut également être déclaré directement comme une fonction pour des raisons de simplicité :

```js
function Hello() {
  return 'hello world!'
}
```

C'est exact, c'est un composant Vue valide ! Voir [les composants fonctionnels](#functional-components) pour plus de détails sur cette syntaxe.

### Les vnodes doivent être uniques {#vnodes-must-be-unique}

Tous les vnodes présents dans l'arbre des composants doivent être uniques. Cela signifie que la fonction de rendu suivante n'est pas valide :

```js
function render() {
  const p = h('p', 'hi')
  return h('div', [
    // Oups - duplication de vnodes!
    p,
    p
  ])
}
```

Si vous voulez vraiment dupliquer le même élément/composant, vous pouvez le faire via une fonction *factory*. Par exemple, la fonction de rendu suivante est un moyen parfaitement valable de rendre 20 paragraphes identiques :

```js
function render() {
  return h(
    'div',
    Array.from({ length: 20 }).map(() => {
      return h('p', 'hi')
    })
  )
}
```

### Using Vnodes in `<template>` {#using-vnodes-in-template}

```vue
<script setup>
import { h } from 'vue'

const vnode = h('button', ['Hello'])
</script>

<template>
  <!-- Via <component /> -->
  <component :is="vnode">Bonjour</component>

  <!-- Ou directement comme un élément -->
  <vnode />
  <vnode>Bonjour</vnode>
</template>
```

Un objet vnode a été déclaré dans `setup()`, vous pouvez l'utiliser comme un composant normal pour le rendu.

:::warning
Un vnode représente une sortie déjà rendu, pas une définition d'un composant. Utiliser un vnode dans le `<template>` ne crée pas une nouvelle instance de composant, mais le vnode sera rendu tel qu'il est.

Ce pattern doit être utilisé avec attention et n'est pas un remplaçant des composants normaux.
:::

## JSX / TSX {#jsx-tsx}

Le [JSX](https://facebook.github.io/jsx/) est une extension de JavaScript semblable au XML qui permet d'écrire du code de cette manière :

```jsx
const vnode = <div>hello</div>
```

Dans les expressions JSX, utilisez des accolades pour intégrer des valeurs dynamiques :

```jsx
const vnode = <div id={dynamicId}>hello, {userName}</div>
```

`create-vue` et Vue CLI possède tous deux des options pour élaborer des projets avec un support du JSX préconfiguré. Si vous configurez le JSX manuellement, veuillez consulter la documentation de [`@vue/babel-plugin-jsx`](https://github.com/vuejs/jsx-next) pour plus de détails.

Bien qu'il ait été introduit par React, le JSX n'a pas de sémantique d'exécution définie et peut être compilé en différents résultats. Si vous avez déjà travaillé avec le JSX, notez que **la transformation du JSX de Vue est différente de la transformation du JSX de React**, vous ne pouvez donc pas utiliser la transformation du JSX de React dans les applications Vue. Voici quelques différences notables par rapport au JSX de React :

* Vous pouvez utiliser des attributs HTML tels que `class` et `for` comme props - il n'est pas nécessaire d'utiliser `className` ou `htmlFor`.
* Passer des enfants à des composants (c'est-à-dire des slots) [fonctionne différemment](#passing-slots).

La définition de type de Vue fournit également une inférence de type pour l'utilisation de TSX. Lorsque vous utilisez TSX, assurez-vous de spécifier `"jsx": "preserve"` dans `tsconfig.json` afin que TypeScript laisse la syntaxe du JSX intacte pour le bon fonctionnement de la transformation du JSX par Vue.

### Inférence de type JSX {#jsx-type-inference}

De la même manière que pour la transformation, le JSX de Vue nécessite également des définitions de types différentes.

À partir de Vue 3.4, Vue n'inscrit plus implicitement `JSX` dans l'espace de noms global. Pour demander à TypeScript d'utiliser les définitions de type JSX de Vue, assurez-vous d'inclure ce qui suit dans votre `tsconfig.json`:

```json
{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "vue"
    // ...
  }
}
```

Vous pouvez également le définir dans un fichier en ajoutant un commentaire `/* @jsxImportSource vue */` en haut du fichier.

Si vous avez du code qui dépend de la présence de l'espace de noms global `JSX`, vous pouvez conserver le comportement global exact d'avant la version 3.4 en référençant explicitement `vue/jsx`, ce qui enregistre l'espace de noms global `JSX`.

## Exemples de fonctions de rendu {#render-function-recipes}

Nous vous proposons ci-dessous quelques exemples courants pour mettre en œuvre les fonctionnalités des templates via leur équivalent en fonctions de rendu / JSX.

### `v-if` {#v-if}

Template :

```vue-html
<div>
  <div v-if="ok">yes</div>
  <span v-else>no</span>
</div>
```

Équivalent en fonction de rendu / JSX :

```js
h('div', [ok.value ? h('div', 'yes') : h('span', 'no')])
```

```jsx
<div>{ok.value ? <div>yes</div> : <span>no</span>}</div>
```

```js
h('div', [this.ok ? h('div', 'yes') : h('span', 'no')])
```

```jsx
<div>{this.ok ? <div>yes</div> : <span>no</span>}</div>
```

### `v-for` {#v-for}

Template :

```vue-html
<ul>
  <li v-for="{ id, text } in items" :key="id">
    {{ text }}
  </li>
</ul>
```

Équivalent en fonction de rendu / JSX :

```js
h(
  'ul',
  // en supposant que `items` est une ref avec une valeur de tableau
  items.value.map(({ id, text }) => {
    return h('li', { key: id }, text)
  })
)
```

```jsx
<ul>
  {items.value.map(({ id, text }) => {
    return <li key={id}>{text}</li>
  })}
</ul>
```

```js
h(
  'ul',
  this.items.map(({ id, text }) => {
    return h('li', { key: id }, text)
  })
)
```

```jsx
<ul>
  {this.items.map(({ id, text }) => {
    return <li key={id}>{text}</li>
  })}
</ul>
```

### `v-on` {#v-on}

Les props dont le nom commence par `on` suivi d'une lettre majuscule sont traitées comme des écouteurs d'événements. Par exemple, `onClick` est l'équivalent de `@click` dans les templates.

```js
h(
  'button',
  {
    onClick(event) {
      /* ... */
    }
  },
  'Cliquez-moi'
)
```

```jsx
<button
  onClick={(event) => {
    /* ... */
  }}
>
  Cliquez-moi
</button>
```

#### Modificateurs d'événement {#event-modifiers}

Les modificateurs d'événements `.passive`, `.capture`, et `.once` peuvent être concaténés après le nom de l'événement en utilisant camelCase.

Par exemple :

```js
h('input', {
  onClickCapture() {
    /* écouteur d'événement en mode capture */
  },
  onKeyupOnce() {
    /* ne se déclenche qu'une seule fois */
  },
  onMouseoverOnceCapture() {
    /* once + capture */
  }
})
```

```jsx
<input
  onClickCapture={() => {}}
  onKeyupOnce={() => {}}
  onMouseoverOnceCapture={() => {}}
/>
```

Pour les autres modificateurs d'événements et de clés, l'utilitaire [`withModifiers`](/api/render-function#withmodifiers) peut être utilisé :

```js
import { withModifiers } from 'vue'

h('div', {
  onClick: withModifiers(() => {}, ['self'])
})
```

```jsx
<div onClick={withModifiers(() => {}, ['self'])} />
```

### Composants {#components}

Pour créer un vnode pour un composant, le premier argument passé à `h()` doit être la définition du composant. Cela signifie que lorsque vous utilisez les fonctions de rendu, il n'est pas nécessaire d'enregistrer les composants - vous pouvez utiliser directement les composants importés :

```js
import Foo from './Foo.vue'
import Bar from './Bar.jsx'

function render() {
  return h('div', [h(Foo), h(Bar)])
}
```

```jsx
function render() {
  return (
    <div>
      <Foo />
      <Bar />
    </div>
  )
}
```

Comme nous pouvons le constater, `h` peut fonctionner avec des composants importés depuis n'importe quel format de fichier tant qu'il s'agit d'un composant Vue valide.

Les composants dynamiques sont simples à utiliser avec les fonctions de rendu :

```js
import Foo from './Foo.vue'
import Bar from './Bar.jsx'

function render() {
  return ok.value ? h(Foo) : h(Bar)
}
```

```jsx
function render() {
  return ok.value ? <Foo /> : <Bar />
}
```

Si un composant est enregistré via son nom et ne peut pas être importé directement (par exemple, s'il est enregistré globalement par une bibliothèque), il peut être l'être en utilisant l'utilitaire [`resolveComponent()`](/api/render-function#resolvecomponent).

### Rendu de slots {#rendering-slots}

Dans les fonctions de rendu, les slots sont accessibles via le contexte `setup()`. Chaque slot de l'objet `slots` est une **fonction qui retourne un tableau de vnodes** :

```js
export default {
  props: ['message'],
  setup(props, { slots }) {
    return () => [
      // slot par défaut :
      // <div><slot /></div>
      h('div', slots.default()),

      // slot nommé :
      // <div><slot name="footer" :text="message" /></div>
      h(
        'div',
        slots.footer({
          text: props.message
        })
      )
    ]
  }
}
```

Équivalent en JSX :

```jsx
// par défaut
<div>{slots.default()}</div>

// nommé
<div>{slots.footer({ text: props.message })}</div>
```

Dans les fonctions de rendu, les slots sont accessibles via [`this.$slots`](/api/component-instance#slots) :

```js
export default {
  props: ['message'],
  render() {
    return [
      // <div><slot /></div>
      h('div', this.$slots.default()),

      // <div><slot name="footer" :text="message" /></div>
      h(
        'div',
        this.$slots.footer({
          text: this.message
        })
      )
    ]
  }
}
```

Équivalent en JSX :

```jsx
// <div><slot /></div>
<div>{this.$slots.default()}</div>

// <div><slot name="footer" :text="message" /></div>
<div>{this.$slots.footer({ text: this.message })}</div>
```

### Passer des slots {#passing-slots}

Passer des enfants à des composants et passer des enfants à des éléments ne fonctionnent pas de la même manière. Au lieu d'un tableau, nous devons passer soit une fonction slot, soit un objet de fonctions slot. Les fonctions slot peuvent retourner tout ce qu'une fonction de rendu normale peut renvoyer - ce qui est retourné sera toujours normalisé en tableaux de vnodes lors de leur appel dans le composant enfant.

```js
// simple slot par défaut
h(MyComponent, () => 'hello')

// slots nommés
// remarquez que `null` est requis afin d'éviter que
// l'objet de slots soit traité comme une prop
h(MyComponent, null, {
  default: () => 'default slot',
  foo: () => h('div', 'foo'),
  bar: () => [h('span', 'one'), h('span', 'two')]
})
```

Équivalent en JSX :

```jsx
// par défaut
<MyComponent>{() => 'hello'}</MyComponent>

// nommé
<MyComponent>{{
  default: () => 'default slot',
  foo: () => <div>foo</div>,
  bar: () => [<span>one</span>, <span>two</span>]
}}</MyComponent>
```

Passer des slots en tant que fonctions leur permet d'être invoqués à la volée par le composant enfant. Ainsi, les dépendances du slot sont traquées par l'enfant plutôt que par le parent, ce qui permet des mises à jour plus précises et plus efficaces.

### Slots Scopés {#scoped-slots}

Pour rendre un slot scopé dans le composant parent, un slot est passé au composant enfant. Remarquez que le slot a maintenant un paramètre `text`. Le slot sera appelé dans le composant enfant et les données du composant enfant seront transmises au composant parent.

```js
// parent component
export default {
  setup() {
    return () =>
      h(MyComp, null, {
        default: ({ text }) => h('p', text)
      })
  }
}
```

N'oubliez pas de passer `null` pour que les slots ne soient pas traités comme des props.

```js
// child component
export default {
  setup(props, { slots }) {
    const text = ref('hi')
    return () => h('div', null, slots.default({ text: text.value }))
  }
}
```

Équivalent JSX :

```jsx
<MyComponent>
  {{
    default: ({ text }) => <p>{text}</p>
  }}
</MyComponent>
```

### Composants natifs {#built-in-components}

[Les composants natifs](/api/built-in-components) tels que `<KeepAlive>`, `<Transition>`, `<TransitionGroup>`, `<Teleport>` et `<Suspense>` doivent être importés pour être utilisés dans les fonctions de rendu :

```js
import { h, KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'

export default {
  setup() {
    return () => h(Transition, { mode: 'out-in' } /* ... */)
  }
}
```

```js
import { h, KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'

export default {
  render() {
    return h(Transition, { mode: 'out-in' } /* ... */)
  }
}
```

### `v-model` {#v-model}

La directive `v-model` est enrichie par les props `modelValue` et `onUpdate:modelValue` lors de la compilation du template - nous devons fournir ces props nous-mêmes :

```js
export default {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  setup(props, { emit }) {
    return () =>
      h(SomeComponent, {
        modelValue: props.modelValue,
        'onUpdate:modelValue': (value) => emit('update:modelValue', value)
      })
  }
}
```

```js
export default {
  props: ['modelValue'],
  emits: ['update:modelValue'],
  render() {
    return h(SomeComponent, {
      modelValue: this.modelValue,
      'onUpdate:modelValue': (value) =>
        this.$emit('update:modelValue', value)
    })
  }
}
```

### Directives personnalisées {#custom-directives}

Les directives personnalisées peuvent être appliquées à un vnode en utilisant [`withDirectives`](/api/render-function#withdirectives) :

```js
import { h, withDirectives } from 'vue'

// une directive personnalisée
const pin = {
  mounted() {
    /* ... */
  },
  updated() {
    /* ... */
  }
}

// <div v-pin:top.animate="200"></div>
const vnode = withDirectives(h('div'), [
  [pin, 200, 'top', { animate: true }]
])
```

Si la directive est enregistrée par son nom et ne peut être importée directement, elle peut l'être en utilisant l'utilitaire [`resolveDirective`](/api/render-function#resolvedirective).

### Template Refs {#template-refs}

Avec la Composition API, les refs de template sont créées en transmettant le `ref()` lui-même en tant que props au vnode :

Avec la Composition API, lors de l'utilisation de [`useTemplateRef()`](/api/composition-api-helpers#usetemplateref)  les références des templates sont créées en passant la valeur de la chaîne en tant que prop au vnode :

```js
import { h, useTemplateRef } from 'vue'

export default {
  setup() {
    const divEl = useTemplateRef('my-div')

    // <div ref="my-div">
    return () => h('div', { ref: 'my-div' })
  }
}
```

Dans les versions antérieures à la 3.5 où useTemplateRef() n'a pas été introduite, les refs de templates sont créés en passant le ref() lui-même en tant que prop au vnode :

```js
import { h, ref } from 'vue'

export default {
  setup() {
    const divEl = ref()

    // <div ref="divEl">
    return () => h('div', { ref: divEl })
  }
}
```

Avec l'Options API, les ref de template sont créées en transmettant le nom de la référence sous forme de chaîne dans les props vnode :

```js
export default {
  render() {
    // <div ref="divEl">
    return h('div', { ref: 'divEl' })
  }
}
```

## Composants fonctionnels {#functional-components}

Les composants fonctionnels sont une autre forme de composants qui n'ont pas d'état propre. Ils agissent comme de pures fonctions : props en entrée, vnodes en sortie. Ils sont rendus sans créer d'instance de composant (c'est-à-dire sans `this`), et sans les hooks habituels du cycle de vie des composants.

Pour créer un composant fonctionnel, nous utilisons une simple fonction, plutôt qu'un objet d'options. La fonction est effectivement la fonction `render` du composant.

La signature d'un composant fonctionnel est la même que celle du hook `setup()` :

```js
function MyComponent(props, { slots, emit, attrs }) {
  // ...
}
```

Comme il n'y a pas de référence `this` pour un composant fonctionnel, Vue passera les `props` comme premier argument :

```js
function MyComponent(props, context) {
  // ...
}
```

Le deuxième argument, `context`, contient trois propriétés : `attrs`, `emit`, et `slots`. Elles sont équivalentes aux propriétés d'instance [`$attrs`](/api/component-instance#attrs), [`$emit`](/api/component-instance#emit), et [`$slots`](/api/component-instance#slots) respectivement.

La plupart des options de configuration habituelles des composants ne sont pas disponibles pour les composants fonctionnels. Cependant, il est possible de définir [`props`](/api/options-state#props) et [`emits`](/api/options-state#emits) en les ajoutant comme propriétés :

```js
MyComponent.props = ['value']
MyComponent.emits = ['click']
```

Si l'option `props` n'est pas spécifiée, alors l'objet `props` passé à la fonction contiendra tous les attributs, de la même manière que `attrs`. Les noms de prop ne seront pas formatés en camelCase, sauf si l'option `props` est spécifiée.

Pour les composants fonctionnels avec des `props` explicites, [la traversée des attributs](/guide/components/attrs) fonctionne à peu près comme pour les composants normaux. Cependant, pour les composants fonctionnels qui ne spécifient pas explicitement leurs `props`, seuls les écouteurs d'événements `class`, `style`, et `onXxx` seront hérités des `attrs` par défaut. Dans les deux cas, `inheritAttrs` peut être mis à `false` pour désactiver l'héritage des attributs :

```js
MyComponent.inheritAttrs = false
```

Les composants fonctionnels peuvent être enregistrés et consommés tout comme les composants normaux. Si vous passez une fonction comme premier argument à `h()`, elle sera traitée comme un composant fonctionnel.

### Typer des composants fonctionnels {#typing-functional-components}

Les composants fonctionnels peuvent être typés selon qu'ils sont nommés ou anonymes. [L'extension Vue - Official](https://github.com/vuejs/language-tools) prend également en charge la vérification de type des composants fonctionnels correctement typés lors de leur utilisation dans des templates SFC.

**Composants fonctionnels nommés**

```tsx
import type { SetupContext } from 'vue'
type FComponentProps = {
  message: string
}

type Events = {
  sendMessage(message: string): void
}

function FComponent(
  props: FComponentProps,
  context: SetupContext<Events>
) {
  return (
    <button onClick={() => context.emit('sendMessage', props.message)}>
      {props.message}{' '}
    </button>
  )
}

FComponent.props = {
  message: {
    type: String,
    required: true
  }
}

FComponent.emits = {
  sendMessage: (value: unknown) => typeof value === 'string'
}
```

**Composants fonctionnels anonymes**

```tsx
import type { FunctionalComponent } from 'vue'

type FComponentProps = {
  message: string
}

type Events = {
  sendMessage(message: string): void
}

const FComponent: FunctionalComponent<FComponentProps, Events> = (
  props,
  context
) => {
  return (
    <button onClick={() => context.emit('sendMessage', props.message)}>
        {props.message} {' '}
    </button>
  )
}

FComponent.props = {
  message: {
    type: String,
    required: true
  }
}

FComponent.emits = {
  sendMessage: (value) => typeof value === 'string'
}
```

---

---
url: /guide/essentials/reactivity-fundamentals.md
---

# Fondamentaux de la réactivité {#reactivity-fundamentals}

:::tip Préférence d'API
Cette page et de nombreux autres chapitres plus loin dans le guide contiennent un contenu différent pour l'Options API et la Composition API. Actuellement, votre préférence est l'Options APIla Composition API. Vous pouvez passer d'un style d'API à l'autre à l'aide des boutons "Préférence d'API" situés en haut de la barre latérale gauche.
:::

## Déclarer un état réactif \* {#declaring-reactive-state}

Avec l'Options API, nous utilisons l'option `data` pour déclarer l'état réactif d'un composant. La valeur de l'option doit être une fonction qui renvoie un objet. Vue appellera la fonction lors de la création d'une nouvelle instance de composant, et enveloppera l'objet retourné dans son système de réactivité. Toutes les propriétés de premier niveau de cet objet sont transmises à l'instance du composant (`this` dans les méthodes et dans les hooks du cycle de vie) :

```js{2-6}
export default {
  data() {
    return {
      count: 1
    }
  },

  // `mounted` est un hook du cycle de vie que nous aborderons plus tard
  mounted() {
    // `this` fait référence à l'instance du composant.
    console.log(this.count) // => 1

    // les données peuvent également être mutées
    this.count = 2
  }
}
```

[Essayer en ligne](https://play.vuejs.org/#eNpFUNFqhDAQ/JXBpzsoHu2j3B2U/oYPpnGtoetGkrW2iP/eRFsPApthd2Zndilex7H8mqioimu0wY16r4W+Rx8ULXVmYsVSC9AaNafz/gcC6RTkHwHWT6IVnne85rI+1ZLr5YJmyG1qG7gIA3Yd2R/LhN77T8y9sz1mwuyYkXazcQI2SiHz/7iP3VlQexeb5KKjEKEe2lPyMIxeSBROohqxVO4E6yV6ppL9xykTy83tOQvd7tnzoZtDwhrBO2GYNFloYWLyxrzPPOi44WWLWUt618txvASUhhRCKSHgbZt2scKy7HfCujGOqWL9BVfOgyI=)

Ces propriétés d'instance ne sont ajoutées que lors de la première création de l'instance, vous devez donc vous assurer qu'elles sont toutes présentes dans l'objet retourné par la fonction `data`. Si besoin, utilisez `null`, `undefined` ou une autre valeur temporaire pour les propriétés pour lesquelles la valeur souhaitée n'est pas encore disponible.

Vous pouvez ajouter une nouvelle propriété directement à `this` sans l'inclure dans `data`. Cependant, les propriétés ajoutées de cette manière ne pourront pas déclencher de mises à jour réactives.

Vue utilise un préfixe `$` lorsqu'il expose ses propres API natives via l'instance du composant. Il réserve également le préfixe `_` pour les propriétés internes. Il faut éviter d'utiliser des noms qui commencent par l'un de ces caractères pour les propriétés `data` à sa racine.

### Proxy réactif vs. original \* {#reactive-proxy-vs-original}

Dans Vue 3, les données sont rendues dynamiques en tirant parti des [proxys JavaScript](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Les utilisateurs venant de Vue 2 doivent être conscients du cas limite suivant :

```js
export default {
  data() {
    return {
      someObject: {}
    }
  },
  mounted() {
    const newObject = {}
    this.someObject = newObject

    console.log(newObject === this.someObject) // faux
  }
}
```

Lorsque vous accédez à `this.someObject` après lui avoir assigné une valeur, la valeur est un proxy réactif de l'objet d'origine `newObject`. **Contrairement à Vue 2, le `newObject` d'origine reste intact et ne sera pas rendu réactif : assurez-vous de toujours accéder à l'état réactif comme une propriété de `this`.**

## Déclarer un état réactif \*\* {#declaring-reactive-state-1}

### `ref()` \*\* {#ref}

Avec la Composition API, la méthode recommandée pour déclarer l'état réactif consiste à utiliser la fonction [`ref()`](/api/reactivity-core#ref) :

```js
import { ref } from 'vue'

const count = ref(0)
```

`ref()` prend l'argument et le renvoie enveloppé dans un objet ref avec une propriété `.value` :

```js
const count = ref(0)

console.log(count) // { value: 0 }
console.log(count.value) // 0

count.value++
console.log(count.value) // 1
```

> Voir aussi : [Typer les variables réactives](/guide/typescript/composition-api#typing-reactive)&#x20;

Pour utiliser un état réactif dans le template d'un composant, déclarez et renvoyez-le depuis la fonction `setup()` du composant :

```js{5,9-11}
import { ref } from 'vue'

export default {
  // `setup` est un hook spécial dédié à la Composition API.
  setup() {
    const count = ref(0)

    // expose l'état au template
    return {
      count
    }
  }
}
```

```vue-html
<div>{{ count }}</div>
```

Notez que nous n'avons **pas** besoin d'ajouter `.value` lors de l'utilisation de la ref dans le template. Pour plus de commodité, les refs sont automatiquement déballées lorsqu'elles sont utilisées dans des templates (avec quelques [pièges](#caveat-when-unwrapping-in-templates)).

Vous pouvez également muter une ref directement dans les gestionnaires d'événements :

```vue-html{1}
<button @click="count++">
  {{ count }}
</button>
```

Pour une logique plus complexe, nous pouvons déclarer des fonctions qui modifient les refs dans la même portée et les exposer en tant que méthodes à côté de l'état :

```js{7-10,15}
import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)

    function increment() {
      // .value est nécessaire en JavaScript
      count.value++
    }

    // n'oubliez pas d'également exposer la fonction.
    return {
      count,
      increment
    }
  }
}
```

Les méthodes exposées sont généralement utilisées comme écouteurs d'événements :

```vue-html{1}
<button @click="increment">
  {{ count }}
</button>
```

Voici l'exemple sur [Codepen](https://codepen.io/vuejs-examples/pen/WNYbaqo), sans utiliser d'outils de build.

### `<script setup>` \*\* {#script-setup}

Exposer manuellement l'état et les méthodes via `setup()` peut être verbeux. Heureusement, cela peut être évité avec l'utilisation de [composants monofichiers (SFC)](/guide/scaling-up/sfc). Nous pouvons simplifier l'utilisation avec `<script setup>` :

```vue{1}
<script setup>
import { ref } from 'vue'

const count = ref(0)

function increment() {
  count.value++
}
</script>

<template>
  <button @click="increment">
    {{ count }}
  </button>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNo9jUEKgzAQRa8yZKMiaNcllvYe2dgwQqiZhDhxE3L3jrW4/DPvv1/UK8Zhz6juSm82uciwIef4MOR8DImhQMIFKiwpeGgEbQwZsoE2BhsyMUwH0d66475ksuwCgSOb0CNx20ExBCc77POase8NVUN6PBdlSwKjj+vMKAlAvzOzWJ52dfYzGXXpjPoBAKX856uopDGeFfnq8XKp+gWq4FAi)

Les importations de premier niveau et les variables déclarées dans `<script setup>` sont automatiquement utilisables dans le template du même composant. Considérez le template comme une fonction JavaScript déclarée dans la même portée - il a naturellement accès à tout ce qui est déclaré à ses côtés.

:::tip
Pour le reste du guide, nous utiliserons principalement la syntaxe monofichier + `<script setup>` pour les exemples de code de la Composition API, car c'est l'utilisation la plus courante pour les développeurs Vue.

Si vous n'utilisez pas SFC, vous pouvez toujours utiliser la Composition API avec l'option [`setup()`](/api/composition-api-setup).
:::

### Pourquoi Refs ? \*\* {#why-refs}

Lorsque vous utilisez une ref dans un template et modifiez la valeur de la ref ultérieurement, Vue détecte automatiquement le changement et met à jour le DOM en conséquence. Ceci est possible grâce à un système de réactivité basé sur le suivi des dépendances. Lorsqu'un composant est rendu pour la première fois, Vue **trace** toutes les refs utilisées pendant le rendu. Plus tard, lorsqu'une ref est modifiée, elle **déclenche** un nouveau rendu pour les composants qui la suivent.

En JavaScript standard, il n'existe aucun moyen de détecter l'accès ou la mutation de variables simples. Cependant, il est possible d'intercepter les opérations get et set des propriétés d'un objet à l'aide des méthodes accesseur et mutateur.

La propriété `.value` donne à Vue la possibilité de détecter quand une ref a été consultée ou mutée. Sous le capot, Vue effectue le suivi dans son accesseur, et effectue le déclenchement dans son mutateur. Conceptuellement, vous pouvez considérer une ref comme un objet qui ressemble à ceci :

```js
// pseudo-code, pas la mise en œuvre effective
const myRef = {
  _value: 0,
  get value() {
    track()
    return this._value
  },
  set value(newValue) {
    this._value = newValue
    trigger()
  }
}
```

Une autre caractéristique intéressante des refs est que, contrairement aux variables ordinaires, vous pouvez passer des refs dans des fonctions tout en conservant l'accès à la dernière valeur et à la connexion de la réactivité. Cela s'avère particulièrement utile lors de la refonte d'une logique complexe en un code réutilisable.

Le système de réactivité est décrit plus en détail dans la section [La réactivité en détails](/guide/extras/reactivity-in-depth).

## Déclarer des méthodes \* {#declaring-methods}

Pour ajouter des méthodes à une instance d'un composant, nous utilisons l'option `methods`. Il doit s'agir d'un objet contenant les méthodes souhaitées :

```js{7-11}
export default {
  data() {
    return {
      count: 0
    }
  },
  methods: {
    increment() {
      this.count++
    }
  },
  mounted() {
    // les méthodes peuvent être appellées dans les hooks du cycle de vie, ou dans d'autres méthodes !
    this.increment()
  }
}
```

Vue lie automatiquement la valeur `this` pour `methods` afin qu'elle se réfère toujours à l'instance du composant. Cela garantit qu'une méthode conserve la bonne valeur `this` si elle est utilisée comme un écouteur d'événement ou comme une fonction de rappel. Vous devez éviter d'utiliser des fonctions fléchées lorsque vous définissez des méthodes, car cela empêche Vue de lier la valeur `this` appropriée :

```js
export default {
  methods: {
    increment: () => {
      // À éviter: pas d'accès à `this` ici!
    }
  }
}
```

Comme toutes les autres propriétés de l'instance du composant, les `méthodes` sont accessibles depuis le template du composant. Dans un template, elles sont le plus souvent utilisées comme des écouteurs d'événements :

```vue-html
<button @click="increment">{{ count }}</button>
```

[Essayer en ligne](https://play.vuejs.org/#eNplj9EKwyAMRX8l+LSx0e65uLL9hy+dZlTWqtg4BuK/z1baDgZicsPJgUR2d656B2QN45P02lErDH6c9QQKn10YCKIwAKqj7nAsPYBHCt6sCUDaYKiBS8lpLuk8/yNSb9XUrKg20uOIhnYXAPV6qhbF6fRvmOeodn6hfzwLKkx+vN5OyIFwdENHmBMAfwQia+AmBy1fV8E2gWBtjOUASInXBcxLvN4MLH0BCe1i4Q==)

Dans l'exemple ci-dessus, la méthode `increment` sera appelée lorsque l'on clique sur le `<button>`.

### Réactivité profonde {#deep-reactivity}

Dans Vue, l'état est profondément réactif par défaut. Cela signifie que vous pouvez vous attendre à ce que les changements soient détectés même lorsque vous modifiez des objets ou des tableaux imbriqués :

```js
export default {
  data() {
    return {
      obj: {
        nested: { count: 0 },
        arr: ['foo', 'bar']
      }
    }
  },
  methods: {
    mutateDeeply() {
      // cela va fonctionner comme prévu.
      this.obj.nested.count++
      this.obj.arr.push('baz')
    }
  }
}
```

Les refs peuvent contenir n'importe quel type de valeur, y compris des objets profondément imbriqués, des tableaux ou des structures de données JavaScript natives comme `Map`.

Une ref rendra sa valeur profondément réactive. Cela signifie que vous pouvez vous attendre à ce que les changements soient détectés même lorsque vous mutez des objets imbriqués ou des tableaux :

```js
import { ref } from 'vue'

const obj = ref({
  nested: { count: 0 },
  arr: ['foo', 'bar']
})

function mutateDeeply() {
  // cela va fonctionner comme prévu.
  obj.value.nested.count++
  obj.value.arr.push('baz')
}
```

Les valeurs non primitives sont transformées en proxies réactifs via [`reactive()`](#reactive), ce qui est expliqué ci-dessous.

Il est également possible de renoncer à la réactivité profonde avec [shallow refs](/api/reactivity-advanced#shallowref). Pour les refs peu profondes, seul l'accès à `.value` est suivi pour la réactivité. Les refs peu profondes peuvent être utilisées pour optimiser les performances en évitant le coût d'observation des gros objets, ou dans les cas où l'état interne est géré par une bibliothèque externe.

Pour en savoir plus :

* [Réduire la surcharge de réactivité pour les grandes structures immuables](/guide/best-practices/performance#reduce-reactivity-overhead-for-large-immutable-structures)
* [Intégration avec des systèmes externes de gestion d'état](/guide/extras/reactivity-in-depth#integration-with-external-state-systems)

### Timing de mise à jour du DOM {#dom-update-timing}

Lorsque vous modifiez un état réactif, le DOM est automatiquement mis à jour. Toutefois, il convient de noter que les mises à jour du DOM ne sont pas appliquées de manière synchrone. En effet, Vue les met en mémoire tampon jusqu'au prochain "tick" du cycle de mises à jour pour s'assurer que chaque composant ne soit mis à jour qu'une seule fois, quel que soit le nombre de modifications d'état que vous avez effectuées.

Pour attendre que la mise à jour du DOM soit terminée après un changement d'état, vous pouvez utiliser l'API globale [nextTick()](/api/general#nexttick) :

```js
import { nextTick } from 'vue'

async function increment() {
  count.value++
  await nextTick()
  // Maintenant le DOM est mis à jour
}
```

```js
import { nextTick } from 'vue'

export default {
  methods: {
    async increment() {
      this.count++
      await nextTick()
      // Maintenant le DOM est mis à jour
    }
  }
}
```

## `reactive()` \*\* {#reactive}

Il existe une autre façon de déclarer un état réactif, avec l'API `reactive()`. Contrairement à une ref qui enveloppe la valeur interne dans un objet spécial, `reactive()` rend un objet lui-même réactif :

```js
import { reactive } from 'vue'

const state = reactive({ count: 0 })
```

> Voir aussi : [Typer reactive()](/guide/typescript/composition-api#typing-reactive)&#x20;

Utilisation dans le template :

```vue-html
<button @click="state.count++">
  {{ state.count }}
</button>
```

Les objets réactifs sont des [proxys JavaScript](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Proxy) et se comportent comme des objets classiques. La différence est que Vue est capable de traquer l'accès aux propriétés et les mutations d'un objet réactif.

`reactive()` convertit l'objet en profondeur : les objets imbriqués sont également enveloppés par `reactive()` lorsqu'on y accède. Il est également appelé par `ref()` en interne lorsque la valeur de ref est un objet. Comme pour les refs peu profondes, il existe aussi l'API [`shallowReactive()`](/api/reactivity-advanced#shallowreactive) pour choisir de ne pas utiliser la réactivité profonde.

### Proxy réactif vs. original \*\* {#reactive-proxy-vs-original-1}

Il est important de noter que la valeur retournée par `reactive()` est un [proxy](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Proxy) de l'objet original, qui n'est pas égal à l'objet original :

```js
const raw = {}
const proxy = reactive(raw)

// le proxy n'est PAS égal à l'original.
console.log(proxy === raw) // faux
```

Seul le proxy est réactif - muter l'objet original ne déclenchera pas de mises à jour. Par conséquent, la meilleure pratique pour travailler avec le système de réactivité de Vue est d'utiliser **exclusivement les versions proxifiées de votre état**.

Pour assurer un accès cohérent au proxy, appeler `reactive()` sur le même objet retournera toujours le même proxy, et appeler `reactive()` sur un proxy existant retournera également ce même proxy :

```js
// appeler reactive() sur le même objet retourne le même proxy
console.log(reactive(raw) === proxy) // true

// appeler reactive() sur un proxy se retourne lui-même
console.log(reactive(proxy) === proxy) // vrai
```

Cette règle s'applique tout aussi bien aux objets imbriqués. En raison de la réactivité profonde, les objets imbriqués à l'intérieur d'un objet réactif sont également des proxys :

```js
const proxy = reactive({})

const raw = {}
proxy.nested = raw

console.log(proxy.nested === raw) // false
```

### Limitations de `reactive()` \*\* {#limitations-of-reactive}

L'API `reactive()` a quelques limitations :

1. **Types limités :** Elle ne fonctionne que pour les types d'objets (objets, tableaux et [objets de type collections](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects#collections_indexées) tels que `Map` et `Set`). Elle ne peut pas contenir les [types primitifs](https://developer.mozilla.org/fr/docs/Glossary/Primitive) tels que `string`, `number` ou `boolean`.

2. **Remplacement impossible de l'intégralité de l'objet :** Comme le suivi de la réactivité de Vue fonctionne sur l'accès aux propriétés, nous devons toujours conserver la même référence à l'objet réactif. Cela signifie que nous ne pouvons pas facilement "remplacer" un objet réactif car la connexion de réactivité à la première référence serait perdue :

   ```js
   let state = reactive({ count: 0 })

   // la référence précédente ({ count: 0 }) n'est plus suivie
   // (la connexion de réactivité est perdue !)
   state = reactive({ count: 1 })
   ```

3. **Ne fonctionne pas avec la destructuration :** lorsque nous déstructurons la propriété de type primitif d'un objet réactif en variables locales, ou lorsque nous passons cette propriété dans une fonction, nous perdons la connexion à la réactivité :

   ```js
   const state = reactive({ count: 0 })

   // count est déconnecté de state.count lorsqu'il est déstructuré.
   let { count } = state
   // n'affecte pas l'état original
   count++

   // la fonction reçoit un simple nombre et
   // ne sera pas capable de traquer les changements de state.count
   // nous devons passer l'objet entier pour conserver la réactivité
   callSomeFunction(state.count)
   ```

À cause de ces limites, nous recommandons l'usage de `ref()` en tant qu'API principale pour déclarer un état réactif.

### En tant que propriété d'un objet réactif \*\* {#ref-unwrapping-as-reactive-object-property}

Une ref est automatiquement déballée lorsqu'elle est accédée ou mutée en tant que propriété d'un objet réactif. En d'autres termes, elle se comporte comme une propriété normale :

```js
const count = ref(0)
const state = reactive({
  count
})

console.log(state.count) // 0

state.count = 1
console.log(count.value) // 1
```

Si une nouvelle ref est attribuée à une propriété liée à une ref existante, elle remplacera l'ancienne ref :

```js
const otherCount = ref(2)

state.count = otherCount
console.log(state.count) // 2
// la ref originale est maintenant déconnectée de state.count
console.log(count.value) // 1
```

Le déballage de ref ne se produit que lorsqu'elle est imbriquée dans un objet réactif profond. Il ne s'applique pas lorsqu'elle est accédée en tant que propriété d'une [shallowReactive](/api/reactivity-advanced#shallowreactive).

### Pièges lors de déballage de tableaux et collections \*\* {#caveat-in-arrays-and-collections}

Contrairement aux objets réactifs, il n'y a **pas** de déballage effectué lorsque la ref est accédée en tant qu'élément d'un tableau réactif ou d'un type de collection natif comme `Map` :

```js
const books = reactive([ref('Vue 3 Guide')])
// il faut ici .value
console.log(books[0].value)

const map = reactive(new Map([['count', ref(0)]]))
// il faut ici .value
console.log(map.get('count').value)
```

### Pièges lors de déballage dans les templates \*\* {#caveat-when-unwrapping-in-templates}

Le déballage de ref dans les templates ne s'applique que si la ref est une propriété de premier niveau dans le contexte de rendu du template.

Dans l'exemple ci-dessous, `count` et `object` sont des propriétés de premier niveau, mais `object.id` ne l'est pas :

```js
const count = ref(0)
const object = { id: ref(1) }
```

Cette expression fonctionne donc comme prévu :

```vue-html
{{ count + 1 }}
```

...alors que celui-ci ne le fait **PAS** :

```vue-html
{{ object.id + 1 }}
```

Le résultat rendu sera `[object Object]1` car `object.id` n'est pas déballé lors de l'évaluation de l'expression et reste un objet ref. Pour résoudre ce problème, nous pouvons déstructurer `id` en une propriété de premier niveau :

```js
const { id } = object
```

```vue-html
{{ id + 1 }}
```

Désormais le résultat rendu sera `2`.

Une autre chose à noter est qu'une ref est déballée s'il s'agit de la valeur finale évaluée d'une interpolation de texte (c'est-à-dire une balise {{ }}), donc ce qui suit rendra `1` :

```vue-html
{{ object.id }}
```

Il s'agit d'une fonctionnalité de commodité de l'interpolation de texte et est équivalent à {{ object.id.value }}.

### Méthodes avec état \* {#stateful-methods}

Dans certains cas, nous pouvons avoir besoin de créer dynamiquement une méthode, par exemple en créant un gestionnaire d'événements *debounced* :

```js
import { debounce } from 'lodash-es'

export default {
  methods: {
    // Debounce avec Lodash
    click: debounce(function () {
      // ... répond au clic ...
    }, 500)
  }
}
```

Toutefois, cette approche est problématique pour les composants réutilisés, car une fonction debounced possède un **état** : elle maintient un état interne sur le temps écoulé. Si plusieurs instances de composants partagent la même fonction debounced, elles interféreront les unes avec les autres.

Pour que la fonction debounced de chaque instance de composant soit indépendante des autres, nous pouvons créer la version debounced dans le hook de cycle de vie `created` :

```js
export default {
  created() {
    // chaque instance a maintenant sa propre copie du gestionnaire debounced
    this.debouncedClick = _.debounce(this.click, 500)
  },
  unmounted() {
    // c'est aussi une bonne idée d'annuler le minuteur
    // lorsque le composant est supprimé
    this.debouncedClick.cancel()
  },
  methods: {
    click() {
      // ... répond au clic ...
    }
  }
}
```

---

---
url: /guide/scaling-up/state-management.md
---
# Gestion d'état {#state-management}

## Qu'est-ce que la gestion d'état ? {#what-is-state-management}

Techniquement, chaque instance de composant Vue "gère" déjà son propre état réactif. Prenons l'exemple d'un simple composant compteur :

```vue
<script setup>
import { ref } from 'vue'

// état
const count = ref(0)

// actions
function increment() {
  count.value++
}
</script>

<!-- vue -->
<template>{{ count }}</template>
```

```vue
<script>
export default {
  // état
  data() {
    return {
      count: 0
    }
  },
  // actions
  methods: {
    increment() {
      this.count++
    }
  }
}
</script>

<!-- vue -->
<template>{{ count }}</template>
```

Il s'agit d'une unité autonome composée de la manière suivante :

* L'**état**, la source de vérité qui dirige notre application;
* La **vue**, une cartographie déclarative de l'**état**;
* Les **actions**, les différentes manières dont l'état pourrait changer, en réaction aux entrées de l'utilisateur dans la **vue**.

C'est une représentation simple du concept de "flux de données à sens unique" :

Toutefois, la simplicité commence à disparaître lorsque nous avons **plusieurs composants qui partagent un état commun** :

1. Plusieurs vues peuvent dépendre de la même partie d'un état.
2. Les actions de différentes vues peuvent avoir besoin de muter la même partie d'un état.

Dans le premier cas, une solution possible consiste à "élever" l'état partagé jusqu'à un composant ancêtre commun, puis à le transmettre en tant que props. Cependant, cela devient rapidement fastidieux dans les arbres de composants avec des hiérarchies profondes, conduisant à un autre problème connu sous le nom de [Prop Drilling](/guide/components/provide-inject#prop-drilling).

Dans le deuxième cas, nous nous retrouvons souvent à utiliser des solutions telles que l'atteinte d'instances directes parent/enfant par le biais des refs de template, ou à essayer de modifier et de synchroniser plusieurs copies de l'état par le biais d'événements émis. Ces deux modèles sont fragiles et conduisent rapidement à un code non maintenable.

Une solution plus simple et plus directe consiste à extraire l'état partagé des composants, et à le gérer dans un singleton global. Ainsi, notre arbre de composants devient une grande "vue", et n'importe quel composant peut accéder à l'état ou déclencher des actions, peu importe où il se trouve dans l'arbre !

## Gestion d'état simple avec l'API de réactivité {#simple-state-management-with-reactivity-api}

Dans l'Options API, les données réactives sont déclarées via l'option `data()`. En interne, l'objet renvoyé par `data()` est rendu réactif via la fonction [`reactive()`](/api/reactivity-core#reactive), qui est également disponible en tant qu'API publique.

Si vous avez un élément d'état qui doit être partagé par plusieurs instances, vous pouvez utiliser [`reactive()`](/api/reactivity-core#reactive) pour créer un objet réactif, puis l'importer dans plusieurs composants :

```js [store.js]
import { reactive } from 'vue'

export const store = reactive({
  count: 0
})
```

```vue [ComponentA.vue]
<script setup>
import { store } from './store.js'
</script>

<template>From A: {{ store.count }}</template>
```

```vue [ComponentB.vue]
<script setup>
import { store } from './store.js'
</script>

<template>From B: {{ store.count }}</template>
```

```vue [ComponentA.vue]
<script>
import { store } from './store.js'

export default {
  data() {
    return {
      store
    }
  }
}
</script>

<template>From A: {{ store.count }}</template>
```

```vue [ComponentB.vue]
<script>
import { store } from './store.js'

export default {
  data() {
    return {
      store
    }
  }
}
</script>

<template>From B: {{ store.count }}</template>
```

Maintenant, chaque fois que l'objet `store` est modifié, `<ComposantA>` et `<ComposantB>` mettront à jour leur vue automatiquement - nous avons désormais une seule source de vérité.

Cependant, cela signifie également que n'importe quel composant important `store` peut le modifier comme il le souhaite :

```vue-html{2}
<template>
  <button @click="store.count++">
    From B: {{ store.count }}
  </button>
</template>
```

Bien que cela fonctionne dans des cas simples, un état global qui peut être arbitrairement modifié par n'importe quel composant ne sera pas très facile à maintenir à long terme. Pour s'assurer que la logique de modification de l'état soit centralisée comme l'état lui-même, il est recommandé de définir des méthodes sur le store avec des noms qui expriment l'intention des actions :

```js{5-7} [store.js]
import { reactive } from 'vue'

export const store = reactive({
  count: 0,
  increment() {
    this.count++
  }
})
```

```vue-html{2}
<template>
  <button @click="store.increment()">
    From B: {{ store.count }}
  </button>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNrNkk1uwyAQha8yYpNEiUzXllPVrtRTeJNSqtLGgGBsVbK4ewdwnT9FWWSTFczwmPc+xMhqa4uhl6xklRdOWQQvsbfPrVadNQ7h1dCqpcYaPp3pYFHwQyteXVxKm0tpM0krnm3IgAqUnd3vUFIFUB1Z8bNOkzoVny+wDTuNcZ1gBI/GSQhzqlQX3/5Gng81pA1t33tEo+FF7JX42bYsT1BaONlRguWqZZMU4C261CWMk3EhTK8RQphm8Twse/BscoUsvdqDkTX3kP3nI6aZwcmdQDUcMPJPabX8TQphtCf0RLqd1csxuqQAJTxtYnEUGtIpAH4pn1Ou17FDScOKhT+QNAVM)

[Essayer en ligne](https://play.vuejs.org/#eNrdU8FqhDAU/JVHLruyi+lZ3FIt9Cu82JilaTWR5CkF8d8bE5O1u1so9FYQzAyTvJnRTKTo+3QcOMlIbpgWPT5WUnS90gjPyr4ll1jAWasOdim9UMum3a20vJWWqxSgkvzTyRt+rocWYVpYFoQm8wRsJh+viHLBcyXtk9No2ALkXd/WyC0CyDfW6RVTOiancQM5ku+x7nUxgUGlOcwxn8Ppu7HJ7udqaqz3SYikOQ5aBgT+OA9slt9kasToFnb5OiAqCU+sFezjVBHvRUimeWdT7JOKrFKAl8VvYatdI6RMDRJhdlPtWdQf5mdQP+SHdtyX/IftlH9pJyS1vcQ2NK8ZivFSiL8BsQmmpMG1s1NU79frYA1k8OD+/I3pUA6+CeNdHg6hmoTMX9pPSnk=)

:::tip
Notez que le gestionnaire de clic utilise `store.increment()` avec des parenthèses - cela est nécessaire pour appeler la méthode avec le contexte `this` adapté puisqu'il ne s'agit pas d'une méthode de composant.
:::

Bien que nous utilisions ici un seul objet réactif en guise de store, vous pouvez également partager un état réactif créé à l'aide d'autres [API de réactivité](/api/reactivity-core) telles que `ref()` ou `computed()`, ou même renvoyer un état global à partir d'un [Composable](/guide/reusability/composables) :

```js
import { ref } from 'vue'

// état global, créé dans la portée du module
const globalCount = ref(1)

export function useCount() {
  // état local, créé composant par composant
  const localCount = ref(1)

  return {
    globalCount,
    localCount
  }
}
```

Le fait que le système de réactivité de Vue soit découplé du modèle de composants le rend extrêmement flexible.

## Considérations relatives au SSR {#ssr-considerations}

Si vous construisez une application qui utilise le [Server-Side Rendering (SSR)](./ssr), le modèle ci-dessus peut entraîner des problèmes car le store est un singleton partagé entre plusieurs requêtes. Ce problème est abordé avec [plus de détails](./ssr#cross-request-state-pollution) dans le guide SSR.

## Pinia {#pinia}

Si notre solution de gestion d'état à la main suffit dans les scénarios simples, il y a beaucoup plus d'éléments à prendre en compte dans les applications de production à grande échelle :

* Des conventions plus solides pour la collaboration en équipe
* L'intégration avec les Vue DevTools, y compris la timeline, l'inspection des composants et le débogage par voyage dans le temps.
* Remplacement de module à chaud
* Prise en charge du rendu côté serveur

[Pinia](https://pinia.vuejs.org) est une bibliothèque de gestion d'état qui implémente tout ce qui précède. Elle est maintenue par l'équipe principale de Vue, et fonctionne à la fois avec Vue 2 et Vue 3.

Les utilisateurs actuels connaissent peut-être [Vuex](https://vuex.vuejs.org/), l'ancienne bibliothèque officielle de gestion d'état pour Vue. Pinia jouant le même rôle dans l'écosystème, Vuex est désormais en mode maintenance. Elle fonctionne toujours, mais ne proposera plus de nouvelles fonctionnalités. Il est recommandé d'utiliser Pinia pour les nouvelles applications.

Pinia a commencé comme une exploration de ce à quoi pourrait ressembler la prochaine itération de Vuex, incorporant de nombreuses idées issues des discussions de l'équipe centrale pour Vuex 5. Finalement, nous avons réalisé que Pinia implémentait déjà la plupart de ce que nous voulions dans Vuex 5, et donc nous avons finalement décidé d'en faire la nouvelle recommandation.

Par rapport à Vuex, Pinia offre une API plus simple avec moins de fioritures, propose des API de type Composition-API et, surtout, dispose d'une solide prise en charge de l'inférence de type lorsqu'elle est utilisée avec TypeScript.

---

---
url: /guide/essentials/event-handling.md
---
# Gestion d'événement {#event-handling}

## Écouter des événements {#listening-to-events}

Nous pouvons utiliser la directive `v-on`, que nous raccourcissons généralement par le symbole `@`, pour écouter les événements DOM et exécuter du JavaScript lorsqu'ils sont déclenchés. L'utilisation serait alors `v-on:click="handler"` ou avec le raccourci, `@click="handler"`.

La valeur du gestionnaire peut alors prendre l'une des formes suivantes :

1. **Gestionnaires en ligne :** Du JavaScript inline qui sera exécuté lorsque l'événement sera déclenché (similaire à l'attribut natif `onclick`).

2. **Méthodes gestionnaires :** Un nom ou un chemin de propriété qui pointe vers une méthode définie sur le composant.

## Gestionnaires en ligne {#inline-handlers}

Les gestionnaires inline sont généralement utilisés dans des cas simples, par exemple :

```js
const count = ref(0)
```

```js
data() {
  return {
    count: 0
  }
}
```

```vue-html
<button @click="count++">Add 1</button>
<p>Count is: {{ count }}</p>
```

[Essayer en ligne](https://play.vuejs.org/#eNo9jssKgzAURH/lko0tgrbbEqX+Q5fZaLxiqHmQ3LgJ+fdqFZcD58xMYp1z1RqRvRgP0itHEJCia4VR2llPkMDjBBkmbzUUG1oII4y0JhBIGw2hh2Znbo+7MLw+WjZ/C4TaLT3hnogPkcgaeMtFyW8j2GmXpWBtN47w5PWBHLhrPzPCKfWDXRHmPsCAaOBfgSOkdH3IGUhpDBWv9/e8vsZZ/gFFhFJN)

[Essayer en ligne](https://play.vuejs.org/#eNo9jcEKgzAQRH9lyKlF0PYqqdR/6DGXaLYo1RjiRgrivzepIizLzu7sm1XUzuVLIFEKObe+d1wpS183eYahtw4DY1UWMJr15ZpmxYAnDt7uF0BxOwXL5Evc0kbxlmyxxZLFyY2CaXSDZkqKZROYJ4tnO/Tt56HEgckyJaraGNxlsVt2u6teHeF40s20EDo9oyGy+CPIYF1xULBt4H6kOZeFiwBZnOFi+wH0B1hk)

## Méthodes gestionnaires {#method-handlers}

Cependant, pour de nombreux gestionnaires d'événements, la logique sera plus complexe et ne sera probablement pas réalisable avec des gestionnaires en ligne. C'est pourquoi `v-on` peut également accepter le nom ou le chemin d'une méthode de composant que vous souhaitez appeler.

Par exemple :

```js
const name = ref('Vue.js')

function greet(event) {
  alert(`Hello ${name.value}!`)
  // `event` est l'événement natif du DOM
  if (event) {
    alert(event.target.tagName)
  }
}
```

```js
data() {
  return {
    name: 'Vue.js'
  }
},
methods: {
  greet(event) {
    // `this` à l'intérieur des méthodes pointe sur l'instance actuellement active
    alert(`Hello ${this.name}!`)
    // `event` est l'événement natif du DOM
    if (event) {
      alert(event.target.tagName)
    }
  }
}
```

```vue-html
<!-- `greet` est le nom de la méthode définie plus haut -->
<button @click="greet">Greet</button>
```

[Essayer en ligne](https://play.vuejs.org/#eNpVj0FLxDAQhf/KMwjtXtq7dBcFQS/qzVMOrWFao2kSkkkvpf/dJIuCEBgm771vZnbx4H23JRJ3YogqaM+IxMlfpNWrd4GxI9CMA3NwK5psbaSVVjkbGXZaCediaJv3RN1XbE5FnZNVrJ3FEoi4pY0sn7BLC0yGArfjMxnjcLsXQrdNJtFxM+Ys0PcYa2CEjuBPylNYb4THtxdUobj0jH/YX3D963gKC5WyvGZ+xR7S5jf01yPzeblhWr2ZmErHw0dizivfK6PV91mKursUl6dSh/4qZ+vQ/+XE8QODonDi)

[Essayer en ligne](https://play.vuejs.org/#eNplUE1LxDAQ/StjEbYL0t5LXRQEvag3Tz00prNtNE1CMilC6X83SUkRhJDJfLz3Jm8tHo2pFo9FU7SOW2Ho0in8MdoSDHhlXhKsnQIYGLHyvL8BLJK3KmcAis3YwOnDY/XlTnt1i2G7i/eMNOnBNRkwWkQqcUFFByVAXUNPk3A9COXEgBkGRgtFDkgDTQjcWxuAwDiJBeMsMcUxszCJlsr+BaXUcLtGwiqut930579KST1IBd5Aqlgie3p/hdTIk+IK//bMGqleEbMjxjC+BZVDIv0+m9CpcNr6MDgkhLORjDBm1H56Iq3ggUvBv++7IhnUFZfnGNt6b4fRtj5wxfYL9p+Sjw==)

Une méthode gestionnaire reçoit automatiquement l'objet événement natif du DOM qui la déclenche - dans l'exemple ci-dessus, nous pouvons accéder à l'élément qui envoie l'événement via `event.target`.

Voir aussi : [Typer les gestionnaires d'événements](/guide/typescript/composition-api#typing-event-handlers)&#x20;

Voir aussi : [Typing Event Handlers](/guide/typescript/options-api#typing-event-handlers)&#x20;

### Méthodes vs. Détection en ligne {#method-vs-inline-detection}

Le compilateur de templates détecte les méthodes gestionnaires en vérifiant si la valeur en chaîne de caractères `v-on` est un identifiant JavaScript ou un chemin d'accès de propriété valide. Par exemple, `foo`, `foo.bar` et `foo['bar']` sont traités comme des méthodes gestionnaires, tandis que `foo()` et `count++` sont traités comme des gestionnaires en ligne.

## Appeler des méthodes dans les gestionnaires en ligne {#calling-methods-in-inline-handlers}

Au lieu de se lier directement à un nom de méthode, nous pouvons également appeler des méthodes dans un gestionnaire en ligne. Cela nous permet de passer à la méthode des arguments personnalisés au lieu de l'événement natif :

```js
function say(message) {
  alert(message)
}
```

```js
methods: {
  say(message) {
    alert(message)
  }
}
```

```vue-html
<button @click="say('hello')">Say hello</button>
<button @click="say('bye')">Say bye</button>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9jTEOwjAMRa8SeSld6I5CBWdg9ZJGBiJSN2ocpKjq3UmpFDGx+Vn//b/ANYTjOxGcQEc7uyAqkqTQI98TW3ETq2jyYaQYzYNatSArZTzNUn/IK7Ludr2IBYTG4I3QRqKHJFJ6LtY7+zojbIXNk7yfmhahv5msvqS7PfnHGjJVp9w/hu7qKKwfEd1NSg==)

[Essayer en ligne](https://play.vuejs.org/#eNptjUEKwjAQRa8yZFO7sfsSi57B7WzGdjTBtA3NVC2ldzehEFwIw8D7vM9f1cX742tmVSsd2sl6aXDgjx8ngY7vNDuBFQeAnsWMXagToQAEWg49h0APLncDAIUcT5LzlKJsqRBfPF3ljQjCvXcknEj0bRYZBzi3zrbPE6o0UBhblKiaKy1grK52J/oA//23IcmNBD8dXeVBtX0BF0pXsg==)

## Accéder à l'argument de l'événement dans les gestionnaires en ligne {#accessing-event-argument-in-inline-handlers}

Parfois, nous avons aussi besoin d'accéder à l'événement original du DOM dans un gestionnaire en ligne. Vous pouvez le passer dans une méthode en utilisant la variable spéciale `$event`, ou utiliser une fonction fléchée en ligne :

```vue-html
<!-- en utilisant la variable spéciale $event  -->
<button @click="warn('Form cannot be submitted yet.', $event)">
  Submit
</button>

<!-- en utilisant une fonction fléchée en ligne -->
<button @click="(event) => warn('Form cannot be submitted yet.', event)">
  Submit
</button>
```

```js
function warn(message, event) {
  // nous avons maintenant accès à l'événement natif
  if (event) {
    event.preventDefault()
  }
  alert(message)
}
```

```js
methods: {
  warn(message, event) {
    // nous avons maintenant accès à l'événement natif
    if (event) {
      event.preventDefault()
    }
    alert(message)
  }
}
```

## Modificateurs d'événements {#event-modifiers}

Il est courant d'avoir besoin d'appeler `event.preventDefault()` ou `event.stopPropagation()` à l'intérieur des gestionnaires d'événements. Bien que nous puissions le faire facilement à l'intérieur des méthodes, il serait préférable que les méthodes puissent se focaliser exclusivement sur la logique des données plutôt qu'avoir à gérer les détails des événements du DOM.

Pour résoudre ce problème, Vue fournit des **modificateurs d'événements** pour `v-on`. Rappelons que les modificateurs sont des postfixes de directives désignés par un point.

* `.stop`
* `.prevent`
* `.self`
* `.capture`
* `.once`
* `.passive`

```vue-html
<!-- la propagation de l'événement clic va être arrêtée -->
<a @click.stop="doThis"></a>

<!-- l'événement submit ne va plus rafraîchir la page -->
<form @submit.prevent="onSubmit"></form>

<!-- les modificateurs peuvent être chaînés -->
<a @click.stop.prevent="doThat"></a>

<!-- seulement le modificateur -->
<form @submit.prevent></form>

<!-- ne déclenche le gestionnaire que si event.target est l'élément lui-même. -->
<!-- par exemple pas depuis un élément enfant -->
<div @click.self="doThat">...</div>
```

::: tip
L'ordre est important lorsqu'on utilise des modificateurs car le code correspondant est généré dans le même ordre. De ce fait, utiliser `@click.prevent.self` empêchera **l'action par défaut du clic sur l'élément lui-même et ses enfants**, alors que `@click.self.prevent` empêchera seulement l'action par défaut de clic sur l'élément lui-même.
:::

Les modificateurs `.capture`, `.once`, et `.passive` imitent les [options de la méthode native `addEventListener`](https://developer.mozilla.org/fr/docs/Web/API/EventTarget/addEventListener#options):

```vue-html
<!-- utiliser le mode capture lors de l'ajout de l'écouteur d'événement -->
<!-- c'est-à-dire qu'un événement ciblant un élément interne est traité -->
<!-- ici avant d'être traité par cet élément -->
<div @click.capture="doThis">...</div>

<!-- l'événement clic sera déclenché au maximum une fois -->
<a @click.once="doThis"></a>

<!-- le comportement par défaut de l'élément de défilement aura lieu -->
<!-- immédiatement, au lieu d'attendre la fin de `onScroll`  -->
<!-- s'il contient `event.preventDefault()`                -->
<div @scroll.passive="onScroll">...</div>
```

Le modificateur `.passive` est généralement utilisé avec les écouteurs d'événements de touche pour [améliorer les performances sur les périphériques mobiles](https://developer.mozilla.org/fr/docs/Web/API/EventTarget/addEventListener#improving_scrolling_performance_with_passive_listeners).

::: tip
N'utilisez pas `.passive` et `.prevent` ensemble, car `.passive` indique déjà au navigateur que vous n'avez *pas* l'intention d'empêcher le comportement par défaut de l'événement, et vous aurez probablement un avertissement du navigateur si vous le faites.
:::

## Modificateurs de touche {#key-modifiers}

Lorsque nous écoutons des événements du clavier, nous avons souvent besoin de vérifier des touches spécifiques. Vue permet d'ajouter des modificateurs de touches pour `v-on` ou `@` lors de l'écoute d'événements du clavier :

```vue-html
<!-- appelle `submit` seulement lorsque `key` est `Enter` -->
<input @keyup.enter="submit" />
```

Vous pouvez utiliser directement n'importe quel nom de touche exposé via [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) comme des modificateurs en les convertissant en kebab-case.

```vue-html
<input @keyup.page-down="onPageDown" />
```

Dans l'exemple ci-dessus, le gestionnaire ne sera appelé que si `$event.key` est égal à `'PageDown'`.

### Alias de touche {#key-aliases}

Vue fournit des alias pour les touches les plus couramment utilisées :

* `.enter`
* `.tab`
* `.delete` (capture à la fois les touches "Delete" et "Backspace")
* `.esc`
* `.space`
* `.up`
* `.down`
* `.left`
* `.right`

### Touches de modification du système {#system-modifier-keys}

Vous pouvez utiliser les modificateurs suivant pour déclencher des écouteurs d'événements de la souris ou du clavier seulement lorsque la touche modificatrice correspondante est pressée :

* `.ctrl`
* `.alt`
* `.shift`
* `.meta`

::: tip Note
Sur les claviers Macintosh, meta est la touche commande (⌘). Sur les claviers Windows, meta est la touche Windows (⊞). Sur les claviers Sun Microsystems, meta est marqué d'un diamant solide (◆). Sur certains claviers, en particulier les claviers MIT et ceux des machines Lisp et leurs successeurs, tels que le clavier Knight, le clavier space-cadet, meta est étiqueté "META". Sur les claviers Symbolics, meta est étiqueté "META" ou "Meta".
:::

Par exemple :

```vue-html
<!-- Alt + Entrée -->
<input @keyup.alt.enter="clear" />

<!-- Ctrl + Clic -->
<div @click.ctrl="doSomething">Do something</div>
```

::: tip
Notez que les touches modificatrices sont différentes des touches normales et que lorsqu'elles sont utilisées avec des événements `keyup`, elles doivent être appuyées lorsque l'événement est émis. En d'autres termes, `keyup.ctrl` ne se déclenchera que si vous relâchez une touche tout en maintenant la touche `ctrl` enfoncée. Il ne se déclenchera pas si vous relâchez la touche `ctrl` seulement.
:::

### Modificateur `.exact` {#exact-modifier}

Le modificateur `.exact` permet le contrôle de la combinaison exacte de touches de modification du système requise pour déclencher un événement.

```vue-html
<!-- l'événement sera déclenché même si Alt ou Maj est également pressée -->
<button @click.ctrl="onClick">A</button>

<!-- l'événement ne sera déclenché que quand Ctrl est enfoncé sans autres touches -->
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- l'événement ne sera déclenché que lorsqu'aucune touche de modification du système n'est pressée -->
<button @click.exact="onClick">A</button>
```

## Modificateurs des boutons de la souris {#mouse-button-modifiers}

* `.left`
* `.right`
* `.middle`

Ces modificateurs limitent le gestionnaire aux événements déclenchés par un bouton spécifique de la souris.

Notez cependant que les noms des modificateurs `.left`, `.right` et `.middle` sont basés sur la disposition typique d'une souris pour droitier, mais représentent en fait les déclencheurs d'événements des dispositifs de pointage "principal", "secondaire" et "auxiliaire", respectivement, et non les boutons physiques réels. Ainsi, pour une souris de gaucher, le bouton "principal" peut être physiquement celui de droite, mais il déclenchera le gestionnaire du modificateur `.left`. Ou bien un trackpad peut déclencher le gestionnaire `.left` en tapant avec un doigt, le gestionnaire `.right` en tapant avec deux doigts, et le gestionnaire `.middle` en tapant avec trois doigts. De même, d'autres dispositifs et sources d'événements générant des événements "souris" peuvent avoir des modes de déclenchement qui ne sont pas liés à "left" et "right".

---

---
url: /glossary.md
---
# Glossaire {#glossary}

Ce glossaire est destiné à fournir la signification des termes techniques couramment utilisés lorsque l'on parle de Vue. Il est destiné à être *descriptif* sur la façon dont les termes sont couramment utilisés, et non une spécification *prescriptive* de la façon dont ils doivent être utilisés. Certains termes peuvent avoir des significations ou des nuances légèrement différentes selon le contexte environnant.

\[\[TOC]]

## composant asynchrone {#async-component}

Un *composant asynchrone* est une enveloppe autour d'un autre composant qui permet au composant enveloppé d'être chargé de manière paresseuse. Il est généralement utilisé pour réduire la taille des fichiers .js construits, en leur permettant d'être divisés en morceaux plus petits qui ne sont chargés qu'en cas de besoin.

Vue Router dispose d'une fonctionnalité similaire pour le [chargement paresseux du composant route](https://router.vuejs.org/guide/advanced/lazy-loading.html), bien que cela n'utilise pas la fonctionnalité de composants asynchrones de Vue.

Pour plus de détails, voir :

* [Guide - Composants asynchrones](/guide/components/async.html)

## macro de compilateur {#compiler-macro}

Une *macro de compilateur* est un code spécial qui est traité par un compilateur et converti en quelque chose d'autre. Ils sont en fait une forme astucieuse de remplacement de chaînes de caractères.

Le compilateur [SFC](#single-file-component) de Vue prend en charge diverses macros, telles que `defineProps()`, `defineEmits()` et `defineExpose()`. Ces macros sont intentionnellement conçues pour ressembler à des fonctions JavaScript normales afin qu'elles puissent tirer parti du même analyseur et des mêmes outils d'inférence de type autour de JavaScript / TypeScript. Cependant, elles ne sont pas des fonctions réelles exécutées dans le navigateur. Ce sont des chaînes de caractères spéciales que le compilateur détecte et remplace par le vrai code JavaScript qui sera réellement exécuté.

Les macros ont des limites d'utilisation qui ne s'appliquent pas au code JavaScript normal. Par exemple, vous pourriez penser que `const dp = defineProps` vous permettrait de créer un alias pour `defineProps`, mais cela entraînera en fait une erreur. Il existe également des limitations sur les valeurs pouvant être transmises à `defineProps()`, car les 'arguments' doivent être traités par le compilateur et non au moment de l'exécution.

Pour plus de détails, voir :

* [`<script setup>` - `defineProps()` & `defineEmits()`](/api/sfc-script-setup.html#defineprops-defineemits)
* [`<script setup>` - `defineExpose()`](/api/sfc-script-setup.html#defineexpose)

## composant {#component}

Le terme *composant* n'est pas propre à Vue. Il est commun à de nombreux frameworks d'interface utilisateur. Il décrit une partie de l'interface utilisateur, comme un bouton ou une case à cocher. Les composants peuvent également être combinés pour former des composants plus grands.

Les composants sont le principal mécanisme fourni par Vue pour diviser une interface utilisateur en plus petits éléments, à la fois pour améliorer la maintenabilité et pour permettre la réutilisation du code.

Un composant Vue est un objet. Toutes les propriétés sont facultatives, mais un template ou une fonction de rendu est requis pour que le composant soit rendu. Par exemple, l'objet suivant serait un composant valide :

```js
const HelloWorldComponent = {
  render() {
    return 'Hello world!'
  }
}
```

En pratique, la plupart des applications Vue sont écrites en utilisant des [composants monofichiers](#single-file-component) (fichiers `.vue`). Bien que ces composants puissent ne pas sembler être des objets à première vue, le compilateur SFC les convertira en un objet, qui sera utilisé comme exportation par défaut pour le fichier. D'un point de vue externe, un fichier `.vue` n'est qu'un module ES qui exporte un objet composant.

Les propriétés d'un objet composant sont généralement appelées *options*. C'est là que l'[Options API](#options-api) tire son nom.

Les options d'un composant définissent comment les instances de ce composant doivent être créées. Les composants sont conceptuellement similaires aux classes, bien que Vue n'utilise pas de classes JavaScript réelles pour les définir.

Le terme composant peut également être utilisé plus librement pour désigner des instances de composant.

Pour plus de détails, voir :

* [Guide - Principes fondamentaux des composants](/guide/essentials/component-basics.html)

Le mot « composant » apparaît également dans plusieurs autres termes :

* [composant async](#async-component)
* [composant dynamique](#dynamic-component)
* [component fonctionnel](#functional-component)
* [Web Component](#web-component)

## composable {#composable}

Le terme *composable* décrit un modèle d'utilisation courant dans Vue. Il ne s'agit pas d'une fonctionnalité distincte de Vue, mais simplement d'un moyen d'utiliser la [Composition API](#composition-api) du framework.

* Un composable est une fonction.
* Les composables sont utilisés pour encapsuler et réutiliser la logique avec état.
* Le nom de la fonction commence généralement par `use`, afin que les autres développeurs sachent qu'il s'agit d'une fonction composable.
* La fonction est typiquement censée être appelée pendant l'exécution synchrone de la fonction `setup()` d'un composant (ou, de manière équivalente, pendant l'exécution d'un bloc `<script setup>`). Cela lie l'invocation du composable au contexte actuel du composant, par exemple via des appels à `provide()`, `inject()` ou `onMounted()`.
* Les composables renvoient généralement un objet simple, et non un objet réactif. Cet objet contient généralement des références et des fonctions et est censé être déstructuré dans le code appelant.

Comme pour de nombreux modèles, il peut y avoir des désaccords sur la question de savoir si un code spécifique peut prétendre au label. Toutes les fonctions utilitaires JavaScript ne sont pas composables. Si une fonction n'utilise pas la Composition API, elle n'est probablement pas composable. Si elle ne s'attend pas à être appelée pendant l'exécution synchrone de `setup()` alors elle n'est probablement pas composable. Les composables sont spécifiquement utilisés pour encapsuler la logique avec état, ils ne sont pas simplement une convention d'appellation pour les fonctions.

Voir le [Guide - Composables](/guide/reusability/composables.html) pour plus de détails sur l'écriture des composables.

## Composition API {#composition-api}

La *Composition API* est une collection de fonctions utilisées pour écrire des composants et des composables dans Vue.

Le terme est également utilisé pour décrire l'un des deux styles principaux utilisés pour écrire des composants, l'autre étant l'[Options API](#options-api). Les composants écrits à l'aide de la Composition API utilisent soit `<script setup>`, soit une fonction explicite `setup()`.

Voir la [FAQ de la Composition API](/guide/extras/composition-api-faq) pour plus de détails.

## élément personnalisé {#custom-element}

Un *élément personnalisé* est une fonctionnalité de la norme des [Web Components](#web-component), qui est mise en œuvre dans les navigateurs web modernes. Il s'agit de la possibilité d'utiliser un élément HTML personnalisé dans votre balisage HTML pour inclure un Web Component à cet endroit de la page.

Vue prend en charge nativement le rendu des éléments personnalisés et permet de les utiliser directement dans les templates de composants Vue.

Les éléments personnalisés ne doivent pas être confondus avec la possibilité d'inclure des composants Vue en tant que balises dans le template d'un autre composant Vue. Les éléments personnalisés sont utilisés pour créer des Web Components, et non des composants Vue.

Pour plus de détails, voir :

* [Vue et les Web Components](/guide/extras/web-components.html)

## directive {#directive}

Le terme *directive* fait référence aux attributs de template commençant par le préfixe `v-`, ou à leurs abréviations équivalentes.

Les directives intégrées comprennent `v-if`, `v-for`, `v-bind`, `v-on` et `v-slot`.

Vue permet également de créer des directives personnalisées, bien qu'elles ne soient généralement utilisées comme une 'trappe d'accès' pour manipuler directement les nœuds du DOM. Les directives personnalisées ne peuvent généralement pas être utilisées pour recréer la fonctionnalité des directives intégrées.

Pour plus de détails, voir :

* [Guide - Syntaxe de template - Directives](/guide/essentials/template-syntax.html#directives)
* [Guide - Directives personnalisées](/guide/reusability/custom-directives.html)

## composant dynamique {#dynamic-component}

Le terme *composant dynamique* est utilisé pour décrire les cas où le choix du composant enfant à rendre doit être fait dynamiquement. Typiquement, ceci est réalisé en utilisant `<component :is="type">`.

Un composant dynamique n'est pas un type particulier de composant. N'importe quel composant peut être utilisé comme composant dynamique. C'est le choix du composant qui est dynamique, plutôt que le composant lui-même.

Pour plus de détails, voir :

* [Guide - Principes fondamentaux des composants - Composants dynamiques](/guide/essentials/component-basics.html#dynamic-components)

## effect {#effect}

Voir [reactive effect](#reactive-effect) et [side effect](#side-effect).

## event {#event}

L'utilisation des événements pour communiquer entre différentes parties d'un programme est commune à de nombreux domaines de programmation différents. Dans Vue, le terme est généralement appliqué à la fois aux événements d'éléments HTML natifs et aux événements de composants Vue. La directive `v-on` est utilisée dans les templates pour écouter les deux types d'événements.

Pour plus de détails, voir :

* [Guide - Gestion d'événement](/guide/essentials/event-handling.html)
* [Guide - Gestion des évènements](/guide/components/events.html)

## fragment {#fragment}

Le terme *fragment* se réfère à un type special de [VNode](#vnode) qui est utilisé comme parent pour les autres VNodes, mais qui ne rend aucun élément lui-même.

Le nom provient d'un concept similaire au [`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) dans le DOM API natif.

Les fragments sont utilisés pour supporter les composants avec de multiples noeuds parent. Bien que ces composant peuvent donner l'impression d'avoir plusieurs noeuds parent, dans les coulisses ils utilisent un noeud fragment comme unique parent, comme parent des noeuds 'racine'.

Les fragments sont aussi utilisées par le compilateur de template comme un moyen d'envelopper plusieurs noeuds dynamiques, par exemple ceux créés avec `v-for` ou `v-if`. Cela permet de passer des informations supplémentaires à l'algorithme de correction du [VDOM](#virtual-dom). La majorité est gérée en interne, mais un endroit où vous pourriez rencontrer cela directement est en utilisant `key` sur un élément `<template>` avec `v-for`. Dans ce scénario, `key` est ajouté comme une [prop](#prop) au fragment VNode.

Les noeuds fragment sont actuellement rendus dans le DOM en tant que noeuds de texte vides, cependant ceci est un détails d'implémentation. Vous pourriez rencontrer ces noeuds texte si vous utilisez `$el` ou essayez de parcourir le DOM avec des API intégrées à votre navigateur.

## composant fonctionnel {#functional-component}

Une définition de composant est généralement un objet contenant des options. Cela peut sembler différent si vous utilisez `<script setup>`, mais le composant exporté depuis le fichier `.vue` sera toujours un objet.

Un *composant fonctionnel* est une autre forme de composant déclaré à l'aide d'une fonction. Cette fonction fait office de [fonction de rendu](#render-function) pour le composant.

Un composant fonctionnel ne peut pas avoir d'état propre. Il ne passe pas non plus par le cycle de vie habituel des composants, de sorte que les hooks de cycle de vie ne peuvent pas être utilisés. Ils sont donc légèrement plus légers que les composants habituels avec état.

Pour plus de détails, voir :

* [Guide - Fonctions de rendu et JSX - Composants fonctionnels](/guide/extras/render-function.html#functional-components)

## hissage (ou *hoisting*) {#hoisting}

Le terme *hissage* est utilisé pour décrire l'exécution d'une section de code avant qu'elle ne soit atteinte, avant d'autres codes. L'exécution est 'tirée vers le haut' à un point antérieur.

JavaScript utilise le hissage pour certaines constructions, telles que `var`, `import` et les déclarations de fonctions.

Dans un contexte Vue, le compilateur applique le *hissage statique* pour améliorer les performances. Lors de la compilation d'un composant, les valeurs statiques sont déplacées hors de la portée du composant. Ces valeurs statiques sont qualifiées de hissées parce qu'elles sont créées en dehors du composant.

## cache statique {#cache-static}

Le terme *cache* est utilisé pour décrire le stockage temporaire de données fréquemment consultées afin d'améliorer les performances.

Le compilateur de template Vue identifie ces VNodes statiques, les met en cache lors du rendu initial et réutilise les mêmes VNodes pour chaque nouveau rendu.

Pour plus de détails, voir :

* [Guide - Mécanismes de rendu - Cache Statique](/guide/extras/rendering-mechanism.html#cache-static)

## template depuis le DOM {#in-dom-template}

Il existe plusieurs façons de spécifier un template pour un composant. Dans la plupart des cas, le template est fourni sous la forme d'une chaîne de caractères.

Le terme *template depuis le DOM* fait référence au scénario dans lequel le template est fourni sous la forme de nœuds DOM, au lieu d'une chaîne de caractères. Vue convertit ensuite les nœuds du DOM en une chaîne de caractères à l'aide de `innerHTML`.

Typiquement, un template depuis le DOM commence par un balisage HTML écrit directement dans le HTML de la page. Le navigateur l'analyse ensuite en nœuds DOM, que Vue utilise ensuite pour lire le `innerHTML`.

Pour plus de détails, voir :

* [Guide - Créer une application - Template de composant racine depuis le DOM](/guide/essentials/application.html#in-dom-root-component-template)
* [Guide - Principes fondamentaux des composants - Mises en garde concernant l'analyse du template DOM](/guide/essentials/component-basics.html#in-dom-template-parsing-caveats)
* [Options: Rendu - template](/api/options-rendering.html#template)

## inject {#inject}

Voir [provide / inject](#provide-inject).

## hooks du cycle de vie {#lifecycle-hooks}

Une instance de composant Vue suit un cycle de vie. Par exemple, elle est créée, montée, mise à jour et démontée.

Les *hooks du cycle de vie* sont un moyen d'écouter ces événements du cycle de vie.

Avec l'Option API, chaque hook est fourni comme une option séparée, par exemple `mounted`. La Composition API utilise des fonctions à la place, comme `onMounted()`.

Pour plus de détails, voir :

* [Guide - Les hooks du cycle de vie](/guide/essentials/lifecycle.html)

## macro {#macro}

Voir [macro de compilateur](#compiler-macro).

## slot nommé {#named-slot}

Un composant peut avoir plusieurs slots, différenciés par leur nom. Les autres slots que le slot par défaut sont appelés *slots nommés*.

Pour plus de détails, voir :

* [Guide - Slots - Slots nommés](/guide/components/slots.html#named-slots)

## Options API {#options-api}

Les composants Vue sont définis à l'aide d'objets. Les propriétés de ces objets composants sont appelées *options*.

Les composants peuvent être écrits dans deux styles. Un style utilise la [Composition API](#composition-api) en conjonction avec `setup` (soit via une option `setup()` ou `<script setup>`). L'autre style utilise plus ou moins directement la Composition API, utilisant plutôt diverses options de composants pour obtenir un résultat similaire. Les options de composants utilisées de cette manière représentent ce qu'on appelle l'*Options API*.

L'Options API inclut des options telles que `data()`, `computed`, `methods` et `created()`.

Certaines options, telles que `props`, `emits` et `inheritAttrs`, peuvent être utilisées lors de la création de composants avec l'une ou l'autre API. Comme il s’agit d’options de composants, elles pourraient être considérées comme faisant partie de l’Options API. Cependant, comme ces options sont également utilisées conjointement avec `setup()`, il est généralement plus utile de les considérer comme partagées entre les deux styles de composants.

La fonction `setup()` elle-même est une option de composant, elle *pourrait* donc être décrite comme faisant partie de l'Options API. Cependant, ce n’est pas ainsi que le terme « Options API » est normalement utilisé. Au lieu de cela, la fonction `setup()` est considérée comme faisant partie de la Composition API.

## plugin {#plugin}

Même si le terme *plugin* peut être utilisé dans une grande variété de contextes, Vue a un concept spécifique de plugin comme moyen d'ajouter des fonctionnalités à une application.

Les plugins sont ajoutés à une application en appelant `app.use(plugin)`. Le plugin lui-même est soit une fonction, soit un objet avec une fonction `install`. Cette fonction recevra l'instance d'application et pourra alors faire tout ce qu'elle doit faire.

Pour plus de détails, voir :

* [Guide - Plugins](/guide/reusability/plugins.html)

## prop {#prop}

Il existe trois utilisations courantes du terme *prop* dans Vue :

* Props de composant
* Props de VNode
* Props de Slot

*Les props de composants* sont ce que la plupart des gens considèrent comme des props. Ils sont explicitement définis par un composant en utilisant soit `defineProps()` soit l'option `props`.

Le terme *props de VNode* fait référence aux propriétés de l'objet transmis en tant que second argument de `h()`. Il peut s'agir de props de composants, mais aussi d'événements de composants, d'événements DOM, d'attributs DOM et de propriétés DOM. Vous ne rencontrerez généralement les props VNode que si vous travaillez avec des fonctions de rendu pour manipuler directement les VNodes.

Les *props de slot* sont les propriétés transmises à un scoped slot.

Dans tous les cas, les props sont des propriétés qui sont transmises depuis l'extérieur.

Bien que le mot props soit dérivé du mot *propriétés*, le terme props a une signification beaucoup plus spécifique dans le contexte de Vue. Vous devriez éviter de l'utiliser comme abréviation de propriétés.

Pour plus de détails, voir :

* [Guide - Props](/guide/components/props.html)
* [Guide - Fonctions de rendu et JSX](/guide/extras/render-function.html)
* [Guide - Slots - Scoped Slots](/guide/components/slots.html#scoped-slots)

## provide / inject {#provide-inject}

`provide` et `inject` sont une forme de communication inter-composants.

Lorsqu'un composant *fournit* une valeur, tous les descendants de ce composant peuvent alors choisir de récupérer cette valeur, en utilisant `inject`. Contrairement à ce qui se passe avec les props, le composant qui fournit la valeur ne sait pas précisément quel composant la reçoit.

`provide` et `inject` sont un moyen parfois utilisé pour éviter le *prop drilling* ou également de manière implicite pour un composant de communiquer avec le contenu de son slot.

`provide` peut également être utilisée au niveau de l'application, en rendant une valeur disponible pour tous les composants de cette application.

Pour plus de détails, voir :

* [Guide - provide / inject](/guide/components/provide-inject.html)

## effet réactif {#reactive-effect}

Un *effet réactif* fait partie du système de réactivité de Vue. Il fait référence au processus de suivi des dépendances d'une fonction et à la ré-exécution de cette fonction lorsque les valeurs de ces dépendances changent.

`watchEffect()` est la façon la plus directe de créer un effet. Plusieurs autres parties de Vue utilisent les effets en interne, par exemple les mises à jour du rendu des composants, `computed()` et `watch()`.

Vue ne peut suivre les dépendances réactives qu'à l'intérieur d'un effet réactif. Si la valeur d'une propriété est lue en dehors d'un effet réactif, elle 'perdra' sa réactivité, dans le sens où Vue ne saura pas quoi faire si cette propriété change par la suite.

Le terme est dérivé de 'effet de bord'. L'appel à la fonction d'effet est un effet de bord de la modification de la valeur de la propriété.

Pour plus de détails, voir :

* [Guide - La réactivité en détails](/guide/extras/reactivity-in-depth.html)

## réactivité {#reactivity}

En général, la *réactivité* fait référence à la capacité d'effectuer automatiquement des actions en réponse à des changements de données. Par exemple, mettre à jour le DOM ou faire une requête réseau lorsqu'une valeur de données change.

Dans le contexte de Vue, la réactivité est utilisée pour décrire un ensemble de fonctionnalités. Ces fonctionnalités se combinent pour former un *système de réactivité*, qui est exposé via l'[API de réactivité](#reactivity-api).

Un système de réactivité peut être mis en œuvre de différentes manières. Par exemple, il pourrait être réalisé par une analyse statique du code pour déterminer ses dépendances. Cependant, Vue n'utilise pas cette forme de système de réactivité.

Au lieu de cela, le système de réactivité de Vue suit l'accès aux propriétés au moment de l'exécution. Pour ce faire, il utilise à la fois des wrappers Proxy et des fonctions [accesseur](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Functions/get#description)/[mutateur](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Functions/set#description) pour les propriétés.

Pour plus de détails, voir :

* [Guide - Fondamentaux de la réactivité](/guide/essentials/reactivity-fundamentals.html)
* [Guide - La réactivité en détails](/guide/extras/reactivity-in-depth.html)

## API de réactivité {#reactivity-api}

L'*API de réactivité* est une collection de fonctions de base de Vue liées à la [réactivité](#reactivity). Ils peuvent être utilisés indépendamment des composants. Elle comprend des fonctions telles que `ref()`, `reactive()`, `computed()`, `watch()` et `watchEffect()`.

L'API de réactivité est un sous-ensemble de la Composition API.

Pour plus de détails, voir :

* [API de la réactivité : Essentiel](/api/reactivity-core.html)
* [API de la réactivité : Utilitaires](/api/reactivity-utilities.html)
* [API de la réactivité : Avancé](/api/reactivity-advanced.html)

## ref {#ref}

> Nous parlons ici de l'utilisation de `ref` pour la réactivité. Pour l'attribut `ref` utilisé dans les templates, voir plutôt [ref de template](#template-ref).

Une `ref` fait partie du système de réactivité de Vue. C'est un objet avec une seule propriété réactive, appelée `value`.

Il existe différents types de ref. Par exemple, les refs peuvent être créées en utilisant `ref()`, `shallowRef()`, `computed()`, et `customRef()`. La fonction `isRef()` peut être utilisée pour vérifier si un objet est une ref, et `isReadonly()` peut être utilisée pour vérifier si la ref permet la réaffectation directe de sa valeur.

Pour plus de détails, voir :

* [Guide - Fondamentaux de la réactivité](/guide/essentials/reactivity-fundamentals.html)
* [API de la réactivité : Essentiel](/api/reactivity-core.html)
* [API de la réactivité : Utilitaires](/api/reactivity-utilities.html)
* [API de la réactivité : Avancé](/api/reactivity-advanced.html)

## fonction de rendu {#render-function}

Une *fonction de rendu* est la partie d'un composant qui génère les VNodes utilisés lors du rendu. Les templates sont compilés en fonctions de rendu.

Pour plus de détails, voir :

* [Guide - Fonctions de rendu et JSX](/guide/extras/render-function.html)

## programmateur {#scheduler}

Le *programmateur* est la partie des rouages internes de Vue qui contrôle le moment où les [effets réactifs](#reactive-effect) sont exécutés.

Lorsque l'état réactif change, Vue ne déclenche pas immédiatement les mises à jour du rendu. Au lieu de cela, il les regroupe à l'aide d'une file d'attente. Cela permet de s'assurer qu'un composant n'effectue qu'un seul nouveau rendu, même si plusieurs changements sont apportés aux données sous-jacentes.

Les [Observateurs](/guide/essentials/watchers.html) sont également mis en lots en utilisant la file d'attente du programmateur. Les observateurs avec `flush: 'pre'` (par défaut) seront exécutés avant le rendu du composant, tandis que ceux avec `flush: 'post'` seront exécutés après le rendu du composant.

Les tâches du programmateur sont également utilisées pour effectuer diverses autres tâches internes, telles que le déclenchement de certains [hooks du cycle de vie](#lifecycle-hooks) et la mise à jour des [refs de template](#template-ref).

## scoped slot {#scoped-slot}

Le terme *scoped slot* est utilisé pour désigner un [slot](#slot) qui reçoit des [props](#prop).

Historiquement, Vue faisait une plus grande distinction entre les slots scoped et non scoped. Dans une certaine mesure, ils pourraient être considérés comme deux fonctionnalités distinctes, unifiées derrière une syntaxe de template commune.

Dans Vue 3, les API des slots ont été simplifiées pour que tous les slots se comportent comme des scoped slots. Cependant, les cas d'utilisation des scoped slots et non scoped diffèrent souvent, de sorte que le terme s'avère toujours utile pour désigner les slots avec des props.

Les props transmis à un slot ne peuvent être utilisés que dans une région spécifique du template parent, responsable de la définition du contenu du slot. Cette région du template se comporte comme une variable de scope pour les props, d'où le nom de 'scoped slot'.

Pour plus de détails, voir :

* [Guide - Slots - Scoped Slots](/guide/components/slots.html#scoped-slots)

## SFC {#sfc}

Voir [Composant monofichier](#single-file-component).

## effet de bord {#side-effect}

Le terme *effet de bord* n'est pas spécifique à Vue. Il est utilisé pour décrire les opérations ou les fonctions qui font quelque chose au-delà de leur portée locale.

Par exemple, lors de l'affectation d'une propriété comme `user.name = null`, on s'attend à ce que cela change la valeur de `user.name`. Si cela fait aussi quelque chose d'autre, comme déclencher le système de réactivité de Vue, alors cela sera décrit comme un effet de bord. C'est l'origine du terme [effet réactif](#reactive-effect) dans Vue.

Lorsqu'une fonction est décrite comme ayant des effets de bord, cela signifie qu'elle effectue une sorte d'action observable en dehors de la fonction, en plus de renvoyer une valeur. Cela peut signifier qu'elle met à jour une valeur dans l'état ou qu'elle déclenche une requête réseau.

Ce terme est souvent utilisé pour décrire le rendu ou les propriétés calculées. On considère que la meilleure pratique pour le rendu est de ne pas avoir d'effets de bord. De même, la fonction accesseur d'une propriété calculée ne doit pas avoir d'effets de bord.

## Composant monofichier (ou *Single-File Component*) {#single-file-component}

Le terme *Single-File Component*, ou SFC, fait référence au format de fichier `.vue` couramment utilisé pour les composants Vue.

Voir aussi :

* [Guide - Composants monofichiers](/guide/scaling-up/sfc.html)
* [Spécifications liées à la syntaxe des composants monofichiers](/api/sfc-spec.html)

## slot {#slot}

Les slots sont utilisés pour transmettre du contenu aux composants enfants. Alors que les props sont utilisés pour transmettre des données, les slots sont utilisés pour transmettre un contenu plus riche composé d'éléments HTML et d'autres composants Vue.

Pour plus de détails, voir :

* [Guide - Slots](/guide/components/slots.html)

## ref de template {#template-ref}

Le terme *ref de template* fait référence à l'utilisation d'un attribut `ref` sur un élément à l'intérieur d'un template. Après le rendu du composant, cet attribut est utilisé pour remplir une propriété correspondante avec l'élément HTML ou l'instance de composant qui correspond à l'élément dans le template.

Si vous utilisez l'Options API, les refs sont exposés via les propriétés de l'objet `$refs`.

Avec la Composition API, les refs de template alimentent une [ref](#ref) réactive portant le même nom.

Il ne faut pas confondre les refs de templates avec les refs réactives du système de réactivité de Vue.

Pour plus de détails, voir :

* [Guide - Les refs du template](/guide/essentials/template-refs.html)

## VDOM {#vdom}

Voir [DOM virtuel](#virtual-dom).

## DOM virtuel {#virtual-dom}

Le terme *DOM virtuel* (VDOM) n'est pas propre à Vue. Il s'agit d'une approche commune utilisée par plusieurs frameworks web pour gérer les mises à jour de l'interface utilisateur.

Les navigateurs utilisent un arbre de nœuds pour représenter l'état actuel de la page. Cet arbre, et les API JavaScript utilisées pour interagir avec celui-ci, représentent le *document object model*, ou *DOM*.

La manipulation du DOM est un goulot d'étranglement majeur pour les performances. Le DOM virtuel fournit une stratégie pour gérer cela.

Plutôt que de créer directement des nœuds DOM, les composants Vue génèrent une description des nœuds DOM qu'ils souhaitent. Ces descripteurs sont des objets JavaScript simples, connus sous le nom de VNodes (nœud virtuel du DOM). La création de VNodes est relativement peu coûteuse.

Chaque fois qu'un composant est rerendu, le nouvel arbre de VNodes est comparé à l'arbre de VNodes précédent et toutes les différences sont alors appliquées au DOM réel. Si rien n'a changé, le DOM n'a pas besoin d'être modifié.

Vue utilise une approche hybride que nous appelons [DOM virtuel basé sur la compilation](/guide/extras/rendering-mechanism.html#compiler-informed-virtual-dom). Le compilateur de template de Vue est capable d'appliquer des optimisations de performance basées sur l'analyse statique du template. Plutôt que d'effectuer une comparaison complète des anciens et nouveaux arbres VNode d'un composant au moment de l'exécution, Vue peut utiliser les informations extraites par le compilateur pour réduire la comparaison aux seules parties de l'arbre qui peuvent réellement changer.

Pour plus de détails, voir :

* [Guide - Mécanismes de rendu](/guide/extras/rendering-mechanism.html)
* [Guide - Fonctions de rendu et JSX](/guide/extras/render-function.html)

## VNode {#vnode}

Un *VNode* est un *nœud virtuel du DOM*. Ils peuvent être créés à l'aide de la fonction [`h()`](/api/render-function.html#h).

Voir [virtual DOM](#virtual-dom) pour plus d'informations.

## Web Component {#web-component}

La norme *Web Components* est un ensemble de fonctionnalités mises en œuvre dans les navigateurs web modernes.

Les composants Vue ne sont pas des Web Components, mais `defineCustomElement()` peut être utilisé pour créer un [élément personnalisé](#custom-element) à partir d'un composant Vue. Vue prend également en charge l'utilisation d'éléments personnalisés à l'intérieur des composants Vue.

Pour plus de détails, voir :

* [Guide - Vue et les Web Components](/guide/extras/web-components.html)

---

---
url: /about/community-guide.md
---

# Guide de la communauté {#community-guide}

La communauté de Vue se développe incroyablement vite et si vous lisez ceci, il y a de fortes chances que vous soyez prêt à la rejoindre. Alors... bienvenue !

Nous allons répondre ici à la fois à ce que la communauté peut faire pour vous et à ce que vous pouvez faire pour la communauté.

## Ressources {#resources}

### Code de bonne conduite {#code-of-conduct}

Notre [Code de bonne conduite](/about/coc) est un guide destiné à faciliter notre enrichissement à tous ainsi que celui des communautés techniques auxquelles nous participons.

### Restez informé(e) {#stay-in-the-know}

* Suivez notre [compte Twitter officiel](https://x.com/vuejs).
* Suivez les [membres de l'équipe](./team) sur Twitter ou GitHub.
* Suivez les [discussions RFC](https://github.com/vuejs/rfcs).
* Abonnez-vous au [blog officiel](https://blog.vuejs.org/).

### Obtenez de l'aide {#get-support}

* [Discord Chat](https://discord.com/invite/vue) : Un endroit où les développeuses et développeurs de Vue peuvent se rencontrer et discuter en temps réel.
* [Forum](https://forum.vuejs.org/) : Le meilleur endroit pour poser des questions et obtenir des réponses sur Vue et son écosystème.
* [Communauté DEV](https://dev.to/t/vue) : Partagez et discutez des sujets liés à Vue sur Dev.to.
* [Rencontres](https://events.vuejs.org/meetups) : Vous souhaitez trouver des passionnés de Vue comme vous ? Vous souhaitez devenir un leader de la communauté ? Nous avons l'aide et le soutien dont vous avez besoin ici même !
* [GitHub](https://github.com/vuejs) : Si vous souhaiter signaler un bug ou réclamer une fonctionnalité, les issues GitHub sont là pour ça. Veuillez respecter les règles spécifiées dans le modèle des issues de chaque dépôt.
* [Communauté Twitter (non officielle)](https://x.com/i/communities/1516368750634840064) : Une communauté Twitter, où vous pouvez rencontrer d'autres passionnés de Vue, obtenir de l'aide ou simplement discuter de Vue.

### Explorez l'écosystème {#explore-the-ecosystem}

* [The Awesome Vue Page](https://github.com/vuejs/awesome-vue) : Voyez quelles autres ressources géniales ont été publiées par d'autres personnes géniales.
* [Vue Telescope Explorer](https://vuetelescope.com/explore) : Explorez les sites Web créés avec Vue, avec des informations sur le framework et les bibliothèques qu'ils utilisent.
* [Made with Vue.js](https://madewithvuejs.com/) : vitrines de projets et de bibliothèques réalisés avec Vue.
* [Le sous-forum "Show and Tell"](https://github.com/vuejs/core/discussions/categories/show-and-tell) : Un autre endroit idéal pour découvrir ce que d'autres ont construit avec et pour l'écosystème Vue, qui est en pleine expansion.

## Ce que vous pouvez faire {#what-you-can-do}

### Aidez les autres utilisateurs {#help-fellow-users}

La contribution au code n'est pas la seule forme de contribution à la communauté Vue. Répondre à une question pour un autre utilisateur de Vue sur Discord ou sur le forum est également considéré comme une contribution précieuse.

### Aidez à trier les issues {#help-triage-issues}

Le tri d'une issue implique de collecter les informations manquantes, de reproduire le problème, de vérifier la validité de l'issue et de rechercher ses causes.

Nous recevons chaque jour de nombreuses issues dans [nos dépôts sur GitHub](https://github.com/vuejs). Notre bande passante est limitée par rapport au nombre d'utilisateurs, de sorte que le tri des issues à lui seul peut demander un effort considérable à l'équipe. En nous aidant à les trier, vous nous permettez de devenir plus efficaces, ce qui nous permet de consacrer du temps à des tâches plus prioritaires.

Il n'est pas demandé de trier une issue dans le but de la corriger (même si ce serait bien aussi). Partager le résultat de votre enquête, par exemple le commit qui a conduit au bug, peut déjà nous faire gagner un temps énorme.

### Contribuer au code {#contribute-code}

Corriger des bugs ou ajouter de nouvelles fonctionnalités est la forme la plus directe de contribution que vous pouvez faire.

Le dépôt principal de Vue fournit un [guide de contribution](https://github.com/vuejs/core/blob/main/.github/contributing.md), qui contient des directives pour les pull request et des informations concernant la configuration de la compilation et l'architecture de haut niveau. D'autres dépôts de sous-projets peuvent également contenir leur propre guide de contribution - veuillez vous assurer de les lire avant de soumettre des pull request.

Les corrections de bugs sont les bienvenues à tout moment. Pour les nouvelles fonctionnalités, il est préférable de discuter du cas d'utilisation et des détails de mise en œuvre d'abord dans le [dépôt RFC](https://github.com/vuejs/rfcs/discussions).

### Partagez (et construisez) votre expérience {#share-and-build-your-experience}

Outre le fait de répondre aux questions et de partager des ressources dans le forum et le chat, il existe d'autres moyens moins évidents de partager et d'étendre vos connaissances :

* **Développez des supports d'apprentissage.** On dit souvent que la meilleure façon d'apprendre est d'enseigner. Si vous faites quelque chose d'intéressant avec Vue, renforcez votre expertise en écrivant un article de blog, en développant un atelier, ou même en publiant un résumé et en le partageant sur les réseaux sociaux.
* **Surveillez un dépôt qui vous tient à coeur.** Vous recevrez des notifications dès qu'il y a de l'activité dans ce dépôt, ce qui vous permettra d'être au courant des discussions en cours et des fonctionnalités à venir. C'est un moyen fantastique d'acquérir de l'expertise afin d'être en mesure d'aider à résoudre les issues et les pull request.

### Traduire la documentation {#translate-docs}

J'espère qu'en ce moment même, vous lisez cette phrase dans votre langue préférée. Si ce n'est pas le cas, voulez-vous nous aider à rendre cela possible ?

Consultez le [Guide des traductions](/translations/) pour plus de détails sur la façon dont vous pouvez vous impliquer.

### Devenez un leader de la communauté {#become-a-community-leader}

Il y a beaucoup de choses que vous pouvez faire pour aider Vue à se développer dans votre communauté :

* **Présentez un talk lors d'une rencontre locale.** Qu'il s'agisse d'une présentation ou d'un atelier, vous pouvez apporter beaucoup de valeur à votre communauté en aidant les développeurs Vue, nouveaux ou expérimentés, à poursuivre leur apprentissage.
* **Organisez une rencontre.** S'il n'y a pas encore de rencontre Vue dans votre région, vous pouvez créer la vôtre ! Utilisez les [ressources de events.vuejs.org](https://events.vuejs.org/resources/#getting-started) pour faire de votre rencontre une réussite !
* **Aidez les organisateurs d'une rencontre.** Il n'y a jamais trop d'aide quand il s'agit d'organiser un événement, alors offrez votre aide aux organisateurs locaux pour faire de chaque événement un succès.

Si vous avez des questions sur la façon dont vous pouvez vous impliquer davantage au sein de votre communauté locale Vue, contactez-nous sur Twitter à l'adresse [@vuejs\_events](https://www.x.com/vuejs_events) !

---

---
url: /api/compile-time-flags.md
---

# Indicateurs à la compilation {#compile-time-flags}

:::tip
Les indicateurs à la compilation ne s'appliquent que lors de l'utilisation de la version `esm-bundler` de Vue (c'est-à-dire `vue/dist/vue.esm-bundler.js`).
:::

Lorsque l'on utilise Vue avec des outils de build, il est possible de configurer un certain nombre d'indicateurs à la compilation pour activer/désactiver certaines fonctionnalités. L'avantage de l'utilisation des indicateurs à la compilation est que les fonctionnalités désactivées de cette manière peuvent être supprimées du paquet final via le *tree-shaking*.

Vue fonctionnera même si ces indicateurs ne sont pas explicitement configurés. Cependant, il est recommandé de toujours les configurer afin que les fonctionnalités concernées puissent être correctement supprimées lorsque cela est possible.

Voir [Guides de configuration](#configuration-guides) pour savoir comment les configurer en fonction de votre outil de construction.

## `__VUE_OPTIONS_API__` {#VUE\_OPTIONS\_API}

* **Par défaut:** `true`

  Activer / désactiver la prise en charge de l'Option API. La désactivation de cette fonction permet d'obtenir des paquets plus petits, mais peut affecter la compatibilité avec les bibliothèques tierces si elles s'appuient sur l'Option API.

## `__VUE_PROD_DEVTOOLS__` {#VUE\_PROD\_DEVTOOLS}

* **Par défaut:** `false`

  Activer / désactiver le support des outils de développement dans les versions de production. Cela aura pour conséquence d'inclure plus de code dans le *bundle*, il est donc recommandé de ne l'activer qu'à des fins de débogage.

## `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__` {#VUE\_PROD\_HYDRATION\_MISMATCH\_DETAILS}

* **Par défaut :** `false`

  Activer / désactiver les avertissements détaillés pour les erreurs d'hydratation dans les versions de production. Cela aura pour conséquence d'inclure plus de code dans le bundle, il est donc recommandé de ne l'activer qu'à des fins de débogage.

## Guides de configuration {#configuration-guides}

* Disponible à partir de la version 3.4

### Vite {#vite}

`@vitejs/plugin-vue` fournit automatiquement des valeurs par défaut pour ces indicateurs. Pour changer les valeurs par défaut, utilisez [l'option de configuration `define`](https://vite.dev/config/shared-options.html#define) de Vite :

```js [vite.config.js]
import { defineConfig } from 'vite'

export default defineConfig({
  define: {
    // activer les détails d'incohérences lors de l'hydratation dans la version de production
    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'true'
  }
})
```

### vue-cli {#vue-cli}

`@vue/cli-service` fournit automatiquement des valeurs par défaut pour certains de ces indicateurs. Pour configurer / modifier les valeurs :

```js [vue.config.js]
module.exports = {
  chainWebpack: (config) => {
    config.plugin('define').tap((definitions) => {
      Object.assign(definitions[0], {
        __VUE_OPTIONS_API__: 'true',
        __VUE_PROD_DEVTOOLS__: 'false',
        __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'
      })
      return definitions
    })
  }
}
```

### webpack {#webpack}

Les indicateurs doivent être définis à l'aide de la fonction [DefinePlugin](https://webpack.js.org/plugins/define-plugin/) de webpack :

```js [webpack.config.js]
module.exports = {
  // ...
  plugins: [
    new webpack.DefinePlugin({
      __VUE_OPTIONS_API__: 'true',
      __VUE_PROD_DEVTOOLS__: 'false',
      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'
    })
  ]
}
```

### Rollup {#rollup}

Les indicateurs doivent être définis à l'aide de [@rollup/plugin-replace](https://github.com/rollup/plugins/tree/master/packages/replace) :

```js [rollup.config.js]
import replace from '@rollup/plugin-replace'

export default {
  plugins: [
    replace({
      __VUE_OPTIONS_API__: 'true',
      __VUE_PROD_DEVTOOLS__: 'false',
      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'
    })
  ]
}
```

---

---
url: /guide/introduction.md
---

# Introduction {#introduction}

:::info Vous êtes en train de lire la documentation de Vue 3

* Le support de Vue 2 s'est terminé le **31 décembre 2023**. En savoir plus sur [Vue 2 EOL (Fin de vie)](https://v2.vuejs.org/eol/).
* Vous souhaitez migrer depuis Vue 2 ? Jetez un œil sur [le guide de migration (EN)](https://v3-migration.vuejs.org/).
  :::

## Qu'est-ce que Vue? {#what-is-vue}

Vue (/vjuː/ à prononcer comme en anglais: **view**) est un framework JavaScript qui se repose sur les standards HTML, CSS et JavaScript. Il propose une manière efficace de déclarer des composants pour la construction d'interfaces utilisateur de toute complexité.

Voici un exemple simple :

```js
import { createApp } from 'vue'

createApp({
  data() {
    return {
      count: 0
    }
  }
}).mount('#app')
```

```js
import { createApp, ref } from 'vue'

createApp({
  setup() {
    return {
      count: ref(0)
    }
  }
}).mount('#app')
```

```vue-html
<div id="app">
  <button @click="count++">
    Le compteur est à {{ count }}
  </button>
</div>
```

**Résultat**

Cet exemple illustre les deux principales fonctionnalités de Vue :

* **Rendu déclaratif** : Vue s'appuie sur le standard HTML avec une syntaxe de type template qui permet de décrire de manière déclarative la structure HTML tout en étant basée sur un état JavaScript.

* **Réactivité** : Vue traque automatiquement tout changement d'état JavaScript et met à jour efficacement le DOM en cas de changement.

Il se peut que vous ayez déjà des questions - pas d'inquiétude. Nous allons couvrir tous les petits détails dans la suite de la documentation. Pour l'instant, veuillez lire scrupuleusement la documentation afin d'avoir une vision d'ensemble de ce que propose Vue.

:::tip Pré-requis
La suite de la documentation présuppose que vous soyez familier avec le HTML, le CSS et le JavaScript. Si vous débutez totalement dans le développement front-end, ce n'est peut-être pas la meilleure idée de vous lancer directement dans un framework pour vos premiers pas. Apprenez les bases puis revenez ! Vous pouvez consolider votre niveau de connaissance avec ces aperçus pour [JavaScript](https://developer.mozilla.org/fr/docs/Web/JavaScript/Guide/Introduction), [HTML](https://developer.mozilla.org/fr/docs/Learn/HTML/Introduction_to_HTML) et [CSS](https://developer.mozilla.org/fr/docs/Learn/CSS/First_steps) si nécessaire. Une précédente expérience avec d'autres frameworks vous aidera, mais n'est pas strictement requise.
:::

## Le Framework Évolutif {#the-progressive-framework}

Vue est un framework et un écosystème qui couvre la plupart des fonctionnalités courantes nécessaires au développement front-end. Le Web est très diversifié; les choses que nous y construisons peuvent varier radicalement. C'est pourquoi Vue a été conçu pour être flexible et adoptable de manière incrémentale. En fonction de votre cas d'utilisation, Vue peut être utilisé de différentes manières :

* Extension du HTML statique sans étape de construction
* Intégration de Web Components (éléments personnalisés) sur n'importe quelle page
* Application mono-page (SPA)
* Fullstack / Rendu côté serveur (SSR)
* JAMStack / Génération de sites statiques (SSG)
* Adapté pour l'ordinateur de bureau, le mobile, pour le WebGL et même le terminal.

Si vous trouvez ces concepts intimidants, ne vous inquiétez pas ! Le tutoriel et le guide ne requièrent que des connaissances de base en HTML et en JavaScript, et vous devriez pouvoir les suivre sans être un expert dans l'un de ces domaines.

Si vous êtes un développeur expérimenté et que vous souhaitez savoir comment intégrer au mieux Vue dans vos outils, ou si vous êtes curieux de savoir ce que ces termes signifient, nous en parlons plus en détail dans [Les manières d'utiliser Vue](/guide/extras/ways-of-using-vue).

Malgré la flexibilité, les connaissances de base sur le fonctionnement de Vue sont partagées dans tous ces cas d'utilisation. Même si vous n'êtes qu'à vos débuts, les connaissances acquises en cours de route vous seront utiles pour atteindre des objectifs plus ambitieux à l'avenir. Si vous avez un niveau expérimenté, vous pouvez choisir la manière optimale de tirer parti de Vue en fonction des problèmes que vous essayez de résoudre, tout en conservant la même productivité. C'est pourquoi nous appelons Vue "le framework évolutif" : c'est un framework qui peut grandir avec vous et s'adapter à vos besoins.

## Composant monofichier (Single-File Components) {#single-file-components}

Dans la plupart des projets Vue dotés d'outils de construction, nous créons des composants Vue en utilisant un format de fichier semblable à HTML appelé **Composant monofichier**, ou **Single-File Component** en anglais (également connu sous le nom de fichiers `*.vue`, abrégé en **SFC**). Un SFC Vue, comme son nom l'indique, encapsule la logique (JavaScript), le modèle (HTML) et les styles (CSS) du composant dans un seul fichier. Voici l'exemple précédent, écrit au format SFC :

```vue
<script>
export default {
  data() {
    return {
      count: 0
    }
  }
}
</script>

<template>
  <button @click="count++">Le compteur est à {{ count }}</button>
</template>

<style scoped>
button {
  font-weight: bold;
}
</style>
```

```vue
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<template>
  <button @click="count++">Le compteur est à {{ count }}</button>
</template>

<style scoped>
button {
  font-weight: bold;
}
</style>
```

Les SFC sont une fonctionnalité essentielle de Vue, et c'est la manière recommandée de créer des composants Vue **si** votre usage justifie une configuration avancée (usant d'outils de construction). Vous pouvez en savoir plus sur le [comment et pourquoi faire des SFC](/guide/scaling-up/sfc) dans la section qui lui est consacrée - mais pour l'instant, sachez que Vue se chargera de la configuration des outils de construction pour vous.

## Styles d'API {#api-styles}

Les composants Vue peuvent être créés dans deux styles d'API différents : l'**Options API** et la **Composition API**.

### Options API {#options-api}

Avec l'Options API, nous définissons la logique d'un composant en utilisant un objet d'options telles que `data`, `methods`, et `mounted`. Les propriétés définies par les options sont exposées sur `this` dans les fonctions, qui pointe sur l'instance du composant :

```vue
<script>
export default {
  // état réactif
  data() {
    return {
      count: 0
    }
  },

  // Les méthodes sont des fonctions qui modifient l'état et déclenchent des mises à jour
  // Elles peuvent être utilisées par des gestionnaires d'événements dans le template.
  methods: {
    increment() {
      this.count++
    }
  },

  // hooks de cycle de vie
  mounted() {
    console.log(`La valeur initiale de count est ${this.count}.`)
  }
}
</script>

<template>
  <button @click="increment">Count is: {{ count }}</button>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNptUEtOwzAQvcooQqJVUcK6ChWILUfIosaZkKGOHexxBYpyF7Y9Ry7GOOlng2TZ80bzPuMhe+n7/Bgx22Zl0J563lUWv3vnGWpsVDQMQ2UBigKmEysGP52UZmpSs1asVutlAMAjR28vCEC7aHkLjwse0zM+VPas1jgrMs4G+IoEnaupIbQM5n7xQQkwnbRBq9vUrzFAR0Hu6Rc+XfRJp0NuXR22F1Oy2mMn47dUANxSyOcwm83/WVrnDkEcQP+IYSqOhLN+YmF9U9MS2BnMjftY7d9kThmMXnyJScpZI3EAA8PdcLMe8/16dq2snLK4frYAxq43ilEQQPkemZ2FZ21IH56q7LpTle1eZ21KCw9no3Esi4Ui9LK4amXjH+vhpTQ=)

### Composition API {#composition-api}

Avec la Composition API, nous définissons la logique d'un composant à l'aide de fonctions API importées. Dans les SFC, la Composition API est généralement utilisée avec [`<script setup>`](/api/sfc-script-setup). L'attribut `setup` est une indication qui permet à Vue d'effectuer des transformations au moment de la compilation, ce qui nous permet d'utiliser la Composition API avec moins de code nécessaire aux déclarations. Par exemple, les importations et les variables / fonctions déclarées au niveau racine dans `<script setup>` sont directement utilisables dans le modèle.

Voici le même composant, avec exactement le même modèle, mais en utilisant la Composition API et `<script setup>` à la place :

```vue
<script setup>
import { ref, onMounted } from 'vue'

// état réactif
const count = ref(0)

// fonctions qui modifient l'état et déclenchent des mises à jour
function increment() {
  count.value++
}

// hooks de cycle de vie
onMounted(() => {
  console.log(`La valeur initiale de count est ${count.value}.`)
})
</script>

<template>
  <button @click="increment">Count is: {{ count }}</button>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNo9UF1OwzAMvopVIa3TUMvz1E0gXuEGeVhJXRaWOiVxJqEqd+F15+jFcNvRh0S28/3k85C99H1xjZjtsypob3qGgBz7oyLT9c4zDOCxfQRH7y4SYwMJWu862Ahro0hRWcJ445rBj7das2kVaUeBQU8EOEz8/Gl7h7aOBCPv8B0NdK4xrUGB2c0iggzNeNMWSZ+neYMBOhPkHn/hy0WvqI2LBBjSHjtB5VsYFMHiWFxrG3G3U5TunmfnLiIE+kd0p+JqUNGaKBf64fivQMFZLKz7zE9vgqwtRi9Oho2Us8ocCyXgw8BnE4p5kIqTRExyqnJZpKxQGsautzWjdADVR2SWjz9ra/TloLI1gcqOr7OuCXsYhrtJSlW5UIRelatWlv4ArcWg0Q==)

### Laquelle choisir ? {#which-to-choose}

Tout d'abord, les deux styles d'API sont parfaitement capables de couvrir les cas d'utilisation courants. Il s'agit de différentes interfaces alimentées par le même système sous-jacent. En fait, l'Options API est implémentée par dessus la Composition API ! Les concepts fondamentaux et les connaissances sur Vue sont partagés entre les deux styles.

L'Options API est centrée sur le concept d'une "instance de composant" (`this` comme dans l'exemple), qui s'aligne généralement mieux sur un modèle mental basé sur les classes pour les utilisateurs issus de la POO. Elle est également plus adaptée aux débutants, car elle fait abstraction des détails de la réactivité et impose une organisation du code par le biais de groupes d'options.

La Composition API est centrée sur la déclaration de variables d'état réactives directement dans la portée d'une fonction, et sur la composition de l'état de plusieurs fonctions pour gérer la complexité. Elle offre une plus grande liberté d'écriture et nécessite une compréhension du fonctionnement de la réactivité dans Vue pour être utilisée efficacement. En retour, sa flexibilité permet des modèles plus puissants pour organiser et réutiliser la logique.

Pour en savoir plus sur la comparaison entre les deux styles et les avantages potentiels de la Composition API, consultez la [FAQ sur la Composition API](/guide/extras/composition-api-faq).

Si Vue est nouveau pour vous, voici notre recommandation générale :

* Pour l'apprentissage, choisissez le style qui vous semble le plus facile à comprendre. Encore une fois, la plupart des concepts fondamentaux sont partagés entre les deux styles. Vous pourrez toujours choisir l'autre style plus tard.

* Pour une utilisation en production :

  * Optez pour l'Options API si vous n'utilisez pas d'outils de construction ou si vous prévoyez d'utiliser Vue principalement dans des scénarios peu complexes, par exemple par une amélioration progressive de votre projet.

  * Choisissez la Composition API + les composants monofichiers (SFC) si vous envisagez de créer des applications complètes avec Vue.

Vous n'avez pas à vous engager dans un seul style pendant la phase d'apprentissage. Le reste de la documentation fournira des exemples de code dans les deux styles, et vous pourrez passer de l'un à l'autre à tout moment à l'aide du bouton **Préférence d'API** en haut de la barre latérale gauche.

## Encore des questions ? {#still-got-questions}

Consultez notre [FAQ](/about/faq).

## Choisissez votre parcours d'apprentissage {#pick-your-learning-path}

Chaque développeur a un style d'apprentissage différent. N'hésitez pas à choisir le parcours d'apprentissage qui vous convient le mieux, même si nous vous recommandons de revoir l'ensemble du contenu si possible !

---

---
url: /guide/built-ins/keep-alive.md
---
# KeepAlive {#keepalive}

`<KeepAlive>` est un composant natif qui nous permet de garder en cache des instances d'un composant de manière conditionnelle tout en switchant entre plusieurs composants de manière dynamique.

## Utilisation basique {#basic-usage}

Dans le chapitre sur les principes fondamentaux des composants, nous avons présenté la syntaxe pour les [Composants Dynamiques](/guide/essentials/component-basics#dynamic-components), en utilisant l'élément spécial `<component>` :

```vue-html
<component :is="activeComponent" />
```

Par défaut, une instance du composant actif est démontée lorsqu'on le change. Cela entraîne la perte de tout état modifié qu'elle comporte. Lorsque ce composant est affiché à nouveau, une nouvelle instance sera créée avec uniquement l'état initial.

Dans l'exemple ci-dessous, nous avons deux composants ayant un état - A contient un compteur, tandis que B contient un message synchronisé avec une entrée via `v-model`. Essayez de mettre à jour l'état de l'un d'entre eux, changez de page, puis revenez :

Vous remarquerez qu'au retour, l'état modifié précédent a été réinitialisé.

La création d'une nouvelle instance de composant lors du changement est normalement un comportement utile, mais dans ce cas, nous aimerions vraiment que les deux instances de composant soient préservées même lorsqu'elles sont inactives. Pour résoudre ce problème, nous pouvons envelopper notre composant dynamique avec le composant natif `<KeepAlive>` :

```vue-html
<!-- Les composants inactifs seront mis en cache ! -->
<KeepAlive>
  <component :is="activeComponent" />
</KeepAlive>
```

Maintenant, l'état sera persistant à travers les changements de composants :

[Essayer en ligne](https://play.vuejs.org/#eNqtUsFOwzAM/RWrl4IGC+cqq2h3RFw495K12YhIk6hJi1DVf8dJSllBaAJxi+2XZz8/j0lhzHboeZIl1NadMA4sd73JKyVaozsHI9hnJqV+feJHmODY6RZS/JEuiL1uTTEXtiREnnINKFeAcgZUqtbKOqj7ruPKwe6s2VVguq4UJXEynAkDx1sjmeMYAdBGDFBLZu2uShre6ioJeaxIduAyp0KZ3oF7MxwRHWsEQmC4bXXDJWbmxpjLBiZ7DwptMUFyKCiJNP/BWUbO8gvnA+emkGKIgkKqRrRWfh+Z8MIWwpySpfbxn6wJKMGV4IuSs0UlN1HVJae7bxYvBuk+2IOIq7sLnph8P9u5DJv5VfpWWLaGqTzwZTCOM/M0IaMvBMihd04ruK+lqF/8Ajxms8EFbCiJxR8khsP6ncQosLWnWV6a/kUf2nqu75Fby04chA0iPftaYryhz6NBRLjdtajpHZTWPio=)

[Essayer en ligne](https://play.vuejs.org/#eNqtU8tugzAQ/JUVl7RKWveMXFTIseofcHHAiawasPxArRD/3rVNSEhbpVUrIWB3x7PM7jAkuVL3veNJmlBTaaFsVraiUZ22sO0alcNedw2s7kmIPHS1ABQLQDEBAMqWvwVQzffMSQuDz1aI6VreWpPCEBtsJppx4wE1s+zmNoIBNLdOt8cIjzut8XAKq3A0NAIY/QNveFEyi8DA8kZJZjlGALQWPVSSGfNYJjVvujIJeaxItuMyo6JVzoJ9VxwRmtUCIdDfNV3NJWam5j7HpPOY8BEYkwxySiLLP1AWkbK4oHzmXOVS9FFOSM3jhFR4WTNfRslcO54nSwJKcCD4RsnZmJJNFPXJEl8t88quOuc39fCrHalsGyWcnJL62apYNoq12UQ8DLEFjCMy+kKA7Jy1XQtPlRTVqx+Jx6zXOJI1JbH4jejg3T+KbswBzXnFlz9Tjes/V/3CjWEHDsL/OYNvdCE8Wu3kLUQEhy+ljh+brFFu)

:::tip
Lorsqu'il est utilisé dans les [templates du DOM](/guide/essentials/component-basics#in-dom-template-parsing-caveats), il doit être référencé comme `<keep-alive>`.
:::

## Include / Exclude {#include-exclude}

Par défaut, `<KeepAlive>` va mettre en cache toute instance de composant qu'il contient. Nous pouvons personnaliser ce comportement via les props `include` et `exclude`. Ces deux options peuvent être une chaîne de caractères délimitée par des virgules, une `RegExp`, ou un tableau contenant l'un ou l'autre type :

```vue-html
<!-- chaîne de caractères délimitée par des virgules -->
<KeepAlive include="a,b">
  <component :is="view" />
</KeepAlive>

<!-- regex (utilisez `v-bind`) -->
<KeepAlive :include="/a|b/">
  <component :is="view" />
</KeepAlive>

<!-- Tableau (utilisez `v-bind`) -->
<KeepAlive :include="['a', 'b']">
  <component :is="view" />
</KeepAlive>
```

La correspondance se fait par rapport à l'option [`name`](/api/options-misc#name) du composant, de sorte que les composants qui doivent être mis en cache de manière conditionnelle par `KeepAlive` doivent déclarer explicitement une option `name`.

:::tip
Depuis la version 3.2.34, un composant monofichier utilisant `<script setup>` déduira automatiquement son option `name` en fonction du nom du fichier, supprimant ainsi le besoin de déclarer manuellement le nom.
:::

## Maximum d'instances mises en cache {#max-cached-instances}

Nous pouvons limiter le nombre maximum d'instances de composants qui peuvent être mises en cache via la prop `max`. Lorsque `max` est spécifié, `<KeepAlive>` se comporte comme un [cache LRU](https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_\(LRU\)) : si le nombre d'instances mises en cache est sur le point de dépasser le nombre maximum spécifié, l'instance mise en cache la moins récemment activée sera détruite pour faire place à la nouvelle.

```vue-html
<KeepAlive :max="10">
  <component :is="activeComponent" />
</KeepAlive>
```

## Cycle de vie des instances mises en cache {#lifecycle-of-cached-instance}

Lorsqu'une instance de composant est supprimée du DOM mais fait partie d'un arbre de composants mis en cache par `<KeepAlive>`, elle passe dans un état **désactivé** au lieu d'être démontée. Lorsqu'une instance de composant est insérée dans le DOM en tant que partie d'un arbre mis en cache, elle est **activée**.

Un composant maintenu en vie peut enregistrer des hooks de cycle de vie pour ces deux états en utilisant [`onActivated()`](/api/composition-api-lifecycle#onactivated) et [`onDeactivated()`](/api/composition-api-lifecycle#ondeactivated) :

```vue
<script setup>
import { onActivated, onDeactivated } from 'vue'

onActivated(() => {
  // appelé au premier montage
  // et à chaque fois qu'il est réinséré depuis le cache
})

onDeactivated(() => {
  // appelé lorsqu'il est retiré du DOM et mis en cache
  // et également lorsqu'il est démonté
})
</script>
```

Un composant maintenu en vie peut enregistrer des hooks de cycle de vie pour ces deux états en utilisant les hooks [`activated`](/api/options-lifecycle#activated) et [`deactivated`](/api/options-lifecycle#deactivated) :

```js
export default {
  activated() {
    // appelé au premier montage
    // et à chaque fois qu'il est réinséré depuis le cache
  },
  deactivated() {
    // appelé lorsqu'il est retiré du DOM et mis en cache
    // et également lorsqu'il est démonté
  }
}
```

Notez que :

* `onActivated``activated` est également appelé au montage, et `onDeactivated``deactivated` au démontage.

* Les deux hooks fonctionnent non seulement pour le composant racine mis en cache par `<KeepAlive>`, mais aussi pour les composants enfants dans l'arbre mis en cache.

***

**Référence**

* [Référence de l'API `<KeepAlive>`](/api/built-in-components#keepalive)

---

---
url: /api/component-instance.md
---
# L'instance de composant {#component-instance}

:::info
Cette page présente les propriétés et méthodes natives exposées par l'instance de composant publique, autrement dit `this`.

Toutes les propriétés sur cette page sont en lecture seule (excepté les propriétés imbriquées dans `data`).
:::

## $data {#data}

L'objet retourné par l'option [`data`](./options-state#data), rendu réactif par le composant. L'instance de composant donne accès aux propriétés de son objet `data` via un proxy.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $data: object
  }
  ```

## $props {#props}

Un objet représentant les `props` courantes et résolues du composant.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $props: object
  }
  ```

* **Détails**

  Seules les props déclarées via l'option [`props`](./options-state#props) seront incluses. L'instance du composant donne accès aux propriétés de son objet props via un proxy.

## $el {#el}

Le nœud du DOM racine que l'instance du composant gère.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $el: any
  }
  ```

* **Détails**

  `$el` sera `undefined` jusqu'à ce que le composant soit [monté](./options-lifecycle#mounted).

  * Pour les composants avec un unique élément racine, `$el` pointera sur cet élément.
  * Pour les composants avec un élément racine `Text`, `$el` pointera sur ce nœud `Text`.
  * Pour les composants avec des nœuds racines multiples, `$el` sera un nœud du DOM fictif que Vue utilise pour suivre la position du composant dans le DOM (un nœud `Text`, ou un nœud `Comment` en mode hydratation avec rendu côté serveur).

  :::tip
  Par cohérence, il est recommandé d'utiliser [les refs de template](/guide/essentials/template-refs) pour accéder directement aux éléments du DOM plutôt que `$el`.
  :::

## $options {#options}

Les options du composant résolues utilisées pour instancier l'instance courante du composant.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $options: ComponentOptions
  }
  ```

* **Détails**

  L'objet `$options` expose les options résolues pour l'instance courante du composant et est le résultat de la fusion de trois sources possibles :

  * Mixins globaux
  * La base `extends` du composant
  * Mixins du composant

  C'est typiquement utilisé pour supporter l'ajout d'options personnalisées au composant :

  ```js
  const app = createApp({
    customOption: 'foo',
    created() {
      console.log(this.$options.customOption) // => 'foo'
    }
  })
  ```

* **Voir aussi** [`app.config.optionMergeStrategies`](/api/application#app-config-optionmergestrategies)

## $parent {#parent}

L'instance du composant parent, si l'instance courante en a une. Cette propriété vaudra `null` dans le cas du composant racine.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $parent: ComponentPublicInstance | null
  }
  ```

## $root {#root}

L'instance du composant à la racine de l'arbre de composants courant. Si l'instance de composant courante n'a pas de composants parents, cette propriété vaudra l'instance du composant elle-même.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $root: ComponentPublicInstance
  }
  ```

## $slots {#slots}

Un objet représentant les [slots](/guide/components/slots) passés par le composant parent.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $slots: { [name: string]: Slot }
  }

  type Slot = (...args: any[]) => VNode[]
  ```

* **Détails**

  Cette option est typiquement utilisée quand on créé manuellement des [fonctions de rendu](/guide/extras/render-function), mais elle peut aussi être utilisée pour détecter si un slot est présent.

  Chaque slot est exposé par `this.$slots` comme une fonction qui retourne un tableau de `VNode` sous la clé correspondant au nom de ce slot. Le slot par défaut est exposé comme `this.$slots.default`.

  Si un slot est un [scoped slot](/guide/components/slots#scoped-slots), les arguments passés à la fonction de slot sont rendus disponibles au slot en tant que props du slot.

* **Voir aussi** [Fonctions de rendu - Rendu des slots](/guide/extras/render-function#rendering-slots)

## $refs {#refs}

Un objet constitué d'éléments du DOM et d'instances de composants, enregistré via les [refs du template](/guide/essentials/template-refs).

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $refs: { [name: string]: Element | ComponentPublicInstance | null }
  }
  ```

* **Voir aussi**

  * [Les refs du template](/guide/essentials/template-refs)
  * [Attributs spéciaux - ref](./built-in-special-attributes.md#ref)

## $attrs {#attrs}

Un objet qui contient les attributs implicitement déclarés (*fallthrough attributes*) du composant.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $attrs: object
  }
  ```

* **Détails**

  Les [attributs implicitement déclarés](/guide/components/attrs) sont des attributs ou écouteurs d'événements `v-on` passés par le composant parent mais non déclarés comme prop ou émission par le composant enfant.

  Par défaut, si le composant a un unique nœud racine, tout ce qui se trouve dans `$attrs` sera automatiquement passé à ce nœud racine. Ce comportement est désactivé si le composant a des nœuds racines multiples, et peut être explicitement désactivé avec l'option [`inheritAttrs`](./options-misc#inheritattrs).

* **Voir aussi**

  * [Attributs implicitement déclarés](/guide/components/attrs)

## $watch() {#watch}

API impérative pour créer des observateurs.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $watch(
      source: string | (() => any),
      callback: WatchCallback,
      options?: WatchOptions
    ): StopHandle
  }

  type WatchCallback<T> = (
    value: T,
    oldValue: T,
    onCleanup: (cleanupFn: () => void) => void
  ) => void

  interface WatchOptions {
    immediate?: boolean // par défaut: false
    deep?: boolean // par défaut: false
    flush?: 'pre' | 'post' | 'sync' // par défaut: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
  }

  type StopHandle = () => void
  ```

* **Détails**

  Le premier argument est la source observée. Cela peut être une chaîne de caractères correspondant au nom d'une propriété du composant,  ou une fonction [accesseur](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Functions/get#description).

  Le second argument est la fonction de rappel. La fonction de rappel reçoit en paramètres la nouvelle et l'ancienne valeur de la source observée.

  * **`immediate`** : déclenche la fonction de rappel immédiatement à la création de l'observateur. L'ancienne valeur vaudra `undefined` lors du premier appel.
  * **`deep`** : force la traversée profonde de la source si c'est un objet, de sorte que la fonction de rappel se déclenche sur les mutations profondes. Voir [les observateurs profonds](/guide/essentials/watchers#deep-watchers).
  * **`flush`** : ajuste le timing de nettoyage de la fonction de rappel. Voir [timing du nettoyage des rappels](/guide/essentials/watchers#callback-flush-timing) et [`watchEffect()`](/api/reactivity-core#watcheffect).
  * **`onTrack / onTrigger`** : débogue les dépendances de l'observateur. Voir [débogage des observateur](/guide/extras/reactivity-in-depth#watcher-debugging).

* **Exemple**

  Observer via le nom d'une propriété :

  ```js
  this.$watch('a', (newVal, oldVal) => {})
  ```

  Observer via un chemin (délimité par des points) :

  ```js
  this.$watch('a.b', (newVal, oldVal) => {})
  ```

  Utiliser un accesseur pour des expressions plus complexes :

  ```js
  this.$watch(
    // à chaque fois qu'une expression `this.a + this.b` retourne
    // un résultat différent, la fonction de rappel sera appelée.
    // C'est comme si on observait une propriété calculée
    // sans définir la propriété calculée en question.
    () => this.a + this.b,
    (newVal, oldVal) => {}
  )
  ```

  Arrêter l'observateur :

  ```js
  const unwatch = this.$watch('a', cb)

  // later...
  unwatch()
  ```

* **Voir aussi**
  * [Options - `watch`](/api/options-state#watch)
  * [Guide - Observateurs](/guide/essentials/watchers)

## $emit() {#emit}

Émet un événement personnalisé depuis l'instance courante. Tout argument additionnel sera passé à la fonction de rappel.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $emit(event: string, ...args: any[]): void
  }
  ```

* **Exemple**

  ```js
  export default {
    created() {
      // événement seul
      this.$emit('foo')
      // avec des arguments additionnels
      this.$emit('bar', 1, 2, 3)
    }
  }
  ```

* **Voir aussi**

  * [Composant - Gestion des événements](/guide/components/events)
  * [L'option `emits`](./options-state#emits)

## $forceUpdate() {#forceupdate}

Force l'instance du composant à effectuer un nouveau rendu.

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $forceUpdate(): void
  }
  ```

* **Détails**

  Ceci devrait être rarement nécessaire grâce au système de réactivité entièrement automatique de Vue. Le seul cas où vous devriez en avoir besoin est celui où vous auriez créé un composant à l'état explicitement non-réactif en utilisant des API de réactivité avancées.

## $nextTick() {#nexttick}

Version propre à l'instance de l'utilité globale [`nextTick()`](./general#nexttick).

* **Type :**

  ```ts
  interface ComponentPublicInstance {
    $nextTick(callback?: (this: ComponentPublicInstance) => void): Promise<void>
  }
  ```

* **Détails**

  La seule différence avec la version globale de `nextTick()` est que la fonction de rendu passée à `this.$nextTick()` aura son contexte `this` lié à l'instance courante du composant.

* **Voir aussi** [`nextTick()`](./general#nexttick)

---

---
url: /guide/extras/reactivity-in-depth.md
---

# La réactivité en détails {#reactivity-in-depth}

L'une des caractéristiques les plus distinctives de Vue est son système de réactivité discret. L'état des composants est constitué d'objets JavaScript réactifs. Lorsque vous les modifiez, la vue se met à jour. Cela rend la gestion de l'état simple et intuitive, mais il est toutefois important de comprendre comment cela fonctionne pour éviter certains problèmes courants. Dans cette section, nous allons nous pencher sur certains détails de bas niveau du système de réactivité de Vue.

## Qu'est-ce que la réactivité ? {#what-is-reactivity}

De nos jours, ce terme revient fréquemment lorsqu'on parle de programmation, mais que veulent vraiment dire les gens lorsqu'ils le prononcent ? La réactivité est un paradigme de programmation qui nous permet de nous adapter aux changements de manière déclarative. L'exemple canonique que les gens utilisent habituellement, parce qu'il est excellent, est une feuille de calcul Excel :

Ici, la cellule A2 est définie par une formule `= A0 + A1` (vous pouvez cliquer sur A2 pour afficher ou modifier la formule), donc le tableur nous donne 3. Pas de surprise ici. Mais si vous mettez à jour A0 ou A1, vous remarquerez que A2 se met automatiquement à jour, comme par magie.

JavaScript ne fonctionne généralement pas de cette manière. Si nous devions écrire quelque chose d'équivalent dans ce langage :

```js
let A0 = 1
let A1 = 2
let A2 = A0 + A1

console.log(A2) // 3

A0 = 2
console.log(A2) // Toujours 3
```

Lorsque nous modifions `A0`, `A2` ne change pas automatiquement.

Alors comment faire en JavaScript ? Tout d'abord, afin de ré-exécuter le code qui met à jour `A2`, enveloppons-le dans une fonction :

```js
let A2

function update() {
  A2 = A0 + A1
}
```

Ensuite, nous devons définir quelques termes :

* La fonction `update()` produit un **effet de bord**, ou **effet** pour faire court, car elle modifie l'état du programme.

* `A0` et `A1` sont considérées comme des **dépendances** de l'effet, puisque leurs valeurs sont utilisées pour le réaliser. On dit que l'effet est un **souscripteur** de ses dépendances.

Ce dont nous avons besoin, c'est d'une fonction magique qui puisse invoquer `update()` (l'**effet**) chaque fois que `A0` ou `A1` (les **dépendances**) changent :

```js
whenDepsChange(update)
```

Cette fonction `whenDepsChange()` assure les tâches suivantes :

1. Traquer quand une variable est lue. Par exemple, lors de l'évaluation de l'expression `A0 + A1`, les deux variables `A0` et `A1` sont lues.

2. Si une variable est lue lorsqu'il y a un effet en cours d'exécution, abonner cet effet à cette variable. Par exemple, comme `A0` et `A1` sont lues lorsque `update()` est en cours d'exécution, `update()` devient abonné à la fois à `A0` et `A1` après le premier appel.

3. Détecter quand une variable est mutée. Par exemple, lorsqu'une nouvelle valeur est attribuée à `A0`, il faut notifier à tous ses effets abonnés de s'exécuter à nouveau.

## Fonctionnement de la réactivité dans Vue {#how-reactivity-works-in-vue}

Nous ne pouvons pas tout à fait suivre la lecture et l'écriture des variables locales comme dans l'exemple. Il n'y a tout simplement pas de mécanisme pour le faire avec du JavaScript classique. Ce que nous **pouvons** faire cependant, c'est intercepter la lecture et l'écriture des **propriétés d'un objet**.

Il existe deux façons d'intercepter l'accès aux propriétés en JavaScript : [les accesseurs](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Functions/get) / [les mutateurs](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Functions/set) et [les proxys](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Vue 2 utilisait exclusivement les accesseurs / mutateurs en raison des limitations de prise en charge du navigateur. Dans Vue 3, les proxys sont utilisés pour les objets réactifs et les accesseurs / mutateurs sont utilisés pour les refs. Voici un pseudo-code qui illustre leur fonctionnement :

```js{4,9,17,22}
function reactive(obj) {
  return new Proxy(obj, {
    get(target, key) {
      track(target, key)
      return target[key]
    },
    set(target, key, value) {
      target[key] = value
      trigger(target, key)
    }
  })
}

function ref(value) {
  const refObject = {
    get value() {
      track(refObject, 'value')
      return value
    },
    set value(newValue) {
      value = newValue
      trigger(refObject, 'value')
    }
  }
  return refObject
}
```

:::tip
Ces extraits de code et ceux situés ci-dessous ont pour but d'expliquer les concepts de base de la manière la plus simple possible, c'est pourquoi de nombreux détails sont omis et les cas limites ignorés.
:::

Cela explique certaines [limitations des objets réactifs](/guide/essentials/reactivity-fundamentals#limitations-of-reactive) que nous avons abordées dans la section sur les principes fondamentaux :

* Lorsque vous assignez ou déstructurez la propriété d'un objet réactif à une variable locale, l'accès ou l'affectation à cette variable est non réactif car il ne déclenche plus les interruptions de proxy get/set sur l'objet source. Notez que cette "déconnexion" n'affecte que la liaison de variable - si la variable pointe vers une valeur non primitive telle qu'un objet, la mutation de l'objet serait toujours réactive.

* Le proxy retourné par `reactive()`, bien que se comportant comme l'original, n'a pas la même identité lorsqu'on le compare à ce dernier en utilisant l'opérateur `===`.

Dans `track()`, nous vérifions s'il existe un effet en cours d'exécution. S'il y en a un, nous recherchons les effets abonnés (stockés dans un Set) à la propriété suivie, et ajoutons l'effet au Set :

```js
// Cela sera défini juste avant qu'un effet soit sur le point
// d'être exécuté. Nous nous en occuperons plus tard.
let activeEffect

function track(target, key) {
  if (activeEffect) {
    const effects = getSubscribersForProperty(target, key)
    effects.add(activeEffect)
  }
}
```

Les abonnements aux effets sont stockés dans une structure de données globale `WeakMap<target, Map<key, Set<effect>>`. Si aucun Set d'effets souscripteurs n'a été trouvé pour une propriété (suivie pour la première fois), il sera créé. C'est en résumé ce que fait la fonction `getSubscribersForProperty()`. Pour plus de simplicité, nous n'entrerons pas dans les détails.

Dans `trigger()`, nous recherchons à nouveau les effets abonnés à la propriété. Mais cette fois, nous les invoquons :

```js
function trigger(target, key) {
  const effects = getSubscribersForProperty(target, key)
  effects.forEach((effect) => effect())
}
```

Maintenant, revenons à la fonction `whenDepsChange()` :

```js
function whenDepsChange(update) {
  const effect = () => {
    activeEffect = effect
    update()
    activeEffect = null
  }
  effect()
}
```

Elle enveloppe la fonction brute `update` dans un effet étant l'effet actif actuel avant d'exécuter la mise à jour correspondante. Cela permet aux appels `track()` pendant la mise à jour de localiser l'effet actif actuel.

À ce stade, nous avons créé un effet qui traque automatiquement ses dépendances et qui s'exécute à nouveau dès qu'une d'elles change. Nous appelons cela un **effet réactif**.

Vue fournit une API qui vous permet de créer des effets réactifs : [`watchEffect()`](/api/reactivity-core#watcheffect). En fait, vous avez peut-être remarqué qu'elle fonctionne de manière assez similaire à la fonction magique `whenDepsChange()` de l'exemple. Nous pouvons maintenant retravailler l'exemple original en utilisant les API de Vue :

```js
import { ref, watchEffect } from 'vue'

const A0 = ref(0)
const A1 = ref(1)
const A2 = ref()

watchEffect(() => {
  // traque A0 et A1
  A2.value = A0.value + A1.value
})

// déclenche l'effet
A0.value = 2
```

L'utilisation d'un effet réactif pour modifier une ref n'est pas le cas d'utilisation le plus intéressant - en fait, l'utilisation d'une propriété calculée rend cela plus déclaratif :

```js
import { ref, computed } from 'vue'

const A0 = ref(0)
const A1 = ref(1)
const A2 = computed(() => A0.value + A1.value)

A0.value = 2
```

En interne, `computed` gère son invalidation et son re-calcul en utilisant un effet réactif.

Alors, quel pourrait être un exemple d'un effet réactif courant et utile ? Et bien, la mise à jour du DOM ! Nous pouvons implémenter un simple "rendu réactif" de cette manière :

```js
import { ref, watchEffect } from 'vue'

const count = ref(0)

watchEffect(() => {
  document.body.innerHTML = `Count est égal à: ${count.value}`
})

// met à jour le DOM
count.value++
```

En fait, cela est assez proche de la façon dont un composant Vue maintient l'état et le DOM synchronisés - chaque instance de composant crée un effet réactif pour rendre et mettre à jour le DOM. Bien sûr, les composants Vue utilisent des moyens beaucoup plus efficaces pour mettre à jour le DOM que `innerHTML`. Ce point est abordé dans [Mécanismes de rendu](./rendering-mechanism).

Les API `ref()`, `computed()` et `watchEffect()` font toutes partie de la Composition API. Si vous n'avez utilisé que l'Options API avec Vue jusqu'à présent, vous remarquerez que la Composition API est plus proche de la façon dont le système de réactivité de Vue fonctionne sous le capot. En fait, dans Vue 3, l'Options API est mise en œuvre par dessus la Composition API. Tous les accès aux propriétés de l'instance du composant (`this`) déclenchent des accesseurs / mutateurs pour le suivi de la réactivité, et les options comme `watch` et `computed` invoquent leurs équivalents de la Composition API en interne.

## Réactivité à l'exécution vs. à la compilation {#runtime-vs-compile-time-reactivity}

Le système de réactivité de Vue est principalement basé sur l'exécution : la traque et le déclenchement sont tous deux effectués pendant l'exécution du code, directement dans le navigateur. Les avantages de la réactivité d'exécution sont qu'elle peut fonctionner sans outil de build et qu'il y a moins de cas limites. En revanche, elle est limitée par les contraintes syntaxiques de JavaScript nécessitant l'usage de conteneur de valeur comme pour les refs de Vue.

Certains frameworks, tels que [Svelte](https://svelte.dev/), choisissent de surmonter ces limitations en implémentant la réactivité lors de la compilation. Svelte analyse et transforme le code afin de simuler la réactivité. La compilation permet au framework de modifier la sémantique de JavaScript lui-même - par exemple, en injectant implicitement du code qui effectue une analyse de dépendance et un déclenchement d'effet autour de l'accès à des variables définies localement. L'inconvénient est que de telles transformations nécessitent un outil de build, et la modification de la sémantique JavaScript crée essentiellement un langage qui ressemble à JavaScript mais se compile en quelque chose d'autre.

L'équipe Vue a exploré cette piste via une fonctionnalité expérimentale appelée [Reactivity Transform](/guide/extras/reactivity-transform), mais en fin de compte, nous avons décidé que cela ne conviendrait pas au projet pour [les raisons énoncées ici](https://github.com/vuejs/rfcs/discussions/369#discussioncomment-5059028).

Le résultat de la compilation de cet extrait de code sera le même que celui résultant de ce que nous aurions écrit sans la transformation, via l'ajout automatique de `.value` après les références aux variables. Avec Reactivity Transform, le système de réactivité de Vue devient un système hybride.

## Déboguer la réactivité {#reactivity-debugging}

C'est une bonne chose que le système de réactivité de Vue traque automatiquement les dépendances, mais dans certains cas, il se peut que nous voulions savoir exactement ce qui est traqué, ou ce qui provoque le nouveau rendu d'un composant.

### Hooks de débogage des composants {#component-debugging-hooks}

Nous pouvons vérifier quelles dépendances sont utilisées pendant le rendu d'un composant et quelle dépendance déclenche une mise à jour à l'aide des hooks de cycle de vie `renderTracked``onRenderTracked` et `renderTriggered``onRenderTriggered`. Les deux hooks recevront un événement de débogage qui contient des informations sur la dépendance en question. Il est recommandé de placer une instruction `debugger` dans les fonctions de rappel pour inspecter de manière interactive la dépendance :

```vue
<script setup>
import { onRenderTracked, onRenderTriggered } from 'vue'

onRenderTracked((event) => {
  debugger
})

onRenderTriggered((event) => {
  debugger
})
</script>
```

```js
export default {
  renderTracked(event) {
    debugger
  },
  renderTriggered(event) {
    debugger
  }
}
```

:::tip
Les hooks de débogage des composants ne fonctionnent qu'en mode développement.
:::

Les objets d'événements de débogage ont le type suivant :

```ts
type DebuggerEvent = {
  effect: ReactiveEffect
  target: object
  type:
    | TrackOpTypes /* 'get' | 'has' | 'iterate' */
    | TriggerOpTypes /* 'set' | 'add' | 'delete' | 'clear' */
  key: any
  newValue?: any
  oldValue?: any
  oldTarget?: Map<any, any> | Set<any>
}
```

### Débogage des propriétés calculées {#computed-debugging}

Nous pouvons déboguer les propriétés calculées en passant à `computed()` un second objet d'options avec des fonctions de rappel `onTrack` et `onTrigger` :

* `onTrack` sera appelée lorsqu'une propriété ou une ref réactive sera traquée en tant que dépendance.
* `onTrigger` sera appelée lorsque la fonction de rappel de l'observateur sera déclenchée par la mutation d'une dépendance.

Les deux fonctions de rappel recevront les événements du débogueur dans le [même format](#debugger-event) que les hooks de débogage des composants :

```js
const plusOne = computed(() => count.value + 1, {
  onTrack(e) {
    // déclenchée lorsque count.value est traquée en tant que dépendance
    debugger
  },
  onTrigger(e) {
    // déclenchée lorsque count.value est mutée
    debugger
  }
})

// accès à plusOne, devrait déclencher onTrack
console.log(plusOne.value)

// mutation de count.value, devrait déclencher onTrigger
count.value++
```

:::tip
Les propriétés calculées `onTrack` et `onTrigger` ne fonctionnent qu'en mode développement.
:::

### Débogage des observateurs {#watcher-debugging}

Comme pour `computed()`, les observateurs prennent aussi en charge les options `onTrack` et `onTrigger` :

```js
watch(source, callback, {
  onTrack(e) {
    debugger
  },
  onTrigger(e) {
    debugger
  }
})

watchEffect(callback, {
  onTrack(e) {
    debugger
  },
  onTrigger(e) {
    debugger
  }
})
```

:::tip
Les options d'observation `onTrack` et `onTrigger` ne fonctionnent qu'en mode développement.
:::

## Intégration avec des systèmes externes de gestion d'état {#integration-with-external-state-systems}

Le système de réactivité de Vue fonctionne en convertissant en profondeur les objets JavaScript simples en proxys réactifs. Cette conversion profonde peut s'avérer inutile ou parfois indésirable lors de l'intégration avec des systèmes externes de gestion d'état (par exemple, si une solution externe utilise également des proxys).

L'idée générale derrière l'intégration du système de réactivité de Vue avec une solution externe de gestion d'état est de conserver l'état externe dans un [`shallowRef`](/api/reactivity-advanced#shallowref). Une ref partiellement réactive n'est réactive que lorsqu'on accède à sa propriété `.value` - la valeur interne reste intacte. Lorsque l'état externe change, remplacez la valeur de la ref pour déclencher les mises à jour.

### Données persistantes {#immutable-data}

Si vous mettez en œuvre une fonctionnalité d'annulation et de rétablissement, vous souhaitez probablement avoir un instantané de l'état de l'application à chaque modification de l'utilisateur. Cependant, le système de réactivité mutable de Vue n'est pas le mieux adapté si l'arbre d'état est grand, car la sérialisation de l'objet d'état entier à chaque mise à jour peut être coûteuse en termes de coûts de CPU et de mémoire.

Les [structures de données persistantes](https://fr.wikipedia.org/wiki/Structure_de_donn%C3%A9es_persistante) résolvent ce problème en ne modifiant jamais les objets d'état - au lieu de cela, elles créent de nouveaux objets qui partagent les mêmes parties persistantes avec les anciens. Il existe différentes façons d'utiliser des données persistantes en JavaScript, mais nous recommandons d'utiliser [Immer](https://immerjs.github.io/immer/) avec Vue car il vous permet d'utiliser des données persistantes tout en conservant une syntaxe de mutation plus ergonomique.

Nous pouvons intégrer Immer avec Vue via un simple composable :

```js
import { produce } from 'immer'
import { shallowRef } from 'vue'

export function useImmer(baseState) {
  const state = shallowRef(baseState)
  const update = (updater) => {
    state.value = produce(state.value, updater)
  }

  return [state, update]
}
```

[Essayer en ligne](https://play.vuejs.org/#eNp9VMFu2zAM/RXNl6ZAYnfoTlnSdRt66DBsQ7vtEuXg2YyjRpYEUU5TBPn3UZLtuE1RH2KLfCIfycfsk8/GpNsGkmkyw8IK4xiCa8wVV6I22jq2Zw3CbV2DZQe2srpmZ2km/PmMK8a4KrRCxxbCQY1j1pgyd3DrD0s27++OFh689z/0OOEkTBlPvkNuFfvbAE/Gra/UilzOko0Mh2A+ufcHwd9ij8KtWUjwMsAqlxgjcLU854qrVaMKJ7RiTleVDBRHQpWwO4/xB8xHoRg2v+oyh/MioJepT0ClvTsxhnSUi1LOsthN6iMdCGgkBacTY7NGhjd9ScG2k5W2c56M9rG6ceBPdbOWm1AxO0/a+uiZFjJHpFv7Fj10XhdSFBtyntTJkzaxf/ZtQnYguoFNJkUkmAWGs2xAm47onqT/jPWHxjjYuUkJhba57+yUSaFg4tZWN9X6Y9eIcC8ZJ1FQkzo36QNqRZILQXjroAqnXb+9LQzVD3vtnMFpljXKbKq00HWU3/X7i/QivcxKgS5aUglVXjxNAGvK8KnWZSNJWa0KDoGChzmk3L28jSVcQX1o1d1puwfgOpdSP97BqsfQxhCCK9gFTC+tXu7/coR7R71rxRWXBL2FpHOMOAAeYVGJhBvFL3s+kGKIkW5zSfKfd+RHA2u3gzZEpML9y9JS06YtAq5DLFmOMWXsjkM6rET1YjzUcSMk2J/G1/h8TKGOb8HmV7bdQbqzhmLziv0Bd3Govywg2O1x8Umvua3ARffN/Q/S1sDZDfMN5x2glo3nGGFfGlUS7QEusL0NcxWq+o03OwcKu6Ke/+fwhIb89Y3Sj3Qv0w+9xg7/AWfvyMs=)

### Machines d'état {#state-machines}

[Une machine d'état](https://developer.mozilla.org/fr/docs/Glossary/State_machine) est un modèle permettant de décrire tous les états possibles d'une application et toutes les façons possibles de passer d'un état à un autre. Bien qu'il puisse être excessif pour les composants simples, il peut aider à rendre les flux d'états complexes plus robustes et plus faciles à gérer.

L'une des implémentations de machine d'état les plus populaires en JavaScript est [XState](https://xstate.js.org/). Voici un composable qui s'intègre avec :

```js
import { createMachine, interpret } from 'xstate'
import { shallowRef } from 'vue'

export function useMachine(options) {
  const machine = createMachine(options)
  const state = shallowRef(machine.initialState)
  const service = interpret(machine)
    .onTransition((newState) => (state.value = newState))
    .start()
  const send = (event) => service.send(event)

  return [state, send]
}
```

[Essayer en ligne](https://play.vuejs.org/#eNp1U81unDAQfpWRL7DSFqqqUiXEJumhyqVVpDa3ugcKZtcJjC1syEqId8/YBu/uIRcEM9/P/DGz71pn0yhYwUpTD1JbMMKO+o6j7LUaLMwwGvGrqk8SBSzQDqqHJMv7EMleTMIRgGOt0Fj4a2xlxZ5EsPkHhytuOjucbApIrDoeO5HsfQCllVVHUYlVbeW0xr2OKcCzHCwkKQAK3fP56fHx5w/irSyqbfFMgA+h0cKBHZYey45jmYfeqWv6sKLXHbnTF0D5f7RWITzUnaxfD5y5ztIkSCY7zjwKYJ5DyVlf2fokTMrZ5sbZDu6Bs6e25QwK94b0svgKyjwYkEyZR2e2Z2H8n/pK04wV0oL8KEjWJwxncTicnb23C3F2slabIs9H1K/HrFZ9HrIPX7Mv37LPuTC5xEacSfa+V83YEW+bBfleFkuW8QbqQZDEuso9rcOKQQ/CxosIHnQLkWJOVdept9+ijSA6NEJwFGePaUekAdFwr65EaRcxu9BbOKq1JDqnmzIi9oL0RRDu4p1u/ayH9schrhlimGTtOLGnjeJRAJnC56FCQ3SFaYriLWjA4Q7SsPOp6kYnEXMbldKDTW/ssCFgKiaB1kusBWT+rkLYjQiAKhkHvP2j3IqWd5iMQ+M=)

### RxJS {#rxjs}

[RxJS](https://rxjs.dev/) est une bibliothèque permettant de travailler avec des flux d'événements asynchrones. La bibliothèque [VueUse](https://vueuse.org/) fournit le module complémentaire [`@vueuse/rxjs`](https://vueuse.org/rxjs/readme.html) permettant de connecter les flux RxJS au système de réactivité de Vue.

## Connexion aux Signals {#connection-to-signals}

De nombreux autres frameworks ont introduit des primitives de réactivité similaires aux refs de la Composition API de Vue, sous le terme "Signals" :

* [Signals de Solid](https://docs.solidjs.com/concepts/signals)
* [Signals d'Angular](https://angular.dev/guide/signals)
* [Signals de Preact](https://preactjs.com/guide/v10/signals/)
* [Signals de Qwik](https://qwik.builder.io/docs/components/state/#usesignal)

Fondamentalement, les *Signals* sont le même genre de primitive de réactivité que les refs de Vue. Il s'agit d'un conteneur de valeurs qui permet la traque des dépendances lors de l'accès et le déclenchement d'effets de bord lors de la mutation. Ce paradigme basé sur la réactivité primitive n'est pas un concept particulièrement nouveau dans le monde front-end : il remonte à des implémentations telles que les [observables Knockout](https://knockoutjs.com/documentation/observables.html) et [Meteor Tracker](https://docs.meteor.com/api/tracker.html) datant d'il y a plus de dix ans. L'Options API de Vue et la bibliothèque de gestion d'état [MobX](https://mobx.js.org/) de React sont également basées sur les mêmes principes, mais cachent les primitives derrière les propriétés d'objet.

Bien qu'il ne s'agisse pas d'un trait nécessaire pour que quelque chose soit qualifié de signal, le concept est aujourd’hui souvent discuté parallèlement au mode de rendu où les mises à jour sont effectuées via des abonnements à granularité fine. En raison de l'utilisation d'un DOM virtuel, Vue [s'appuie actuellement sur des compilateurs pour obtenir des optimisations similaires](https://vuejs.org/guide/extras/rendering-mechanism.html#compiler-informed-virtual-dom). Cependant, nous explorons également une nouvelle stratégie de compilation inspirée de Solid, appelé [Vapor Mode](https://github.com/vuejs/core-vapor), qui ne se repose pas sur le DOM virtuel et tire davantage parti du système de réactivité intégré de Vue.

### Compromis du design d'API {#api-design-trade-offs}

La conception des *Signals* de Preact et de Qwik est très similaire à [shallowRef](/api/reactivity-advanced#shallowref) de Vue : tous les trois fournissent une interface mutable via la propriété `.value`. Nous concentrerons la discussion sur les *Signals* de Solid et d'Angular.

### Signals de Solid {#solid-signals}

La conception de l'API `createSignal()` de Solid met l'accent sur la séparation de la lecture et de l'écriture. Les *Signals* sont exposés sous la forme d'un accesseur en lecture seule et d'un mutateur séparé :

```js
const [count, setCount] = createSignal(0)

count() // accès à la valeur
setCount(1) // mise à jour de la valeur
```

Remarquez comment le signal `count` peut être transmis sans utiliser le mutateur. Cela assure que l'état ne peut jamais être muté à moins que le mutateur soit également explicitement exposé. La question de savoir si cette garantie de sécurité justifie la syntaxe plus verbeuse peut être questionnée par les exigences du projet et vos goûts personnels - mais si vous préférez ce style d'API, vous pouvez facilement reproduire ce schéma dans Vue :

```js
import { shallowRef, triggerRef } from 'vue'

export function createSignal(value, options) {
  const r = shallowRef(value)
  const get = () => r.value
  const set = (v) => {
    r.value = typeof v === 'function' ? v(r.value) : v
    if (options?.equals === false) triggerRef(r)
  }
  return [get, set]
}
```

[Essayer en ligne](https://play.vuejs.org/#eNpdUk1TgzAQ/Ss7uQAjgr12oNXxH+ix9IAYaDQkMV/qMPx3N6G0Uy9Msu/tvn2PTORJqcI7SrakMp1myoKh1qldI9iopLYwQadpa+krG0TLYYZeyxGSojSSs/d7E8vFh0ka0YhOCmPh0EknbB4mPYfTEeqbIelD1oiqXPRQCS+WjoojAW8A1Wmzm1A39KYZzHNVYiUib85aKeCx46z7rBuySqQe6h14uINN1pDIBWACVUcqbGwtl17EqvIiR3LyzwcmcXFuTi3n8vuF9jlYzYaBajxfMsDcomv6E/m9E51luN2NV99yR3OQKkAmgykss+SkMZerxMLEZFZ4oBYJGAA600VEryAaD6CPaJwJKwnr9ldR2WMedV1Dsi6WwB58emZlsAV/zqmH9LzfvqBfruUmNvZ4QN7VearjenP4aHwmWsABt4x/+tiImcx/z27Jqw==)

#### Signals d'Angular {#angular-signals}

Angular subit en ce moment des changements fondamentaux en renonçant au *dirt-checking* et en introduisant sa propre implémentation d'une primitive de réactivité. L'API du signal d'Angular ressemble à ça :

```js
const count = signal(0)

count() // accède à la valeur
count.set(1) // assigne la nouvelle valeur
count.update((v) => v + 1) // met à jour en fonction de la valeur précédente
```

Une fois de plus, nous pouvons facilement répliquer l'API dans Vue :

```js
import { shallowRef } from 'vue'

export function signal(initialValue) {
  const r = shallowRef(initialValue)
  const s = () => r.value
  s.set = (value) => {
    r.value = value
  }
  s.update = (updater) => {
    r.value = updater(r.value)
  }
  return s
}
```

[Essayer en ligne](https://play.vuejs.org/#eNp9Ul1v0zAU/SuWX9ZCSRh7m9IKGHuAB0AD8WQJZclt6s2xLX+ESlH+O9d2krbr1Df7nnPu17k9/aR11nmgt7SwleHaEQvO6w2TvNXKONITyxtZihWpVKu9g5oMZGtUS66yvJSNF6V5lyjZk71ikslKSeuQ7qUj61G+eL+cgFr5RwGITAkXiyVZb5IAn2/IB+QWeeoHO8GPg1aL0gH+CCl215u7mJ3bW9L3s3IYihyxifMlFRpJqewL1qN3TknysRK8el4zGjNlXtdYa9GFrjryllwvGY18QrisDLQgXZTnSX8pF64zzD7pDWDghbbI5/Hoip7tFL05eLErhVD/HmB75Edpyd8zc9DUaAbso3TrZeU4tjfawSV3vBR/SuFhSfrQUXLHBMvmKqe8A8siK7lmsi5gAbJhWARiIGD9hM7BIfHSgjGaHljzlDyGF2MEPQs6g5dpcAIm8Xs+2XxODTgUn0xVYdJ5RxPhKOd4gdMsA/rgLEq3vEEHlEQPYrbgaqu5APNDh6KWUTyuZC2jcWvfYswZD6spXu2gen4l/mT3Icboz3AWpgNGZ8yVBttM8P2v77DH9wy2qvYC2RfAB7BK+NBjon32ssa2j3ix26/xsrhsftv7vQNpp6FCo4E5RD6jeE93F0Y/tHuT3URd2OLwHyXleRY=)

Par rapport aux références Vue, Solid et le style d'API basé sur les accesseurs d'Angular offrent quelques compromis intéressants lorsqu'ils sont utilisés dans des composants Vue :

* `()` est légèrement moins verbeux que `.value`, mais la mise à jour de la valeur l'est d'avantage.
* Les refs ne sont pas enveloppées : l'accès aux valeurs nécessite toujours `()`. Cela rend l'accès aux valeurs cohérent partout. Cela signifie également que vous pouvez transmettre des *Signals* bruts vers le bas en tant que props de composants.

Que ces styles d'API vous conviennent ou non est dans une certaine mesure subjectif. Notre objectif ici est de démontrer la similarité sous-jacente et les compromis entre ces différentes conceptions d'API. Nous voulons également montrer que Vue est flexible : vous n'êtes pas vraiment enfermé dans les API existantes. Si cela s'avère nécessaire, vous pouvez créer votre propre API primitive de réactivité pour répondre à des besoins plus spécifiques.

---

---
url: /guide/components/events.md
---
# Les événements de composant {#component-events}

> Cette page suppose que vous avez déjà lu les [principes fondamentaux des composants](/guide/essentials/component-basics). Lisez-les d'abord si vous débutez avec les composants.

## Émettre et écouter des événements {#emitting-and-listening-to-events}

Un composant peut émettre des événements personnalisés directement à partir du template (par exemple, dans un gestionnaire d'événement `v-on`) à l'aide de la méthode native `$emit` :

```vue-html
<!-- MyComponent -->
<button @click="$emit('someEvent')">Cliquez-Moi</button>
```

La méthode `$emit()` est également disponible sur l'instance du composant avec `this.$emit()` :

```js
export default {
  methods: {
    submit() {
      this.$emit('someEvent')
    }
  }
}
```

Le composant parent peut alors l'écouter en utilisant `v-on` :

```vue-html
<MyComponent @some-event="callback" />
```

Le modificateur `.once` est également pris en charge sur les écouteurs d'événements de composants :

```vue-html
<MyComponent @some-event.once="callback" />
```

Comme les composants et les props, les noms d'événements fournissent une transformation de casse automatique. Notez que nous avons émis un événement `camelCase`, mais que nous pouvons l'écouter à l'aide d'un écouteur `kebab-case` dans le parent. Comme pour la [casse des props](/guide/components/props#prop-name-casing), nous vous recommandons d'utiliser des noms d'écouteurs d'événement au format `kebab-case` dans les templates.

:::tip
Contrairement aux événements DOM natifs, les événements émis par les composants **ne se propagent pas** au delà de leur parent direct. Vous ne pouvez écouter que les événements émis par un composant enfant direct. S'il est nécessaire de communiquer entre des composants frères ou profondément imbriqués, utilisez un bus d'événements externe ou une [solution de gestion d'état global](/guide/scaling-up/state-management).
:::

## Arguments d'événement {#event-arguments}

Il est parfois utile d'émettre une valeur spécifique avec un événement. Par exemple, nous pouvons vouloir que le composant `<BlogPost>` soit en charge d'agrandir plus ou moins le texte. Dans ces cas, nous pouvons passer des arguments supplémentaires à `$emit` pour fournir cette valeur :

```vue-html
<button @click="$emit('increaseBy', 1)">
  Increase by 1
</button>
```

Ensuite, lorsque nous écoutons l'événement dans le composant parent, nous pouvons utiliser une fonction fléchée comme écouteur, ce qui nous permet d'accéder à l'argument de l'événement :

```vue-html
<MyButton @increase-by="(n) => count += n" />
```

Ou, si le gestionnaire d'événements est une méthode :

```vue-html
<MyButton @increase-by="increaseCount" />
```

Ensuite, la valeur sera transmise comme premier paramètre de cette méthode :

```js
methods: {
  increaseCount(n) {
    this.count += n
  }
}
```

```js
function increaseCount(n) {
  count.value += n
}
```

:::tip
Tous les arguments supplémentaires passés à `$emit()` après le nom de l'événement seront transmis à l'écouteur. Par exemple, avec `$emit('foo', 1, 2, 3)` la fonction d'écoute recevra trois arguments.
:::

## Déclaration des événements émis {#declaring-emitted-events}

Les événements émis peuvent être explicitement déclarés sur le composant via la macro [`defineEmits()`](/api/sfc-script-setup#defineprops-defineemits)l'option [`emits`](/api/options-state#emits) :

```vue
<script setup>
defineEmits(['inFocus', 'submit'])
</script>
```

La méthode `$emit` que nous avons utilisée dans le `<template>` n'est pas accessible dans la section `<script setup>` d'un composant, mais `defineEmits()` renvoie une fonction équivalente que nous pouvons utiliser à la place :

```vue
<script setup>
const emit = defineEmits(['inFocus', 'submit'])

function buttonClick() {
  emit('submit')
}
</script>
```

La macro `defineEmits()` **ne peut pas** être utilisée dans une fonction, elle doit être placée directement dans `<script setup>`, comme dans l'exemple ci-dessus.

Si vous utilisez une fonction `setup` explicite au lieu de `<script setup>`, les événements doivent être déclarés à l'aide de l'option [`emits`](/api/options-state#emits), et la fonction `emit` est exposée dans le contexte de `setup()` :

```js
export default {
  emits: ['inFocus', 'submit'],
  setup(props, ctx) {
    ctx.emit('submit')
  }
}
```

Comme pour les autres propriétés du contexte de `setup()`, `emit` peut être déstructurée en toute sécurité :

```js
export default {
  emits: ['inFocus', 'submit'],
  setup(props, { emit }) {
    emit('submit')
  }
}
```

```js
export default {
  emits: ['inFocus', 'submit']
}
```

L'option `emits` et la macro `defineEmits()` supportent également une syntaxe avec un objet. Si vous utilisez TypeScript, vous pouvez utiliser les arguments, ce qui nous permet d'effectuer une validation à l'exécution du contenu des événements émis :

```vue
<script setup lang="ts">
const emit = defineEmits({
  submit(payload: { email: string, password: string }) {
    // renvoie `true` ou `false` pour indiquer
    // que la validation a réussi/échoué
  }
})
</script>
```

Si vous utilisez TypeScript avec `<script setup>`, il est également possible de déclarer des événements émis à l'aide d'annotations de type :

```vue
<script setup lang="ts">
const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()
</script>
```

Plus de détails : [Typer les données émises par les composants](/guide/typescript/composition-api#typing-component-emits)&#x20;

```js
export default {
  emits: {
    submit(payload: { email: string, password: string }) {
      // renvoie `true` ou `false` pour indiquer
      // que la validation a réussi/échoué
    }
  }
}
```

Voir également : [Typer les données émises par les composants](/guide/typescript/options-api#typing-component-emits)&#x20;

Bien que facultatif, il est recommandé de définir tous les événements émis afin de mieux documenter le fonctionnement d'un composant. Cela permet également à Vue d'exclure les écouteurs connus des [attributs implicitement déclarés (fallthrough attributes)](/guide/components/attrs#v-on-listener-inheritance), évitant ainsi les problèmes liés aux cas à la marge causés par des événements DOM envoyés manuellement par du code tiers.

:::tip
Si un événement natif (par exemple, `click`) est défini dans l'option `emits`, l'écouteur n'écoutera alors que les événements `click` émis par le composant et ne réagira plus aux événements `click` natifs.
:::

## Validation des événements {#events-validation}

Semblable à la validation de type de prop, un événement émis peut être validé s'il est défini avec la syntaxe utilisant un objet au lieu d'un tableau.

Pour ajouter une validation, l'événement se voit attribuer une fonction qui reçoit les arguments passés à l'appel de `this.$emit``emit` et renvoie un booléen pour indiquer si l'événement est valide ou non.

```vue
<script setup>
const emit = defineEmits({
  // Pas de validation
  click: null,

  // Validation de l'événement soumis
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Invalid submit event payload!')
      return false
    }
  }
})

function submitForm(email, password) {
  emit('submit', { email, password })
}
</script>
```

```js
export default {
  emits: {
    // Pas de validation
    click: null,

    // Validation de l'événement soumis
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Invalid submit event payload!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}
```

---

---
url: /guide/essentials/lifecycle.md
---
# Les hooks du cycle de vie {#lifecycle-hooks}

Chaque instance d'un composant Vue passe par une série d'étapes d'initialisation lorsqu'elle est créée - par exemple, il faut paramétrer l'observation des données, compiler le template, monter l'instance sur le DOM, et le mettre à jour lorsque les données changent. En cours de route, des fonctions appelées hooks du cycle de vie sont également exécutées, donnant la possibilité à l'utilisateur d'ajouter son propre code à des étapes spécifiques.

## Enregistrement des hooks du cycle de vie {#registering-lifecycle-hooks}

Par exemple, le hook `onMounted``mounted`  peut être utilisé pour exécuter du code après que le composant ait terminé son rendu initial et créé les nœuds du DOM :

```vue
<script setup>
import { onMounted } from 'vue'

onMounted(() => {
  console.log(`the component is now mounted.`)
})
</script>
```

```js
export default {
  mounted() {
    console.log(`the component is now mounted.`)
  }
}
```

Il y a également d'autres hooks qui peuvent être appelés à différentes étapes du cycle de vie de l'instance, dont les plus couramment utilisés sont [`onMounted`](/api/composition-api-lifecycle#onmounted), [`onUpdated`](/api/composition-api-lifecycle#onupdated), et [`onUnmounted`](/api/composition-api-lifecycle#onunmounted).[`mounted`](/api/options-lifecycle#mounted), [`updated`](/api/options-lifecycle#updated), and [`unmounted`](/api/options-lifecycle#unmounted).

Tous les hooks du cycle de vie sont appelés via leur contexte `this` qui pointe sur l'instance active actuelle qui l'invoque. Notez que vous devez éviter d'utiliser les fonctions fléchées lorsque vous déclarez des hooks du cycle de vie, puisque dans ce cas vous ne pourrez pas accéder à l'instance du composant via `this`.

Lorsque vous appelez `onMounted`, Vue associe automatiquement la fonction de rappel enregistrée et l'instance active actuelle du composant. Cela nécessite que ces hooks soient enregistrés **de manière synchrone** pendant la configuration du composant. Par exemple, ne faites pas ça :

```js
setTimeout(() => {
  onMounted(() => {
    // cela ne fonctionnera pas.
  })
}, 100)
```

Notez que cela ne signifie pas que l'appel doit être placé littéralement dans `setup()` ou `<script setup>`. `onMounted()` peut être appelé dans une fonction externe tant que le contenu de l'appel est synchrone et provient de `setup()`.

## Diagramme du cycle de vie {#lifecycle-diagram}

Ci-dessous figure le diagramme du cycle de vie d'une instance. Vous n'avez pas besoin de le comprendre entièrement pour le moment, mais au fur et à mesure que vous apprendrez et construirez, il sera une référence utile.

![Diagramme du cycle de vie d'un composant](./images/lifecycle.png)

Consultez la [référence de l'API des hooks du cycle de vie](/api/composition-api-lifecycle)[référence de l'API des hooks du cycle de vie](/api/options-lifecycle) pour plus de détails sur tous les hooks du cycle de vie et leurs utilisations respectives.

---

---
url: /guide/essentials/template-refs.md
---
# Les refs du template {#template-refs}

Bien que le modèle de rendu déclaratif de Vue fasse abstraction pour vous de la plupart des opérations directes sur le DOM, il peut tout de même y avoir des cas où nous avons besoin d'accéder aux éléments sous-jacents du DOM. Pour ce faire, nous pouvons utiliser l'attribut spécial `ref`:

```vue-html
<input ref="input">
```

`ref` est un attribut spécial, semblable à l'attribut `key` évoqué dans le chapitre `v-for`. Il nous permet d'obtenir une référence directe à un élément spécifique du DOM ou à une instance d'un composant enfant une fois qu'il a été monté. Cela peut être utile lorsque vous voulez, par exemple, vous concentrer de manière programmatique sur une entrée lors du montage d'un composant, ou bien initialiser une librairie tierce sur un élément.

## Accéder aux refs {#accessing-the-refs}

Pour obtenir la référence avec l'API Composition, nous pouvons utiliser le helper [`useTemplateRef()`](/api/composition-api-helpers#usetemplateref) :

```vue
<script setup>
import { useTemplateRef, onMounted } from 'vue'

// le premier argument doit correspondre à la valeur ref dans le template
const input = useTemplateRef('my-input')

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="my-input" />
</template>
```

Lorsque vous utilisez TypeScript, le support IDE de Vue et `vue-tsc` déduiront automatiquement le type de `input.value` en fonction de l'élément ou du composant sur lequel l'attribut `ref` correspondant est utilisé.

Dans les versions antérieures à la 3.5 où `useTemplateRef()` n'a pas été introduit, nous devons déclarer une ref avec un nom qui correspond à la valeur de l'attribut template ref :

```vue
<script setup>
import { ref, onMounted } from 'vue'

// déclare une ref contenant la référence à l'élément
// le nom doit correspondre à la valeur de la ref dans le template
const input = ref(null)

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="input" />
</template>
```

Si vous n'utilisez pas `<script setup>`, assurez vous également de retourner la ref depuis `setup()` :

```js{6}
export default {
  setup() {
    const input = ref(null)
    // ...
    return {
      input
    }
  }
}
```

La ref correspondante est accessible via `this.$refs` :

```vue
<script>
export default {
  mounted() {
    this.$refs.input.focus()
  }
}
</script>

<template>
  <input ref="input" />
</template>
```

Notez que vous ne pouvez accéder à la ref **qu'après que le composant ait été monté.** Si vous essayez d'accéder à `$refs.input``input` via une expression dans le template, ça sera `undefined``null` lors du premier rendu. C'est parce que l'élément n'existe pas avant la fin du premier rendu !

Si vous essayez d'observer les changements d'une ref du template, assurez vous de prendre en compte le cas où la ref a une valeur `null` :

```js
watchEffect(() => {
  if (input.value) {
    input.value.focus()
  } else {
    // pas encore monté ou l'élément a été démonté (par ex. par v-if)
  }
})
```

Voir aussi : [Typer les refs du template](/guide/typescript/composition-api#typing-template-refs)&#x20;

## Ref sur un composant {#ref-on-component}

> Cette section considère [les composants](/guide/essentials/component-basics) comme acquis. N'hésitez pas à la passer et revenir plus tard.

`ref` peut également être utilisée sur un composant enfant. Dans ce cas la référence sera celle d'une instance du composant :

```vue
<script setup>
import { useTemplateRef, onMounted } from 'vue'
import Child from './Child.vue'

const childRef = useTemplateRef('child')

onMounted(() => {
  // childRef.value contiendra une instance de <Child />
})
</script>

<template>
  <Child ref="child" />
</template>
```

```vue
<script setup>
import { ref, onMounted } from 'vue'
import Child from './Child.vue'

const child = ref(null)

onMounted(() => {
  // child.value contiendra une instance de <Child />
})
</script>

<template>
  <Child ref="child" />
</template>
```

```vue
<script>
import Child from './Child.vue'

export default {
  components: {
    Child
  },
  mounted() {
    // this.$refs.child ne contiendra pas une instance de <Child />
  }
}
</script>

<template>
  <Child ref="child" />
</template>
```

Si le composant enfant utilise l'Options API ou n'utilise pas `<script setup>`, l'L'instance référencée sera identique au `this` du composant enfant, ce qui signifie que le composant parent aura un accès total aux propriétés et méthodes du composant enfant. Cela simplifie la création de détails de mise en oeuvre étroitement liés entre le parent en l'enfant, donc les refs sur un composant devraient être utilisées seulement si nécessaire - dans la plupart des cas, vous devriez essayez d'implémenter des interactions parent / enfant en utilisant d'abord les props standards et les interfaces emit.

Une exception ici est que les composants utilisant `<script setup>` sont **privés par défaut** : un composant parent faisant référence à un composant enfant en utilisant `<script setup>` n'aura accès à rien, à moins que le composant enfant choisisse d'exposer une interface publique via la macro `defineExpose` :

```vue
<script setup>
import { ref } from 'vue'

const a = 1
const b = ref(2)

// Les macros de compilation, telle que defineExpose, n'ont pas besoin d'être importées
defineExpose({
  a,
  b
})
</script>
```

Lorsqu'un parent accède à une instance de ce composant via les refs du template, l'instance récupérée aura la forme suivante : `{ a: number, b: number }` (les refs sont automatiquement désenveloppées comme sur les instances classiques).

Notez que defineExpose doit être appelé avant toute opération await. Sinon, les propriétés et les méthodes exposées après l'opération await ne seront pas accessibles.

Voir aussi : [Typer les refs du template d'un composant](/guide/typescript/composition-api#typing-component-template-refs)&#x20;

L'option `expose` peut être utilisée afin de limiter l'accès à une instance du composant enfant :

```js
export default {
  expose: ['publicData', 'publicMethod'],
  data() {
    return {
      publicData: 'foo',
      privateData: 'bar'
    }
  },
  methods: {
    publicMethod() {
      /* ... */
    },
    privateMethod() {
      /* ... */
    }
  }
}
```

Dans l'exemple ci-dessus, un parent référençant ce composant via une ref du template n'aura pas accès à `publicData` et `publicMethod`.

## Refs à l'intérieur d'un `v-for` {#refs-inside-v-for}

> Requiert v3.5 ou ultérieure

Lorsque `ref` est utilisée à l'intérieur d'un `v-for`, la ref correspondante doit contenir un tableau, qui sera alimenté avec les éléments après le montage :

```vue
<script setup>
import { ref, useTemplateRef, onMounted } from 'vue'

const list = ref([
  /* ... */
])

const itemRefs = useTemplateRef('items')

onMounted(() => console.log(itemRefs.value))
</script>

<template>
  <ul>
    <li v-for="item in list" ref="items">
      {{ item }}
    </li>
  </ul>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9UsluwjAQ/ZWRLwQpDepyQoDUIg6t1EWUW91DFAZq6tiWF4oU5d87dtgqVRyyzLw3b+aN3bB7Y4ptQDZkI1dZYTw49MFMuBK10dZDAxZXOQSHC6yNLD3OY6zVsw7K4xJaWFldQ49UelxxVWnlPEhBr3GszT6uc7jJ4fazf4KFx5p0HFH+Kme9CLle4h6bZFkfxhNouAIoJVqfHQSKbSkDFnVpMhEpovC481NNVcr3SaWlZzTovJErCqgydaMIYBRk+tKfFLC9Wmk75iyqg1DJBWfRxT7pONvTAZom2YC23QsMpOg0B0l0NDh2YjnzjpyvxLrYOK1o3ckLZ5WujSBHr8YL2gxnw85lxEop9c9TynkbMD/kqy+svv/Jb9wu5jh7s+jQbpGzI+ZLu0byEuHZ+wvt6Ays9TJIYl8A5+i0DHHGjvYQ1JLGPuOlaR/TpRFqvXCzHR2BO5iKg0Zmm/ic0W2ZXrB+Gve2uEt1dJKs/QXbwePE)

Dans les versions antérieurs à la 3.5 où `useTemplateRef()` n'était pas encore introduit, nous devions déclarer une ref avec un nom qui corresponde à la valeur de l'attribut ref du template. La ref devait également contenir un valeur sous forme de tableau :

In versions before 3.5 where `useTemplateRef()` was not introduced, we need to declare a ref with a name that matches the template ref attribute's value. The ref should also contain an array value:

```vue
<script setup>
import { ref, onMounted } from 'vue'

const list = ref([
  /* ... */
])

const itemRefs = ref([])

onMounted(() => console.log(itemRefs.value))
</script>

<template>
  <ul>
    <li v-for="item in list" ref="itemRefs">
      {{ item }}
    </li>
  </ul>
</template>
```

Lorsque `ref` est utilisée à l'intérieur d'un `v-for`, la valeur ref qui en résulte sera un tableau contenant les éléments correspondants :

```vue
<script>
export default {
  data() {
    return {
      list: [
        /* ... */
      ]
    }
  },
  mounted() {
    console.log(this.$refs.items)
  }
}
</script>

<template>
  <ul>
    <li v-for="item in list" ref="items">
      {{ item }}
    </li>
  </ul>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNpFjk0KwjAQha/yCC4Uaou6kyp4DuOi2KkGYhKSiQildzdNa4WQmTc/37xeXJwr35HEUdTh7pXjszT0cdYzWuqaqBm9NEDbcLPeTDngiaM3PwVoFfiI667AvsDhNpWHMQzF+L9sNEztH3C3JlhNpbaPNT9VKFeeulAqplfY5D1p0qurxVQSqel0w5QUUEedY8q0wnvbWX+SYgRAmWxIiuSzm4tBinkc6HvkuSE7TIBKq4lZZWhdLZfE8AWp4l3T)

À noter que le tableau ref ne garantit **pas** le même ordre que celui du tableau source.

## Les fonctions refs {#function-refs}

Au lieu d'une chaîne de caractères comme clé, l'attribut `ref` peut également être lié à une fonction, qui sera appelée à chaque mise à jour du composant et vous donne une flexibilité totale sur l'endroit où stocker la référence à l'élément. La fonction reçoit la référence à l'élément comme premier argument :

```vue-html
<input :ref="(el) => { /* assigne l'élément à une propriété ou à une ref */ }">
```

Notez l'utilisation d'une liaison dynamique `:ref` permettant de passer une fonction au lieu d'un nom de ref en chaîne de caractères. Lorsque l'élément est démonté, l'argument sera `null`. Vous pouvez, bien entendu, utiliser une méthode au lieu d'une fonction en une ligne.

---

---
url: /guide/essentials/class-and-style.md
---
# Liaison de classes et de styles {#class-and-style-bindings}

La liaison de données consiste à manipuler la liste des classes et les styles CSS inline d'un élément. Puisque `class` et `style` sont tous les deux des attributs, nous pouvons utiliser `v-bind` pour leur attribuer dynamiquement une valeur de chaîne, un peu comme avec les autres attributs. Cependant, essayer de générer ces valeurs à l'aide de la concaténation de chaînes peut être ennuyeux et sujet aux erreurs. Pour cette raison, Vue fournit des améliorations spéciales lorsque `v-bind` est utilisé avec `class` et `style`. En plus des chaînes, les expressions peuvent également évaluer des objets ou des tableaux.

## Liaison des classes HTML {#binding-html-classes}

### Liaison par objet {#binding-to-objects-1}

Nous pouvons passer un objet à `:class` (abréviation de `v-bind:class`) pour basculer dynamiquement entre les classes :

```vue-html
<div :class="{ active: isActive }"></div>
```

La syntaxe ci-dessus signifie que la présence de la classe "active" sera déterminée par la [valeur évaluée à vrai](https://developer.mozilla.org/fr/docs/Glossary/Truthy) de la donnée "isActive".

Vous pouvez basculer plusieurs classes en ayant plus de clés dans l'objet. De plus, la directive `:class` peut également coexister avec l'attribut simple `class`. Admettons la chose suivante :

```js
const isActive = ref(true)
const hasError = ref(false)
```

```js
data() {
  return {
    isActive: true,
    hasError: false
  }
}
```

Et avec le template suivant :

```vue-html
<div
  class="static"
  :class="{ active: isActive, 'text-danger': hasError }"
></div>
```

Cela sera rendu :

```vue-html
<div class="static active"></div>
```

Lorsque `isActive` ou `hasError` change, la liste des classes sera mise à jour en conséquence. Par exemple, si `hasError` devient `true`, la liste des classes deviendra `"static active text-danger"`.

L'objet lié n'a pas besoin d'être décrit dans le template :

```js
const classObject = reactive({
  active: true,
  'text-danger': false
})
```

```js
data() {
  return {
    classObject: {
      active: true,
      'text-danger': false
    }
  }
}
```

```vue-html
<div :class="classObject"></div>
```

Cela rendra :

```vue-html
<div class="active"></div>
```

Nous pouvons également lier à une [propriété calculée](./computed) qui renvoie un objet. Il s'agit d'un modèle commun et puissant :

```js
const isActive = ref(true)
const error = ref(null)

const classObject = computed(() => ({
  active: isActive.value && !error.value,
  'text-danger': error.value && error.value.type === 'fatal'
}))
```

```js
data() {
  return {
    isActive: true,
    error: null
  }
},
computed: {
  classObject() {
    return {
      active: this.isActive && !this.error,
      'text-danger': this.error && this.error.type === 'fatal'
    }
  }
}
```

```vue-html
<div :class="classObject"></div>
```

Là encore, la liaison de style objet est souvent utilisée avec des propriétés calculées qui renvoient des objets.

Les directives `:style` peuvent également coexister avec des attributs de style ordinaires, tout comme `:class`.

Template:

```vue-html
<h1 style="color: red" :style="'font-size: 1em'">hello</h1>
```

Il rendra :

```vue-html
<h1 style="color: red; font-size: 1em;">hello</h1>
```

### Liaison par tableau {#binding-to-arrays-1}

Nous pouvons lier `:class` à un tableau pour appliquer une liste de classes :

```js
const activeClass = ref('active')
const errorClass = ref('text-danger')
```

```js
data() {
  return {
    activeClass: 'active',
    errorClass: 'text-danger'
  }
}
```

```vue-html
<div :class="[activeClass, errorClass]"></div>
```

Ceci sera rendu :

```vue-html
<div class="text-danger active"></div>
```

Si vous souhaitez également basculer une classe dans la liste de manière conditionnelle, vous pouvez le faire avec une expression ternaire :

```vue-html
<div :class="[isActive ? activeClass : '', errorClass]"></div>
```

Cela appliquera toujours `errorClass`, mais `activeClass` ne sera appliqué que lorsque `isActive` est vrai.

Cependant, cela peut être un peu verbeux si vous avez plusieurs classes conditionnelles. C'est pourquoi il est également possible d'utiliser la syntaxe objet à l'intérieur de la syntaxe tableau :

```vue-html
<div :class="[{ [activeClass]: isActive }, errorClass]"></div>
```

### Avec les composants {#with-components}

> Cette section suppose une connaissance des [Composants](/guide/essentials/component-basics). N'hésitez pas à sauter cette partie et à y revenir plus tard.

Lorsque vous utilisez l'attribut `class` sur un composant avec un seul élément racine, ces classes seront ajoutées à l'élément racine du composant et fusionnées avec toute classe existante déjà présente.

Par exemple, si nous avons un composant nommé "MyComponent" avec le template suivant :

```vue-html
<!-- template du composant enfant -->
<p class="foo bar">Hello !</p>
```

Ajoutez ensuite quelques classes lors de son utilisation :

```vue-html
<!-- usage du composant -->
<MyComponent class="baz boo" />
```

Le HTML rendu sera :

```vue-html
<p class="foo bar baz boo">Hi!</p>
```

Il en va de même pour les liaisons de classe :

```vue-html
<MyComponent :class="{ active: isActive }" />
```

Lorsque `isActive` est vrai, le rendu HTML sera :

```vue-html
<p class="foo bar active">Hello !</p>
```

Si votre composant a plusieurs éléments racine, vous devrez définir quel élément recevra cette classe. Vous pouvez le faire en utilisant la propriété de composant `$attrs` :

```vue-html
<!-- Template de MyComponent utilisant $attrs -->
<p :class="$attrs.class">Hello !</p>
<span>This is a child component</span>
```

```vue-html
<MyComponent class="baz" />
```

Sera rendu :

```html
<p class="baz">Hello !</p>
<span>This is a child component</span>
```

Vous pouvez en savoir plus sur l'héritage des attributs de composant dans la section [Attributs implicitement déclarés](/guide/components/attrs).

## Liaison des styles inline {#binding-inline-styles}

### Liaison par objet {#binding-to-objects-2}

`:style` supporte les liaisons avec des objets JavaScript - ça correspond à la [propriété `style` des éléments HTML](https://developer.mozilla.org/fr/docs/Web/API/HTMLElement/style):

```js
const activeColor = ref('red')
const fontSize = ref(30)
```

```js
data() {
  return {
    activeColor: 'red',
    fontSize: 30
  }
}
```

```vue-html
<div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div>
```

Bien que les clés camelCase soient recommandées, `:style` prend également en charge les clés de propriété CSS en casse kebab (correspond à la façon dont elles sont utilisées dans le CSS réel), par exemple :

```vue-html
<div :style="{ 'font-size': fontSize + 'px' }"></div>
```

C'est souvent une bonne idée de lier directement un objet de style pour que le template soit plus propre :

```js
const styleObject = reactive({
  color: 'red',
  fontSize: '30px'
})
```

```js
data() {
  return {
    styleObject: {
      color: 'red',
      fontSize: '13px'
    }
  }
}
```

```vue-html
<div :style="styleObject"></div>
```

À nouveau, la liaison par objet est souvent utilisée conjointement avec des propriétés calculées qui renvoient des objets.

### Liaison par tableau {binding-to-arrays-1}

Nous pouvons lier `:style` à un tableau de plusieurs objets de style. Ces objets seront fusionnés et appliqués au même élément :

```vue-html
<div :style="[baseStyles, overridingStyles]"></div>
```

### Préfixe automatique {#auto-prefixing}

Lorsque vous utilisez une propriété CSS qui nécessite un [préfixe vendeur](https://developer.mozilla.org/fr/docs/Glossary/Vendor_Prefix) dans `:style`, Vue ajoutera automatiquement le préfixe approprié. Vue le fait en vérifiant lors de l'exécution quelles propriétés de style sont prises en charge dans le navigateur actuel. Si le navigateur ne prend pas en charge une propriété particulière, différentes variantes préfixées seront testées pour essayer d'en trouver une qui soit prise en charge.

### Valeurs multiples {#multiple-values}

Vous pouvez fournir un tableau de plusieurs valeurs (préfixées) à une propriété de style, par exemple :

```vue-html
<div :style="{ display: ['-webkit-box', '-ms-flexbox', 'flex'] }"></div>
```

Cela ne rendra que la dernière valeur du tableau prise en charge par le navigateur. Dans cet exemple, il affichera `display: flex` pour les navigateurs prenant en charge la version sans préfixe de flexbox.

---

---
url: /guide/essentials/forms.md
---

# Liaisons des entrées utilisateur d'un formulaire {#form-input-bindings}

Lorsque nous devons gérer des formulaires côté front, il arrive souvent que nous ayons besoin de synchroniser l'état des éléments de saisie du formulaire avec l'état correspondant en JavaScript. Cela peut être encombrant de connecter les liaisons des valeurs et de changer les écouteurs d'événements :

```vue-html
<input
  :value="text"
  @input="event => text = event.target.value">
```

La directive `v-model` nous aide à simplifier le code ci-dessus par :

```vue-html
<input v-model="text">
```

De plus, `v-model` peut être utilisé sur des entrées de différents types, des éléments `<textarea>`, et `<select>`. Il s'étend automatiquement aux différentes paires de propriétés et d'événements du DOM en fonction de l'élément sur lequel il est utilisé :

* Les éléments `<input>` de type texte et `<textarea>` utilisent la propriété `value` et l'événement `input` ;
* `<input type="checkbox">` et `<input type="radio">` utilisent la propriété `checked` et l'événement `change` ;
* `<select>` utilise `value` comme prop et `change` comme événement.

:::tip Remarque
`v-model` ignorera les attributs initiaux `value`, `checked` ou `selected` trouvés sur tout élément de formulaire. Il traitera toujours l'état actuel du JavaScript lié comme la source de vérité. Vous devez déclarer la valeur initiale côté JavaScript, à l'aide de l'option [`data`](/api/options-state.html#data)[des API de réactivité](/api/reactivity-core.html#reactivity-api-core).
:::

## Utilisation basique {#basic-usage}

### Texte {#text}

```vue-html
<p>Message is: {{ message }}</p>
<input v-model="message" placeholder="edit me" />
```

[Essayer en ligne](https://play.vuejs.org/#eNo9jUEOgyAQRa8yYUO7aNkbNOkBegM2RseWRGACoxvC3TumxuX/+f+9ql5Ez31D1SlbpuyJoSBvNLjoA6XMUCHjAg2WnAJomWoXXZxSLAwBSxk/CP2xuWl9d9GaP0YAEhgDrSOjJABLw/s8+NJBrde/NWsOpWPrI20M+yOkGdfeqXPiFAhowm9aZ8zS4+wPv/RGjtZcJtV+YpNK1g==)

[Essayer en ligne](https://play.vuejs.org/#eNo9jdEKwjAMRX8l9EV90L2POvAD/IO+lDVqoetCmw6h9N/NmBuEJPeSc1PVg+i2FFS90nlMnngwEb80JwaHL1sCQzURwFm258u2AyTkkuKuACbM2b6xh9Nps9o6pEnp7ggWwThRsIyiADQNz40En3uodQ+C1nRHK8HaRyoMy3WaHYa7Uf8To0CCRvzMwWESH51n4cXvBNTd8Um1H0FuTq0=)


::: tip Remarque
Pour les langages nécessitant un [IME](https://en.wikipedia.org/wiki/Input_method) (chinois, japonais, coréen, etc.), vous remarquerez que `v-model` n'est pas mis à jour pendant la composition de l'IME. Si vous souhaitez également réagir à ces mises à jour, utilisez votre propre écouteur d'événements `input` et votre propre liaison `value` au lieu d'utiliser `v-model`.
:::

### Texte Multiligne {#multiline-text}

```vue-html
<span>Multiline message is:</span>
<p style="white-space: pre-line;">{{ message }}</p>
<textarea v-model="message" placeholder="add multiple lines"></textarea>
```

[Essayer en ligne](https://play.vuejs.org/#eNo9jktuwzAMRK9CaON24XrvKgZ6gN5AG8FmGgH6ECKdJjB891D5LYec9zCb+SH6Oq9oRmN5roEEGGWlyeWQqFSBDSoeYYdjLQk6rXYuuzyXzAIJmf0fwqF1Prru02U7PDQq0CCYKHrBlsQy+Tz9rlFCDBnfdOBRqfa7twhYrhEPzvyfgmCvnxlHoIp9w76dmbbtDe+7HdpaBQUv4it6OPepLBjV8Gw5AzpjxlOJC1a9+2WB1IZQRGhWVqsdXgb1tfDcbvYbJDRqLQ==)

[Essayer en ligne](https://play.vuejs.org/#eNo9jk2OwyAMha9isenMIpN9hok0B+gN2FjBbZEIscDpj6LcvaZpKiHg2X6f32L+mX+uM5nO2DLkwNK7RHeesoCnE85RYHEJwKPg1/f2B8gkc067AhipFDxTB4fDVlrro5ce237AKoRGjihUldjCmPqjLgkxJNoxEEqnrtp7TTEUeUT6c+Z2CUKNdgbdxZmaavt1pl+Wj3ldbcubUegumAnh2oyTp6iE95QzoDEGukzRU9Y6eg9jDcKRoFKLUm27E5RXxTu7WZ89/G4E)

Notez que l'interpolation à l'intérieur de `<textarea>` ne fonctionnera pas. Utilisez `v-model` à la place.

```vue-html
<!-- À éviter -->
<textarea>{{ text }}</textarea>

<!-- OK -->
<textarea v-model="text"></textarea>
```

### Checkbox {#checkbox}

Case à cocher unique, valeur booléenne :

```vue-html
<input type="checkbox" id="checkbox" v-model="checked" />
<label for="checkbox">{{ checked }}</label>
```

[Essayer en ligne](https://play.vuejs.org/#eNpVjssKgzAURH/lko3tonVfotD/yEaTKw3Ni3gjLSH/3qhUcDnDnMNk9gzhviRkD8ZnGXUgmJFS6IXTNvhIkCHiBAWm6C00ddoIJ5z0biaQL5RvVNCtmwvFhFfheLuLqqIGQhvMQLgm4tqFREDfgJ1gGz36j2Cg1TkvN+sVmn+JqnbtrjDDiAYmH09En/PxphTebqsK8PY4wMoPslBUxQ==)

[Essayer en ligne](https://play.vuejs.org/#eNpVjtEKgzAMRX8l9Gl72Po+OmH/0ZdqI5PVNnSpOEr/fVVREEKSc0kuN4sX0X1KKB5Cfbs4EDfa40whMljsTXIMWXsAa9hcrtsOEJFT9DsBdG/sPmgfwDHhJpZl1FZLycO6AuNIzjAuxGrwlBj4R/jUYrVpw6wFDPbM020MFt0uoq2a3CycadFBH+Lpo8l5jwWlKLle1QcljwCi/AH7gFic)

Nous pouvons également lier plusieurs cases à cocher au même tableau ou à la même valeur [Set](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Set) :

```js
const checkedNames = ref([])
```

```js
export default {
  data() {
    return {
      checkedNames: []
    }
  }
}
```

```vue-html
<div>Checked names: {{ checkedNames }}</div>

<input type="checkbox" id="jack" value="Jack" v-model="checkedNames" />
<label for="jack">Jack</label>

<input type="checkbox" id="john" value="John" v-model="checkedNames" />
<label for="john">John</label>

<input type="checkbox" id="mike" value="Mike" v-model="checkedNames" />
<label for="mike">Mike</label>
```

Dans ce cas, le tableau `checkedNames` contiendra toujours les valeurs des cases qui sont actuellement cochées.

[Essayer en ligne](https://play.vuejs.org/#eNqVkUtqwzAURbfy0CTtoNU8KILSWaHdQNWBIj8T1fohyybBeO+RbOc3i2e+vHvuMWggHyG89x2SLWGtijokaDF1gQunbfAxwQARaxihjt7CJlc3wgmnvGsTqAOqBqsfabGFXSm+/P69CsfovJVXckhog5EJcwJgle7558yBK+AWhuFxaRwZLbVCZ0K70CVIp4A7Qabi3h8FAV3l/C9Vk797abpy/lrim/UVmkt/Gc4HOv+EkXs0UPt4XeCFZHQ6lM4TZn9w9+YlrjFPCC/kKrPVDd6Zv5e4wjwv8ELezIxeX4qMZwHduAs=)

[Essayer en ligne](https://play.vuejs.org/#eNqVUc1qxCAQfpXBU3tovS9WKL0V2hdoenDjLGtjVNwxbAl592rMpru3DYjO5/cnOLLXEJ6HhGzHxKmNJpBsHJ6DjwQaDypZgrFxAFqRenisM0BEStFdEEB7xLZD/al6PO3g67veT+XIW16Cr+kZEPbBKsKMAIQ2g3yrAeBqwjjeRMI0CV5kxZ0dxoVEQL8BXxo2C/f+3DAwOuMf1XZ5HpRNhX5f4FPvNdqLfgnOBK+PsGqPFg4+rgmyOAWfiaK5o9kf3XXzArc0zxZZnJuae9PhVfPHAjc01wRZnP/Ngq8/xaY/yMW74g==)

### Radio {#radio}

```vue-html
<div>Picked: {{ picked }}</div>

<input type="radio" id="one" value="One" v-model="picked" />
<label for="one">One</label>

<input type="radio" id="two" value="Two" v-model="picked" />
<label for="two">Two</label>
```

[Essayer en ligne](https://play.vuejs.org/#eNqFkDFuwzAMRa9CaHE7tNoDxUBP0A4dtTgWDQiRJUKmHQSG7x7KhpMMAbLxk3z/g5zVD9H3NKI6KDO02RPDgDxSbaPvKWWGGTJ2sECXUw+VrFY22timODCQb8/o4FhWPqrfiNWnjUZvRmIhgrGn0DCKAjDOT/XfCh1gnnd+WYwukwJYNj7SyMBXwqNVuXE+WQXeiUgRpZyaMJaR5BX11SeHQfTmJi1dnNiE5oQBupR3shbC6LX9Posvpdyz/jf1OksOe85ayVqIR5bR9z+o5Qbc6oCk)

[Essayer en ligne](https://play.vuejs.org/#eNqNkEEOAiEMRa/SsFEXyt7gJJ5AFy5ng1ITIgLBMmomc3eLOONSEwJ9Lf//pL3YxrjqMoq1ULdTspGa1uMjhkRg8KyzI+hbD2A06fmi1gAJKSc/EkC0pwuaNcx2Hme1OZSHLz5KTtYMhNfoNGEhUsZ2zf6j7vuPEQyDkmVSBPzJ+pgJ6Blx04qkjQ2tAGsYgkcuO+1yGXF6oeU1GHTM1Y1bsoY5fUQH55BGZcMKJd/t31l0L+WYdaj0V9Zb2bDim6XktAcxvADR+YWb)

### Select {#select}

Simple select :

```vue-html
<div>Selected: {{ selected }}</div>

<select v-model="selected">
  <option disabled value="">Please select one</option>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>
```

[Essayer en ligne](https://play.vuejs.org/#eNp1j7EOgyAQhl/lwmI7tO4Nmti+QJOuLFTPxASBALoQ3r2H2jYOjvff939wkTXWXucJ2Y1x37rBBvAYJlsLPYzWuAARHPaQoHdmhILQQmihW6N9RhW2ATuoMnQqirPQvFw9ZKAh4GiVDEgTAPdW6hpeW+sGMf4VKVEz73Mvs8sC5stoOlSVYF9SsEVGiLFhMBq6wcu3IsUs1YREEvFUKD1udjAaebnS+27dHOT3g/yxy+nHywM08PJ3KksfXwJ2dA==)

[Essayer en ligne](https://play.vuejs.org/#eNp1j1ELgyAUhf/KxZe2h633cEHbHxjstReXdxCYSt5iEP333XIJPQSinuN3jjqJyvvrOKAohAxN33oqa4tf73oCjR81GIKptgBakTqd4x6gRxp6uymAgAYbQl1AlkVvXhaeeMg8NbMg7LxRhKwAZPDKlvBK8WlKXTDPnFzOI7naMF46p9HcarFxtVgBRpyn1lnQbVBvwwWjMgMyycTToAr47wZnUeaR3mfL6sC/H/iPnc/vXS9gIfP0UTH/ACgWeYE=)

:::tip Remarque
Si la valeur initiale de votre expression `v-model` ne correspond à aucune des options, l'élément `<select>` sera rendu dans un état "non sélectionné". Sous iOS, l'utilisateur ne pourra pas sélectionner le premier élément, car iOS ne déclenche pas d'événement de modification dans ce cas. Il est donc recommandé de fournir une option désactivée avec une valeur vide, comme le montre l'exemple ci-dessus.
:::

Plusieurs select (liés à un tableau):

```vue-html
<div>Selected: {{ selected }}</div>

<select v-model="selected" multiple>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>
```

[Essayer en ligne](https://play.vuejs.org/#eNp1kL2OwjAQhF9l5Ya74i7QBhMJeARKTIESIyz5Z5VsAsjyu7NOQEBB5xl/M7vaKNaI/0OvRSlkV7cGCTpNPVbKG4ehJYjQ6hMkOLXBwYzRmfLK18F3GbW6Jt3AKkM/+8Ov8rKYeriBBWmH9kiaFYBszFDtHpkSYnwVpCSL/JtDDE4+DH8uNNqulHiCSoDrLRm0UyWzAckEX61l8Xh9+psv/vbD563HCSxk8bY0y45u47AJ2D/HHyDm4MU0dC5hMZ/jdal8Gg8wJkS6A3nRew4=)

[Essayer en ligne](https://play.vuejs.org/#eNp1UEEOgjAQ/MqmJz0oeMVKgj7BI3AgdI1NCjSwIIbwdxcqRA4mTbsznd2Z7CAia49diyIQsslrbSlMSuxtVRMofGStIRiSEkBllO32rgaokdq6XBBAgwZzQhVAnDpunB6++EhvncyAsLAmI2QEIJXuwvvaPAzrJBhH6U2/UxMLHQ/doagUmksiFmEioOCU2ho3krWVJV2VYSS9b7Xlr3/424bn1LMDA+n9hGbY0Hs2c4J4sU/dPl5a0TOAk+/b/rwsYO4Q4wdtRX7l)

Les options d'un select peuvent être rendues de manière dynamique avec `v-for` :

```js
const selected = ref('A')

const options = ref([
  { text: 'One', value: 'A' },
  { text: 'Two', value: 'B' },
  { text: 'Three', value: 'C' }
])
```

```js
export default {
  data() {
    return {
      selected: 'A',
      options: [
        { text: 'One', value: 'A' },
        { text: 'Two', value: 'B' },
        { text: 'Three', value: 'C' }
      ]
    }
  }
}
```

```vue-html
<div>Selected: {{ selected }}</div>

<select v-model="selected">
  <option v-for="option in options" :value="option.value">
    {{ option.text }}
  </option>
</select>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9kj9vwjAQxb/KyUtaiYahGwpIgBjaoVSFre6AkguEOnZkOwEpynfv2flDqlZkyt37+fye7ZotiyKsSmQzFplYZ4UFg7YsFlxmeaG0hRo0ptBAqlUOAaEBl1zGShqHCowtJjB30EOwDB5voipsRj+d9skl0CyLVzuDYCsxmEB1ECVStQygmfzS9xc10ld/9ZPG8YQ1EVx+0e7RtI1BAaiwmBfiYNFVNkqyarHrLM+grm/+myaaOtUtAojaPlRPuUpQzDnrQc4IAfqiNh0hqdIEdGUm+9icwcy7G8TQl8MESlN3cOhSkYdu9LTteo7i+K2piKZDGjZh1tApp9kxPBsl6fZqR3MWq7zIBOpt74JytmM5OwihLq++Z3WJ/kT9mhPG3//0z+bqepy9azSoK/I+aPagj2hbebN7I/8jkU6tFETfET/QKFE6jy22KmVCtkecd/vi32Amj3uzuVqUpg/ljDqyfRec0btc34l+s/scPvt1XDas+QENov3B)

[Essayer en ligne](https://play.vuejs.org/#eNp9ksFuwjAMhl/FyoVNYuWwG+omAeKwHcY0uC07VK2BspBUiVuQKt59Tkq6Hjakqortz87/J2nFrKqSpkYxFanLbVnRs9R4rowlKHCb1YqglRqgyCi7u+/WABaptjpGAA4V5oTFFEaz0ThmTUWl0W4KnzED0ALhmZhbaRyNoclUjaELLn3fgNqczICa/0ftLQ6nLZiL2Fe3CDH/+EsnvVMOCI+Vygh9RGlRNs/r3kzb9s7gckknvuqbANIuD83D0RSonqSIoBSM+B3Tzj4jW2MZuIaljuciBUyD4r6YhLCfwA7bK5x4p6zhOnrSZQPHdsLWHKST3o0YC3K50dtylxyc0XzB4bakyM2xKhXaVVTBPruxUmRKmdNryJGt8XrW3LPH/PuP/MGdfU6Kd4sObcPa+xpldofUlZfrN9Y/KPKp1YrpG8UPdEbVXmOHzWtdsOwBF9S+HP1jLfVu45ZnQu2iKS80XHrgpeBXvrhh/VfuY/IYH4u4/AD+8ADR)

## Liaisons d'une valeur {#value-bindings}

Pour les options de type radio, checkbox et select, les valeurs de liaison du `v-model` sont généralement des chaînes de caractères statiques (ou des booléens pour les checkbox) :

```vue-html
<!-- `picked` est une chaîne de caractères valant "a" lorsqu'il est sélectionné -->
<input type="radio" v-model="picked" value="a" />

<!-- `toggle` peut être vrai ou faux -->
<input type="checkbox" v-model="toggle" />

<!-- `selected` est une chaîne de caractères valant "abc" lorsque la première option est sélectionnée -->
<select v-model="selected">
  <option value="abc">ABC</option>
</select>
```

Mais parfois, il peut arriver que nous voulions lier la valeur à une propriété dynamique sur l'instance actuellement active. Nous pouvons utiliser `v-bind` pour ce faire. De plus, l'utilisation de `v-bind` nous permet de lier la valeur d'entrée à des valeurs autres que des chaînes de caractères.

### Checkbox {#checkbox-1}

```vue-html
<input
  type="checkbox"
  v-model="toggle"
  true-value="yes"
  false-value="no" />
```

`true-value` et `false-value` sont des attributs spécifiques à Vue qui ne fonctionnent qu'avec `v-model`. Ici, la valeur de la propriété `toggle` sera définie à `'yes'` lorsque la case est cochée, et à `'no'` lorsqu'elle est décochée. Vous pouvez également les lier à des valeurs dynamiques en utilisant `v-bind` :

```vue-html
<input
  type="checkbox"
  v-model="toggle"
  :true-value="dynamicTrueValue"
  :false-value="dynamicFalseValue" />
```

:::tip Tip
Les attributs `true-value` et `false-value` n'affectent pas l'attribut `value` de l'entrée, car les navigateurs n'incluent pas les cases non cochées dans les soumissions de formulaires. Pour garantir qu'une des deux valeurs est soumise dans un formulaire (par exemple, "oui" ou "non"), utilisez plutôt des entrées de type radio.
:::

### Radio {#radio-1}

```vue-html
<input type="radio" v-model="pick" :value="first" />
<input type="radio" v-model="pick" :value="second" />
```

`pick` prendra la valeur `first` lorsque la première entrée radio sera cochée, et prendra la valeur `second` lorsque la seconde sera cochée.

### Options de select {#select-options}

```vue-html
<select v-model="selected">
  <!-- inline object literal -->
  <option :value="{ number: 123 }">123</option>
</select>
```

`v-model` supporte également les liaisons de valeurs autres que des chaînes de caractères ! Dans l'exemple précédent, lorsque l'option est sélectionnée, `selected` sera défini comme la valeur littérale de l'objet `{ number : 123 }`.

## Modificateurs {#modifiers}

### `.lazy` {#lazy}

Par défaut, `v-model` synchronise l'entrée avec les données après chaque événement `input` (à l'exception de la composition IME comme [indiqué ci-dessus](#vmodel-ime-tip)). Vous pouvez ajouter le modificateur `lazy` pour enclencher la synchronisation après les événements `change` :

```vue-html
<!-- synchronisé après "change" au lieu de "input" -->
<input v-model.lazy="msg" />
```

### `.number` {#number}

Si vous voulez que l'entrée de l'utilisateur soit automatiquement typée comme un nombre, vous pouvez ajouter le modificateur `number` à vos entrées gérées par `v-model` :

```vue-html
<input v-model.number="age" />
```

Si la valeur ne peut pas être analysée avec `parseFloat()`, alors la valeur originale (chaîne) est utilisée à la place. En particulier, si l'entrée est vide (par exemple après que l'utilisateur ait effacé le champ de saisie), une chaîne vide est renvoyée. Ce comportement diffère de la [propriété DOM `valueAsNumber`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement#valueasnumber).

Le modificateur `number` est appliqué automatiquement si l'entrée possède `type="number"`.

### `.trim` {#trim}

Si vous voulez que les espaces blancs des entrées utilisateur soient automatiquement supprimés, vous pouvez ajouter le modificateur `trim` à vos entrées gérées par `v-model` :

```vue-html
<input v-model.trim="msg" />
```

## `v-model` avec les composants {#v-model-with-components}

> Si vous n'êtes pas encore familiarisé avec les composants de Vue, vous pouvez sauter cette étape pour le moment.

Les types de saisie natifs dans HTML ne répondent pas toujours à vos besoins. Heureusement, les composants Vue vous permettent de construire des entrées réutilisables avec un comportement complètement personnalisé. Ces entrées fonctionnent même avec `v-model` ! Pour en savoir plus, lisez à propos de l'[utilisation avec `v-model`](/guide/components/v-model) dans le guide des composants.

---

---
url: /guide/extras/ways-of-using-vue.md
---
# Manières d'utiliser Vue {#ways-of-using-vue}

Nous pensons qu'il n'existe pas de solution unique pour le web. C'est pourquoi Vue est conçu pour être flexible et facilement adoptable. Selon votre cas d'utilisation, Vue peut être utilisé de différentes manières pour trouver l'équilibre optimal entre la complexité de la stack, l'expérience de développement et les performances finales.

## Script autonome {#standalone-script}

Vue peut être utilisé comme un fichier de script autonome, sans outil de build nécessaire! Si vous avez déjà un framework backend qui rend la plupart de l'HTML ou si votre logique frontend n'est pas assez complexe pour justifier des outils de build, c'est la manière la plus facile d'intégrer Vue à votre stack. Vous pouvez considérer Vue comme un remplacement plus déclaratif de jQuery dans de tels cas.

Nous proposions auparavant une distribution alternative appelée [petite-vue](https://github.com/vuejs/petite-vue) qui était spécialement optimisée pour améliorer progressivement le HTML existant. Cependant, petite-vue n'est plus activement maintenue, la dernière version ayant été publiée dans Vue 3.2.27.

## Intégration des Web Components {#embedded-web-components}

Vous pouvez utiliser Vue pour [construire des composants personnalisés standards](/guide/extras/web-components) qui peuvent être intégrés dans n'importe quelle page HTML, quelle que soit la manière dont ils sont rendus. Cette option vous permet de tirer parti de Vue de manière complètement agnostique pour le consommateur: les web components résultants peuvent être intégrés dans des applications legacy, dans du HTML statique, ou même dans des applications construites avec d'autres frameworks.

## Application monopage (SPA) {#single-page-application-spa}

Certaines applications nécessitent une interactivité riche, une profondeur de session importante et une logique d'état soignée sur le frontend. La meilleure manière de construire de telles applications consiste à utiliser une architecture où Vue contrôle non seulement toutes les pages, mais gère également les mises à jour de données et la navigation sans avoir à recharger la page. Ce type d'application est généralement appelé une application monopage (SPA).

Vue fournit des bibliothèques de base et un [support d'outils exhaustif](/guide/scaling-up/tooling) avec une expérience de développeur incroyable pour construire des SPAs modernes, y compris :

* Routeur côté client
* Chaîne d'outils de build rapide
* Support IDE
* Outils de développement pour navigateur
* Intégrations TypeScript
* Utilitaires de test

Les SPAs nécessitent généralement que le backend expose une API, mais vous pouvez également associer Vue à des solutions telles que [Inertia.js](https://inertiajs.com) pour bénéficier des avantages d'une SPA tout en conservant un modèle de développement centré sur le serveur.

## Fullstack / SSR {#fullstack-ssr}

Les SPAs entièrement côté client posent problème lorsque l'application est sensible au SEO et au temps d'accès au contenu. Cela est dû au fait que le navigateur recevra une page HTML totalement vide et devra attendre que le JavaScript soit téléchargé avant de rendre quoi que ce soit.

Vue fournit des API de première classe pour "rendre" une application Vue en chaînes HTML sur le serveur. Cela permet au serveur de renvoyer de l'HTML déjà rendu, permettant aux utilisateurs finaux de voir immédiatement le contenu tandis que le JavaScript est en cours de téléchargement. Vue hydratera alors l'application côté client pour la rendre interactive. Cela s'appelle [Rendu côté serveur ou *Server-Side Rendering* (SSR)](/guide/scaling-up/ssr) et améliore considérablement les métriques Core Web Vital telles que [Largest Contentful Paint (LCP)](https://web.dev/lcp/).

Il y a des frameworks basés sur Vue, par exemple [Nuxt](https://nuxt.com/), qui permettent de développer une application avec Vue et JavaScript.

## JAMStack / SSG {#jamstack-ssg}

Le rendu côté serveur peut être effectué à l'avance si les données requises sont statiques. Cela signifie que nous pouvons pré-rendre une application entière en HTML et les servir en tant que fichiers statiques. Cela améliore les performances du site et simplifie le déploiement, car nous n'avons plus besoin de rendre dynamiquement les pages à chaque requête. Vue peut toujours hydrater de telles applications pour fournir une interactivité riche côté client. Cette technique est communément appelée génération de site statique (SSG), également connue sous le nom de [JAMStack](https://jamstack.org/what-is-jamstack/).

Il existe deux types de SSG : monopage et multi-page. Les deux types pré-rendent le site en HTML statique, la différence étant que :

* Après le chargement initial de la page, une SSG à une seule page "hydrate" la page en une SPA. Cela nécessite un payload JS plus important et un coût d'hydratation plus élevé, mais les navigations ultérieures seront plus rapides, car il n'aura qu'à mettre à jour partiellement le contenu de la page au lieu de recharger toute la page.

* Une SSG à plusieurs pages charge une nouvelle page à chaque navigation. L'avantage est qu'elle peut livrer un JS minimal - ou pas du tout s'il n'y a pas besoin d'interaction ! Certains frameworks SSG à plusieurs pages, tels que [Astro](https://astro.build/) prennent également en charge une "hydratation partielle" - ce qui vous permet d'utiliser des composants Vue pour créer des "îlots" interactifs à l'intérieur de l'HTML statique.

Les SSG monopages conviennent mieux si vous attendez une interactivité non négligeable, des sessions profondes ou des éléments / états persistants à travers les navigations. Dans le cas contraire, une SSG à plusieurs pages serait un choix plus judicieux.

L'équipe Vue maintient également un générateur de site statique appelé [VitePress](https://vitepress.dev/), qui alimente le site web que vous êtes en train de lire en ce moment même! VitePress prend en charge les deux types de SSG. [Nuxt](https://nuxt.com/) prend également en charge le SSG. Vous pouvez même mélanger SSR et SSG pour différentes routes dans la même application Nuxt.

## Au-delà du web {#beyond-the-web}

Bien que Vue soit principalement conçu pour construire des applications Web, il n'est en aucun cas limité au navigateur. Vous pouvez :

* Construire des applications de bureau avec [Electron](https://www.electronjs.org/) ou [Wails](https://wails.io)
* Construire des applications mobiles avec [Ionic Vue](https://ionicframework.com/docs/vue/overview)
* Construire des applications de bureau et mobile à partir du même code avec [Quasar](https://quasar.dev/) ou [Tauri](https://tauri.app)
* Créez des expériences 3D WebGL avec [TresJS](https://tresjs.org/)
* Utiliser l'API de [rendu personnalisé](/api/custom-renderer) de Vue pour construire des rendus personnalisés comme ceux du [terminal](https://github.com/vue-terminal/vue-termui) !

---

---
url: /guide/extras/rendering-mechanism.md
---

# Mécanismes de rendu {#rendering-mechanism}

Comment Vue fait pour partir d'un template et le transformer en nœuds du DOM ? Comment Vue met-il à jour ces nœuds du DOM de manière efficace ? Nous allons tenter d'élucider ces questions en nous plongeant dans les mécanismes de rendu internes de Vue.

## DOM virtuel {#virtual-dom}

Vous avez probablement entendu parler du terme "virtual DOM", sur lequel le système de rendu de Vue s'appuie.

Le DOM virtuel (VDOM) est un concept de programmation dans lequel une représentation idéale, ou "virtuelle", d'une interface utilisateur est conservée en mémoire et synchronisée avec le DOM "réel". Le concept a été lancé par [React](https://react.dev/), et a été adapté dans de nombreux autres frameworks avec différentes implémentations, y compris Vue.

Le DOM virtuel est plus un modèle qu'une technologie spécifique, il n'y a donc pas d'implémentation canonique. Nous pouvons illustrer ce concept à l'aide d'un exemple simple :

```js
const vnode = {
  type: 'div',
  props: {
    id: 'hello'
  },
  children: [
    /* d'autres vnodes */
  ]
}
```

Ici, un `vnode` est un objet JavaScript simple (un "nœud virtuel") représentant un élément `<div>`. Il contient toutes les informations dont nous avons besoin pour créer l'élément réel. Il contient également d'autres vnodes enfants, ce qui en fait la racine d'un arbre du DOM virtuel.

Un moteur d'exécution peut parcourir un arbre du DOM virtuel et construire un arbre du DOM réel à partir de celui-ci. Ce processus est appelé le **montage**.

Si nous avons deux copies d'arbres du DOM virtuel, le moteur de rendu peut également parcourir et comparer les deux arbres, en déterminant les différences, et appliquer ces changements au DOM réel. Ce processus est appelé **patch**, également connu sous le nom de "diffing" ou "réconciliation".

Le principal avantage du DOM virtuel est qu'il donne au développeur la possibilité de créer, inspecter et composer de manière programmatique les structures d'interface utilisateur souhaitées de façon déclarative, tout en laissant la manipulation directe du DOM au moteur de rendu.

## Pipeline de rendu {#render-pipeline}

Au niveau le plus élevé, voici ce qui se passe lorsqu'un composant Vue est monté :

1. **Compilation** : Les templates Vue sont compilés en **fonctions de rendu** : fonctions qui retournent des arbres du DOM virtuel. Cette étape peut être effectuée soit à l'avance via un outil de build, soit à la volée en utilisant le compilateur d'exécution.

2. **Montage** : Le moteur d'exécution invoque les fonctions de rendu, parcourt l'arbre du DOM virtuel retourné et crée des nœuds DOM réels en fonction. Cette étape est réalisée comme un [effet réactif](./reactivity-in-depth), et garde donc la trace de toutes les dépendances réactives qui ont été utilisées.

3. **Correction** (Patch) : Quand une dépendance utilisée pendant le montage change, l'effet est ré-exécuté. Cette fois, un nouvel arbre du DOM virtuel mis à jour est créé. Le moteur d'exécution parcourt le nouvel arbre, le compare avec l'ancien et applique les mises à jour nécessaires au DOM réel.

![render pipeline](./images/render-pipeline.png)

## Templates vs. Fonctions de rendu {#templates-vs-render-functions}

Les templates Vue sont compilés en fonctions de rendu du DOM virtuel. Vue fournit également des API qui nous permettent de sauter l'étape de compilation des templates et de créer directement des fonctions de rendu. Celles-ci sont plus flexibles que les templates pour incorporer des logiques très dynamiques, car vous pouvez travailler avec les vnodes en utilisant toute la puissance de JavaScript.

Dans ce cas, pourquoi Vue recommande-t-il les templates par défaut ? Il y a un plusieurs raisons :

1. Les templates se rapprochent du HTML réel. Il est donc plus facile de réutiliser des extraits HTML existants, d'appliquer les meilleures pratiques en matière d'accessibilité, de créer un style avec du CSS, et pour les designers de comprendre le code et de le modifier.

2. Les templates sont plus faciles à analyser statiquement en raison de leur syntaxe plus déterministe. Cela permet au compilateur de templates de Vue d'appliquer de nombreuses optimisations au moment de la compilation afin d'améliorer les performances du DOM virtuel (que nous aborderons plus loin).

En pratique, les templates sont suffisants pour la plupart des cas d'utilisation d'une application. Les fonctions de rendu ne sont généralement utilisées que dans les composants réutilisables qui doivent gérer une logique de rendu hautement dynamique. L'utilisation des fonctions de rendu est abordée plus en détail dans [Fonctions de rendu et JSX](./render-function).

## DOM virtuel basé sur la compilation {#compiler-informed-virtual-dom}

L'implémentation du DOM virtuel dans React et la plupart de ses autres implémentations sont purement basées sur l'exécution : l'algorithme de réconciliation ne peut pas faire d'hypothèses sur l'arbre du DOM virtuel entrant, il doit donc traverser entièrement l'arbre et différencier les props de chaque vnode afin d'assurer la correction. En outre, même si une partie de l'arbre ne change jamais, de nouveaux vnodes sont toujours créés pour eux à chaque nouveau rendu, ce qui entraîne une charge mémoire inutile. C'est l'un des aspects les plus critiqués du DOM virtuel : le processus de réconciliation quelque peu brutal sacrifie l'efficacité au profit de la déclarativité et de l'exactitude.

Cependant d'autres façons de faire existent. Dans Vue, le framework a le contrôle à la fois pendant la compilation et l'exécution. Cela nous permet de mettre en œuvre de nombreuses optimisations au moment de la compilation dont seul un moteur de rendu étroitement intégré peut tirer parti. Le compilateur peut analyser statiquement le template et laisser des indications dans le code généré afin que le moteur d'exécution puisse gagner du temps lorsque cela est possible. Dans le même temps, l'utilisateur peut toujours avoir le contrôle jusqu'à la fonction de rendu pour agir de manière plus directe lorsque cela est nécessaire. Nous appelons cette approche hybride le **DOM virtuel basé sur la compilation**.

Nous aborderons ci-dessous quelques optimisations importantes réalisées par le compilateur de templates Vue dans le but d'améliorer les performances d'exécution du DOM virtuel.

### Cache Statique {#cache-static}

Il arrive régulièrement que certaines parties d'un template ne contiennent pas de liaisons dynamiques :

```vue-html{2-3}
<div>
  <div>foo</div> <!-- en cache -->
  <div>bar</div> <!-- en cache -->
  <div>{{ dynamic }}</div>
</div>
```

[Inspection dans l'explorateur de template](https://template-explorer.vuejs.org/#eyJzcmMiOiI8ZGl2PlxuICA8ZGl2PmZvbzwvZGl2PiA8IS0tIGNhY2hlZCAtLT5cbiAgPGRpdj5iYXI8L2Rpdj4gPCEtLSBjYWNoZWQgLS0+XG4gIDxkaXY+e3sgZHluYW1pYyB9fTwvZGl2PlxuPC9kaXY+XG4iLCJvcHRpb25zIjp7ImhvaXN0U3RhdGljIjp0cnVlfX0=)

Les divs `foo` et `bar` sont statiques - recréer des vnodes et les différencier à chaque rendu est inutile. Le moteur de rendu crée ces vnodes lors du rendu initial, les met en cache et réutilise les mêmes vnodes lors de chaque rendu ultérieur. Le moteur de rendu est également capable de ne pas les différencier quand il remarque que l'ancien et le nouveau vnode sont les mêmes.

En outre, lorsqu'il y a suffisamment d'éléments statiques consécutifs, ils seront condensés en un seul "vnode statique" qui contient une simple chaîne de caractères HTML pour tous ces nœuds ([Exemple](https://template-explorer.vuejs.org/#eyJzcmMiOiI8ZGl2PlxuICA8ZGl2IGNsYXNzPVwiZm9vXCI+Zm9vPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmb29cIj5mb288L2Rpdj5cbiAgPGRpdiBjbGFzcz1cImZvb1wiPmZvbzwvZGl2PlxuICA8ZGl2IGNsYXNzPVwiZm9vXCI+Zm9vPC9kaXY+XG4gIDxkaXYgY2xhc3M9XCJmb29cIj5mb288L2Rpdj5cbiAgPGRpdj57eyBkeW5hbWljIH19PC9kaXY+XG48L2Rpdj4iLCJzc3IiOmZhbHNlLCJvcHRpb25zIjp7ImhvaXN0U3RhdGljIjp0cnVlfX0=)). Ces vnodes statiques sont montés en modifiant directement `innerHTML`.

### Marques de correction {#patch-flags}

Nous pouvons également déduire de nombreuses informations concernant un élément unique possédant des liaisons dynamiques au moment de la compilation :

```vue-html
<!-- seulement une liaison de classe -->
<div :class="{ active }"></div>

<!-- seulement des liaisons de value et de l'id -->
<input :id="id" :value="value">

<!-- seulement un texte -->
<div>{{ dynamic }}</div>
```

[Inspection dans l'explorateur de template](https://template-explorer.vuejs.org/#eyJzcmMiOiI8ZGl2IDpjbGFzcz1cInsgYWN0aXZlIH1cIj48L2Rpdj5cblxuPGlucHV0IDppZD1cImlkXCIgOnZhbHVlPVwidmFsdWVcIj5cblxuPGRpdj57eyBkeW5hbWljIH19PC9kaXY+Iiwib3B0aW9ucyI6e319)

Lors de la génération du code de la fonction de rendu pour ces éléments, Vue encode le type de mise à jour dont chacun d'entre eux a besoin directement dans l'appel de création de vnode :

```js{3}
createElementVNode("div", {
  class: _normalizeClass({ active: _ctx.active })
}, null, 2 /* CLASS */)
```

Le dernier argument, `2`, est une [option de correction](https://github.com/vuejs/core/blob/main/packages/shared/src/patchFlags.ts). Un élément peut avoir plusieurs marques de correction, qui seront fusionnées en un seul nombre. Le moteur d'exécution peut alors vérifier les marques en utilisant des [opérations sur les bits](https://en.wikipedia.org/wiki/Bitwise_operation) pour déterminer s'il doit effectuer certaines opération :

```js
if (vnode.patchFlag & PatchFlags.CLASS /* 2 */) {
  // met à jour la classe de l'élément
}
```

Les vérifications par bit sont extrêmement rapides. Grâce aux marques de correction, Vue est en mesure d'effectuer le moins d'opérations possible lors de la mise à jour des éléments avec des liaisons dynamiques.

Vue encode également le type des enfants d'un vnode. Par exemple, un template qui possède plusieurs nœuds racines est représenté comme un fragment. Dans la plupart des cas, nous savons avec certitude que l'ordre de ces nœuds racines ne changera jamais, de sorte que cette information peut également être fournie au moment de l'exécution en tant qu'indicateur de patch :

```js{4}
export function render() {
  return (_openBlock(), _createElementBlock(_Fragment, null, [
    /* enfants */
  ], 64 /* STABLE_FRAGMENT */))
}
```

Lors de l'exécution, la réconciliation de l'ordre des enfants pour le fragment racine peut donc être totalement ignorée.

### Réduction d'un arbre {#tree-flattening}

Si vous regardez à nouveau le code généré dans l'exemple précédent, vous remarquerez que la racine de l'arbre du DOM virtuel retourné est créée en utilisant un appel spécial à `createElementBlock()` :

```js{2}
export function render() {
  return (_openBlock(), _createElementBlock(_Fragment, null, [
    /* enfants */
  ], 64 /* STABLE_FRAGMENT */))
}
```

Conceptuellement, un "bloc" est une partie du template qui a une structure interne stable. Dans notre cas, le modèle template n'a qu'un seul bloc car il ne contient pas de directives structurelles comme `v-if` et `v-for`.

Chaque bloc traque tous les nœuds descendants (pas seulement les enfants directs) possédant des marques de correction. Par exemple :

```vue-html{3,5}
<div> <!-- root block -->
  <div>...</div>         <!-- non traqué -->
  <div :id="id"></div>   <!-- traqué -->
  <div>                  <!-- non traqué -->
    <div>{{ bar }}</div> <!-- traqué -->
  </div>
</div>
```

Il en résulte un tableau réduit qui ne contient que les nœuds descendants dynamiques :

```
div (block root)
- div with :id binding
- div with {{ bar }} binding
```

Lorsque ce composant doit effectuer un nouveau rendu, il ne doit parcourir que l'arbre réduit au lieu de l'arbre complet. C'est ce qu'on appelle la réduction de l'arbre (**Tree Flattening**), et cela réduit considérablement le nombre de nœuds qui doivent être traversés pendant la réconciliation virtuelle du DOM. Toutes les parties statiques du template sont ignorées.

Les directives `v-if` et `v-for` vont créer de nouveaux nœuds pour un bloc :

```vue-html
<div> <!-- bloc racine -->
  <div>
    <div v-if> <!-- bloc if -->
      ...
    </div>
  </div>
</div>
```

Un bloc enfant est traqué à l'intérieur du tableau des descendants dynamiques du bloc parent. Cela permet au bloc parent de conserver une structure stable.

### Conséquences sur l'hydratation SSR {#impact-on-ssr-hydration}

Les marques de correction et la réduction des arbres améliorent également considérablement les performances de Vue en matière d'[hydratation SSR](/guide/scaling-up/ssr#client-hydration) :

* L'hydratation d'un seul élément peut utiliser des chemins rapides basés sur les marques de correction du vnode correspondant.

* Seuls les nœuds de bloc et leurs descendants dynamiques doivent être parcourus pendant l'hydratation, ce qui permet d'obtenir une hydratation partielle au niveau du template.

---

---
url: /ecosystem/newsletters.md
---
# Newsletters de la communauté {#community-newsletters}

Il existe de nombreuses newsletters et de nombreux blogs de la communauté consacrés à Vue qui vous informent des dernières nouvelles et des événements survenus dans l'écosystème Vue. Voici une liste non exhaustive de celles et ceux qui sont actifs et sur lesquels nous sommes tombés :

* [Vue.js Feed](https://vuejsfeed.com/)
* [Michael Thiessen](https://michaelnthiessen.com/newsletter)
* [Jakub Andrzejewski](https://dev.to/jacobandrewsky)
* [Weekly Vue News](https://weekly-vue.news/)
* [Vue.js Developers Newsletter](https://vuejsdevelopers.com/newsletter/)

Si vous en connaissez une newsletter ou un blog qui n'est pas encore inclus, veuillez soumettre une pull request en utilisant le lien ci-dessous !

---

---
url: /guide/essentials/watchers.md
---
# Observateurs {#watchers}

## Exemple Basique {#basic-example}

Les propriétés calculées nous permettent de calculer des valeurs dérivées de manière déclarative. Toutefois, il y a des cas dans lesquels nous devons réaliser des "effets de bord" en réaction aux changements de l'état - par exemple, muter le DOM, ou changer une autre partie de l'état en fonction du résultat d'une opération asynchrone.

Avec l'Options API, on peut utiliser l'[option `watch`](/api/options-state#watch) pour déclencher une fonction chaque fois qu'une propriété réactive change :

```js
export default {
  data() {
    return {
      question: '',
      answer: 'Questions usually contain a question mark. ;-)',
      loading: false
    }
  },
  watch: {
    // à chaque fois que question change, cette fonction sera exécutée
    question(newQuestion) {
      if (newQuestion.includes('?')) {
        this.getAnswer()
      }
    }
  },
  methods: {
    async getAnswer() {
      this.loading = true
      this.answer = 'Thinking...'
      try {
        const res = await fetch('https://yesno.wtf/api')
        this.answer = (await res.json()).answer
      } catch (error) {
        this.answer = 'Error! Could not reach the API. ' + error
      } finally {
        this.loading = false
      }
    }
  }
}
```

```vue-html
<p>
  Ask a yes/no question:
  <input v-model="question" :disabled="loading" />
</p>
<p>{{ answer }}</p>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9VE1v2zAM/SucLnaw1D70lqUbsiKH7rB1W4++aDYdq5ElTx9xgiD/fbT8lXZFAQO2+Mgn8pH0mW2aJjl4ZCu2trkRjfucKTw22jgosOReOjhnCqDgjseL/hvAoPNGjSeAvx6tE1qtIIqWo5Er26Ih088BteCt51KeINfKcaGAT5FQc7NP4NPNYiaQmhdC7VZQcmlxMF+61yUcWu7yajVmkabQVqjwgGZmzSuudmiX4CphofQqD+ZWSAnGqz5y9I4VtmOuS9CyGA9T3QCihGu3RKhc+gJtHH2JFld+EG5Mdug2QYZ4MSKhgBd11OgqXdipEm5PKoer0Jk2kA66wB044/EF1GtOSPRUCbUnryRJosnFnK4zpC5YR7205M9bLhyUSIrGUeVcY1dpekKrdNK6MuWNiKYKXt8V98FElDxbknGxGLCpZMi7VkGMxmjzv0pz1tvO4QPcay8LULoj5RToKoTN40MCEXyEQDJTl0KFmXpNOqsUxudN+TNFzzqdJp8ODutGcod0Alg34QWwsXsaVtIjVXqe9h5bC9V4B4ebWhco7zI24hmDVSEs/yOxIPOQEFnTnjzt2emS83nYFrhcevM6nRJhS+Ys9aoUu6Av7WqoNWO5rhsh0fxownplbBqhjJEmuv0WbN2UDNtDMRXm+zfsz/bY2TL2SH1Ec8CMTZjjhqaxh7e/v+ORvieQqvaSvN8Bf6HV0veSdG5fvSoo7Su/kO1D3f13SKInuz06VHYsahzzfl0yRj+s+3dKn9O9TW7HPrPLP624lFU=)

L'option `watch` supporte également comme clé un chemin délimité par des points :

```js
export default {
  watch: {
    // Remarque : seulement des chemins simples. Les expressions ne sont pas supportées.
    'some.nested.key'(newValue) {
      // ...
    }
  }
}
```

Avec la Composition API, nous pouvons utiliser la [fonction `watch`](/api/reactivity-core#watch) pour déclencher une fonction de rappel chaque fois qu'une partie d'un état réactif change :

```vue
<script setup>
import { ref, watch } from 'vue'

const question = ref('')
const answer = ref('Questions usually contain a question mark. ;-)')
const loading = ref(false)

// watch agit directement sur une ref
watch(question, async (newQuestion, oldQuestion) => {
  if (newQuestion.indexOf('?')) {
    loading.value = true
    answer.value = 'Thinking...'
    try {
      const res = await fetch('https://yesno.wtf/api')
      answer.value = (await res.json()).answer
    } catch (error) {
      answer.value = 'Error! Could not reach the API. ' + error
    } finally {
      loading.value = false
    }
  }
})
</script>

<template>
  <p>
    Ask a yes/no question:
    <input v-model="question" :disabled="loading" />
  </p>
  <p>{{ answer }}</p>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9U8Fy0zAQ/ZVFF9tDah96C2mZ0umhHKBAj7oIe52oUSQjyXEyGf87KytyoDC9JPa+p+e3b1cndtd15b5HtmQrV1vZeXDo++6Wa7nrjPVwAovtAgbh6w2M0Fqzg4xOZFxzXRvtPPzq0XlpNNwEbp5lRUKEdgPaVP925jnoXS+UOgKxvJAaxEVjJ+y2hA9XxUVFGdFIvT7LtEI5JIzrqjrbGozdOmikxdqTKqmIQOV6gvOkvQDhjrqGXOOQvCzAqCa9FHBzCyeuAWT7F6uUulZ9gy7PPmZFETmQjJV7oXoke972GJHY+Axkzxupt4FalhRcYHh7TDIQcqA+LTriikFIDy0G59nG+84tq+qITpty8G0lOhmSiedefSaPZ0mnfHFG50VRRkbkj1BPceVorbFzF/+6fQj4O7g3vWpAm6Ao6JzfINw9PZaQwXuYNJJuK/U0z1nxdTLT0M7s8Ec/I3WxquLS0brRi8ddp4RHegNYhR0M/Du3pXFSAJU285osI7aSuus97K92pkF1w1nCOYNlI534qbCh8tkOVasoXkV1+sjplLZ0HGN5Vc1G2IJ5R8Np5XpKlK7J1CJntdl1UqH92k0bzdkyNc8ZRWGGz1MtbMQi1esN1tv/1F/cIdQ4e6LJod0jZzPmhV2jj/DDjy94oOcZpK57Rew3wO/ojOpjJIH2qdcN2f6DN7l9nC47RfTsHg4etUtNpZUeJz5ndPPv32j9Yve6vE6DZuNvu1R2Tg==)

### Les types de sources de watch {#watch-source-types}

Le premier argument de `watch` peut être différents types de "sources" réactives : ça peut être une ref (y compris des refs calculées), un objet réactif, une fonction [accesseur](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description), ou un tableau de différentes sources :

```js
const x = ref(0)
const y = ref(0)

// simple ref
watch(x, (newX) => {
  console.log(`x is ${newX}`)
})

// accesseur
watch(
  () => x.value + y.value,
  (sum) => {
    console.log(`sum of x + y is: ${sum}`)
  }
)

// tableau de différentes sources
watch([x, () => y.value], ([newX, newY]) => {
  console.log(`x is ${newX} and y is ${newY}`)
})
```

Notez que vous ne pouvez pas observer une propriété d'un objet réactif de cette manière :

```js
const obj = reactive({ count: 0 })

// cela ne fonctionnera pas car on passe un nombre à watch()
watch(obj.count, (count) => {
  console.log(`Count est égal à: ${count}`)
})
```

À la place, utilisez un accesseur :

```js
// à la place, utilisez un accesseur :
watch(
  () => obj.count,
  (count) => {
    console.log(`Count est égal à: ${count}`)
  }
)
```

## Observateurs profonds {#deep-watchers}

`watch` est par défaut superficiel : la fonction de rappel ne sera déclenchée que lorsque la propriété observée se verra assigner une nouvelle valeur - elle ne sera pas déclenchée lors du changement d'une propriété imbriquée. Si vous voulez que la fonction de rappel s'exécute à chaque mutation imbriquée, vous devez utiliser un observateur profond :

```js
export default {
  watch: {
    someObject: {
      handler(newValue, oldValue) {
        // Remarque: `newValue` sera égale à `oldValue` ici
        // à chaque mutation imbriquée tant que l'objet lui-même
        // n'a pas été remplacé.
      },
      deep: true
    }
  }
}
```

Lorsque vous appelez `watch()` directement sur un objet réactif, un observateur profond va implicitement être créé - la fonction de rappel sera déclenchée à chaque mutation imbriquée :

```js
const obj = reactive({ count: 0 })

watch(obj, (newValue, oldValue) => {
  // exécution à chaque mutation d'une propriété imbriquée
  // Remarque : `newValue` sera égale à `oldValue` ici
  // car elles pointent toutes les deux sur le même objet !
})

obj.count++
```

Il ne faut pas confondre avec un accesseur qui retourne un objet réactif - dans ce dernier cas, la fonction de rappel ne sera exécutée que si l'accesseur retourne un objet différent :

```js
watch(
  () => state.someObject,
  () => {
    // exécution seulement lorsque state.someObject est remplacé
  }
)
```

Toutefois, vous pouvez transformer ce second cas en un observateur profond en utilisant explicitement l'option `deep` :

```js
watch(
  () => state.someObject,
  (newValue, oldValue) => {
    // Remarque : `newValue` sera égale à `oldValue` ici
    // *sauf si* state.someObject a été remplacé
  },
  { deep: true }
)
```

À partir de la version 3.5, l'option `deep` peut aussi être un nombre indiquant la profondeur maximale à traverser, c'est-à-dire de combien de niveaux Vue traverse un objet avec des propriétés imbriquées.

:::warning À utiliser avec précaution
Les observateurs profonds nécessitent de traverser toutes les propriétés imbriquées de l'objet observé, et peuvent être consommateurs de ressources lorsqu'ils sont utilisés sur des structures importantes de données. Utilisez-les seulement si nécessaire, en ayant conscience des implications en matière de performances.
:::

## Les observateurs impatients {#eager-watchers}

`watch` fonctionne à la volée par défaut : la fonction de rappel ne sera pas appelée tant que la source observée n'aura pas changé. Mais dans certains cas, on peut souhaiter que cette même logique de rappel soit exécutée de manière précoce - par exemple, on peut vouloir récupérer des données initiales, puis les récupérer de nouveau chaque fois qu'un état pertinent change.

Nous pouvons forcer la fonction de rappel d'un observateur à être exécutée immédiatement en la déclarant via un objet avec une fonction de gestion et l'option `immediate: true` :

```js
export default {
  // ...
  watch: {
    question: {
      handler(newQuestion) {
        // cela sera exécuté immédiatement à la création du composant
      },
      // force l'exécution précoce de la fonction de rappel
      immediate: true
    }
  }
  // ...
}
```

L'exécution initiale d'une fonction de gestion aura lieu juste avant le hook `created`. Vue aura déjà traité les options `data`, `computed`, et `méthodes`, donc ces propriétés seront disponibles à la première invocation.

Nous pouvons forcer l'exécution immédiate d'un observateur en passant l'option `immediate: true` :

```js
watch(
  source,
  (newValue, oldValue) => {
    // execution immédiate, puis à chaque fois que `source` change
  },
  { immediate: true }
)
```

## Observateurs unitaires {#once-watchers}

* Supporté à partir de la version 3.4

La fonction de rappel de l'observateur sera exécutée dès lors qu'une source observée change. Si vous voulez que la fonction de rappel soit déclenchée une seule fois quand il y a un changement, utilisez l'option `once: true`.

```js
export default {
  watch: {
    source: {
      handler(newValue, oldValue) {
        // quand `source` change, déclenchée une seule fois
      },
      once: true
    }
  }
}
```

```js
watch(
  source,
  (newValue, oldValue) => {
    // quand `source` change, déclenchée une seule fois
  },
  { once: true }
)
```

## `watchEffect()` \*\* {#watcheffect}

Il est commun pour la fonction de l'observateur d'utiliser exactement le même état réactif comme source. Par exemple, considérez le code suivant, qui utilise un observateur pour charger une ressource distante à chaque changement de la ref `todoId` :

```js
const todoId = ref(1)
const data = ref(null)

watch(
  todoId,
  async () => {
    const response = await fetch(
      `https://jsonplaceholder.typicode.com/todos/${todoId.value}`
    )
    data.value = await response.json()
  },
  { immediate: true }
)
```

En particulier, remarquez comment l'observateur utilise doublement `todoId`, une fois comme source, ensuite à nouveau à l'intérieur de la fonction.

Cela peut être simplifié par [`watchEffect()`](/api/reactivity-core#watcheffect). `watchEffect()` nous permet d'effectuer des effets de bord immédiatement tout en traquant automatiquement les dépendances réactives de cet effet. L'exemple précédent peut être réécrit de la sorte :

```js
watchEffect(async () => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/todos/${todoId.value}`
  )
  data.value = await response.json()
})
```

Ici, la fonction sera exécutée immédiatement, il n'y a pas besoin de spécifier `immediate : true`. Pendant son exécution, elle suivra automatiquement `todoId.value` comme une dépendance (similaire aux propriétés calculées). Chaque fois que `todoId.value` change, la fonction sera exécutée à nouveau. Avec `watchEffect()`, nous n'avons plus besoin de passer explicitement `todoId` comme source.

Vous pouvez vous référer à [cet exemple](/examples/#fetching-data) avec `watchEffect` et une récupération de données en action.

Pour des exemples comme ceux-ci, avec une seule dépendance, le bénéfice de `watchEffect()` est relativement faible. Mais pour les surveillances qui ont plusieurs dépendances, l'utilisation de `watchEffect()` supprime la charge de maintenir la liste des dépendances manuellement. De plus, si vous devez surveiller plusieurs propriétés dans une structure de données imbriquée, `watchEffect()` peut s'avérer plus efficace qu'un observateur profond, car il ne suivra que les propriétés qui sont utilisées dans la fonction, plutôt que de les suivre toutes de manière récursive.

:::tip
`watchEffect` traque les dépendances seulement pendant son exécution **synchrone**. Lorsque vous l'utilisez avec un rappel asynchrone, seules les propriétés accédées avant le premier événement `await` seront traquées.
:::

### `watch` vs. `watchEffect` {#watch-vs-watcheffect}

`watch` et `watchEffect` permettent tous les deux de réaliser des effets de bord. Leur principale différence réside dans la manière dont ils traquent leurs dépendances réactives :

* `watch` traque seulement la source explicitement observée . De plus, le rappel n'est déclenché que lorsque la source a bien changé. `watch` sépare la traque des dépendances et les effets de bord, ce qui nous donne plus de contrôle sur le moment où le rappel doit être exécuté.

* `watchEffect`, d'un autre côté, combine la traque des dépendances et les effets de bord en une phase. Il traque automatiquement chaque propriété réactive accédée durant son exécution synchrone. Cela est plus pratique et rend généralement le code plus concis, mais rend les dépendances réactives moins explicites.

## Nettoyage des effets de bord {#side-effect-cleanup}

Parfois, nous pouvons effectuer des effets secondaires, par exemple des requêtes asynchrones, dans un observateur :

```js
watch(id, (newId) => {
  fetch(`/api/${newId}`).then(() => {
    // logique de rappel
  })
})
```

```js
export default {
  watch: {
    id(newId) {
      fetch(`/api/${newId}`).then(() => {
        // logique de rappel
      })
    }
  }
}
```

Mais que se passe-t-il si `id` change avant que la requête ne soit terminée ? Lorsque la requête précédente se termine, elle déclenche toujours le callback avec une valeur d'ID qui est déjà périmée. Idéalement, nous voulons pouvoir annuler la requête périmée lorsque `id` change pour une nouvelle valeur.

Nous pouvons utiliser l'API [`onWatcherCleanup()`](/api/reactivity-core#onwatchercleanup)  pour enregistrer une fonction de nettoyage qui sera appelée lorsque l'observateur est invalidé et sur le point d'être réexécuté :

```js {10-13}
import { watch, onWatcherCleanup } from 'vue'

watch(id, (newId) => {
  const controller = new AbortController()

  fetch(`/api/${newId}`, { signal: controller.signal }).then(() => {
    // logique de rappel
  })

  onWatcherCleanup(() => {
    // annuler la demande périmée
    controller.abort()
  })
})
```

```js {12-15}
import { onWatcherCleanup } from 'vue'

export default {
  watch: {
    id(newId) {
      const controller = new AbortController()

      fetch(`/api/${newId}`, { signal: controller.signal }).then(() => {
        // logique de rappel
      })

      onWatcherCleanup(() => {
        // annuler la demande périmée
        controller.abort()
      })
    }
  }
}
```

Notez que `onWatcherCleanup` n'est supporté que dans Vue 3.5+ et doit être appelé pendant l'exécution synchrone d'une fonction d'effet `watchEffect` ou d'une fonction de callback `watch` : vous ne pouvez pas l'appeler après une instruction `await` dans une fonction asynchrone.

Alternativement, une fonction `onCleanup` est également transmise aux callbacks des observateurs en tant que troisième argument, et à la fonction d'effet `watchEffect` en tant que premier argument:

```js
watch(id, (newId, oldId, onCleanup) => {
  // ...
  onCleanup(() => {
    // logique de rappel
  })
})

watchEffect((onCleanup) => {
  // ...
  onCleanup(() => {
    // logique de rappel
  })
})
```

```js
export default {
  watch: {
    id(newId, oldId, onCleanup) {
      // ...
      onCleanup(() => {
        // logique de rappel
      })
    }
  }
}
```

La fonction `onCleanup` transmise via l'argument de fonction est liée à l'instance de l'observateur, elle n'est donc pas soumise à la contrainte synchrone de `onWatcherCleanup`.

## Timing de nettoyage des rappels {#callback-flush-timing}

Lorsque vous mutez un état réactif, cela peut déclencher à la fois la mise à jour des composants Vue et des rappels d'observateur que vous avez créés.

Comme pour les mises à jour de composants, les rappels de l'observateur créés par l'utilisateur sont regroupés afin d'éviter les invocations en double. Par exemple, nous ne voulons probablement pas qu'un observateur se déclenche mille fois si nous introduisons de manière synchrone mille éléments dans un tableau observé.

Par défaut, le rappel d'un observateur est appelé **après** les mises à jour du composant parent (le cas échéant), et **avant** les mises à jour du DOM du composant propriétaire. Cela signifie que si vous tentez d'accéder au DOM du composant propriétaire à l'intérieur d'un callback de l'observateur, le DOM sera dans un état de pré-mise à jour.

### Observateurs a posteriori {#post-watchers}

Si vous voulez accéder au DOM **après** que Vue l'ait mis à jour, vous devez spécifier l'option `flush: 'post'` :

```js{6}
export default {
  // ...
  watch: {
    key: {
      handler() {},
      flush: 'post'
    }
  }
}
```

```js{2,6}
watch(source, callback, {
  flush: 'post'
})

watchEffect(callback, {
  flush: 'post'
})
```

Le `watchEffect()` "post-flush" a également un pseudonyme de confort, `watchPostEffect()`:

```js
import { watchPostEffect } from 'vue'

watchPostEffect(() => {
  /* exécution après la mise à jour de Vue */
})
```

### Observateurs synchrones {#sync-watchers}

Il est également possible de créer un observateur qui se déclenche de manière synchrone, avant toute mise à jour gérée par Vue.

```js{6}
export default {
  // ...
  watch: {
    key: {
      handler() {},
      flush: 'sync'
    }
  }
}
```

```js{2,6}
watch(source, callback, {
  flush: 'sync'
})

watchEffect(callback, {
  flush: 'sync'
})
```

Sync `watchEffect()` a également un alias de commodité, `watchSyncEffect()` :

```js
import { watchSyncEffect } from 'vue'

watchSyncEffect(() => {
  /* exécuté de manière synchrone lors d'une modification réactive des données */
})
```

:::warning A utiliser avec précaution
Les observateurs synchrones n'ont pas de fonction de mise en lot et se déclenchent à chaque fois qu'une mutation réactive est détectée. Il est possible de les utiliser pour surveiller de simples valeurs booléennes, mais il faut éviter de les utiliser sur des sources de données qui peuvent être mutées plusieurs fois de manière synchrone, par exemple des tableaux.
:::

## `this.$watch()` \* {#this-watch}

Il est également possible de créer des observateurs de manière impérative en utilisant [la méthode d'instance `$watch()`](/api/component-instance#watch):

```js
export default {
  created() {
    this.$watch('question', (newQuestion) => {
      // ...
    })
  }
}
```

Cela est utile lorsque vous avez besoin de paramétrer un observateur de manière conditionnelle, ou de seulement observer quelque chose en réponse à une interaction de l'utilisateur. Cela vous permet également d'arrêter l'observateur précocement.

## Arrêter un observateur {#stopping-a-watcher}

Les observateurs déclarés via l'option `watch` ou la méthode d'instance `$watch()` sont automatiquement arrêtés lorsque le composant propriétaire est démonté, donc dans la plupart des cas vous n'avez pas à vous soucier d'arrêter les observateurs vous-même.

Dans les rares cas où vous auriez besoin d'arrêter un observateur avant que le composant propriétaire ne soit démonté, l'API `$watch()` retourne une fonction permettant de le faire :

```js
const unwatch = this.$watch('foo', callback)

// ...lorsque l'observateur n'est plus nécessaire :
unwatch()
```

Les observateurs déclarés de manière synchrone à l'intérieur de `setup()` ou `<script setup>` sont liés à l'instance du composant propriétaire, et seront automatiquement arrêtés lorsque ce dernier sera démonté. Dans la plupart des cas, vous n'avez pas à vous soucier d'arrêter les observateurs vous-même.

La clé ici est que l'observateur doit être créé de **manière synchrone** : si l'observateur est créé dans un rappel asynchrone, il ne sera pas lié au composant propriétaire et devra être arrêté manuellement afin d'éviter des fuites de mémoire. Voici un exemple :

```vue
<script setup>
import { watchEffect } from 'vue'

// celui-ci sera automatiquement arrêté
watchEffect(() => {})

// ...celui-là non!
setTimeout(() => {
  watchEffect(() => {})
}, 100)
</script>
```

Pour arrêter manuellement un observateur, utilisez la fonction de gestion qu'il retourne. Cela fonctionne pour `watch` et pour `watchEffect`:

```js
const unwatch = watchEffect(() => {})

// ...plus tard, lorsqu'il n'est plus nécessaire
unwatch()
```

Notez que les cas où vous devriez être amenés à créer des observateurs de manière asynchrone sont rares, et une création synchrone devrait être choisie lorsque c'est possible. Si vous devez attendre des données asynchrones, vous pouvez intégrer votre logique d'observation dans une condition :

```js
// données à récupérer de manière asynchrone
const data = ref(null)

watchEffect(() => {
  if (data.value) {
    // on fait quelque chose lorsque les données sont chargées
  }
})
```

---

---
url: /api/options-composition.md
---
# Options : Composition {#options-composition}

## provide {#provide}

Fournit des valeurs qui peuvent être injectées par les composants descendants.

* **Type :**

  ```ts
  interface ComponentOptions {
    provide?: object | ((this: ComponentPublicInstance) => object)
  }
  ```

* **Détails**

  `provide` et [`inject`](#inject) sont utilisées ensemble pour permettre à un composant ancêtre de servir d'injecteur de dépendances pour tous ses descendants, peu importe la profondeur de la hiérarchie des composants, tant qu'ils sont de la même lignée.

  L'option `provide` doit être soit un objet, soit une fonction qui renvoie un objet. Cet objet contient les propriétés qui sont disponibles pour l'injection dans ses descendants. Vous pouvez utiliser des symboles comme clés dans cet objet.

* **Exemple**

  Utilisation basique :

  ```js
  const s = Symbol()

  export default {
    provide: {
      foo: 'foo',
      [s]: 'bar'
    }
  }
  ```

  Utilisation d'une fonction pour fournir un état par composant :

  ```js
  export default {
    data() {
      return {
        msg: 'foo'
      }
    }
    provide() {
      return {
        msg: this.msg
      }
    }
  }
  ```

  Notez que dans l'exemple ci-dessus, le `msg` fourni ne sera PAS réactif. Consultez [travailler avec la réactivité](/guide/components/provide-inject#working-with-reactivity) pour plus de détails.

* **Voir aussi** [Provide / Inject](/guide/components/provide-inject)

## inject {#inject}

Déclare les propriétés à injecter dans le composant actuel en les localisant à partir des fournisseurs ancêtres.

* **Type :**

  ```ts
  interface ComponentOptions {
    inject?: ArrayInjectOptions | ObjectInjectOptions
  }

  type ArrayInjectOptions = string[]

  type ObjectInjectOptions = {
    [key: string | symbol]:
      | string
      | symbol
      | { from?: string | symbol; default?: any }
  }
  ```

* **Détails**

  L'option `inject` doit être soit :

  * Un tableau de chaînes de caractères, ou
  * Un objet où les clés sont le nom de la liaison locale et la valeur est soit :
    * La clé (chaîne de caractères ou symbole) à rechercher dans les injections disponibles, ou bien
    * Un objet où :
      * La propriété `from` est la clé (chaîne de caractères ou symbole) à rechercher dans les injections disponibles, et
      * La propriété `default` est utilisée comme valeur de secours. Comme pour les valeurs par défaut des props, une fonction *factory* est nécessaire pour les types objets afin d'éviter le partage de valeurs entre plusieurs instances de composants.

  Une propriété injectée sera `undefined` si aucune propriété correspondante ou valeur par défaut n'a été fournie.

  Notez que les liaisons injectées ne sont PAS réactives. Ceci est intentionnel. Cependant, si la valeur injectée est un objet réactif, les propriétés de cet objet restent réactives. Consultez [travailler avec la réactivité](/guide/components/provide-inject#working-with-reactivity) pour plus de détails.

* **Exemple**

  Utilisation basique :

  ```js
  export default {
    inject: ['foo'],
    created() {
      console.log(this.foo)
    }
  }
  ```

  En utilisant une valeur injectée comme valeur par défaut pour une prop :

  ```js
  const Child = {
    inject: ['foo'],
    props: {
      bar: {
        default() {
          return this.foo
        }
      }
    }
  }
  ```

  En utilisant une valeur injectée comme entrée de données :

  ```js
  const Child = {
    inject: ['foo'],
    data() {
      return {
        bar: this.foo
      }
    }
  }
  ```

  Les injections peuvent être optionnelles avec une valeur par défaut :

  ```js
  const Child = {
    inject: {
      foo: { default: 'foo' }
    }
  }
  ```

  Si l'injection doit se faire à partir d'une propriété portant un nom différent, utilisez `from` pour désigner la propriété source :

  ```js
  const Child = {
    inject: {
      foo: {
        from: 'bar',
        default: 'foo'
      }
    }
  }
  ```

  Comme pour les valeurs par défaut des props, vous devez utiliser une fonction *factory* pour les valeurs non primitives :

  ```js
  const Child = {
    inject: {
      foo: {
        from: 'bar',
        default: () => [1, 2, 3]
      }
    }
  }
  ```

* **Voir aussi** [Provide / Inject](/guide/components/provide-inject)

## mixins {#mixins}

Un tableau d'objets d'options à introduire dans le composant actuel.

* **Type :**

  ```ts
  interface ComponentOptions {
    mixins?: ComponentOptions[]
  }
  ```

* **Détails**

  L'option `mixins` accepte un tableau d'objets mixins. Ces objets mixins peuvent contenir des options d'instance comme des objets d'instance normaux, et ils seront fusionnés avec les options éventuelles en utilisant la logique de fusion des options. Par exemple, si votre mixin contient un hook `created` et que le composant lui-même en possède un, les deux fonctions seront appelées.

  Les hooks des mixins sont appelés dans l'ordre où ils sont fournis, et sont appelés avant les propres hooks du composant.

  :::warning N'est plus recommandé
  Avec Vue 2, les mixins étaient le principal mécanisme pour créer des morceaux réutilisables des logiques de composants. Bien que les mixins continuent d'être pris en charge avec Vue 3, la [Composition API](/guide/reusability/composables) est désormais l'approche privilégiée pour la réutilisation du code entre les composants.
  :::

* **Exemple**

  ```js
  const mixin = {
    created() {
      console.log(1)
    }
  }

  createApp({
    created() {
      console.log(2)
    },
    mixins: [mixin]
  })

  // => 1
  // => 2
  ```

## extends {#extends}

Un composant de la "classe de base" à partir duquel on peut étendre un composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    extends?: ComponentOptions
  }
  ```

* **Détails**

  Permet à un composant d'en étendre un autre, en héritant de ses options de composant.

  Du point de vue de l'implémentation, `extends` est presque identique à `mixins`. Le composant spécifié par `extends` sera traité comme s'il était le premier mixin.

  Cependant, `extends` et `mixins` expriment des intentions différentes. L'option `mixins` est principalement utilisée pour composer des morceaux de fonctionnalité, alors que `extends` est principalement concerné par l'héritage.

  Comme avec `mixins`, toutes les options (excepté pour `setup()`) seront fusionnées en utilisant la stratégie de fusion appropriée.

* **Exemple**

  ```js
  const CompA = { ... }

  const CompB = {
    extends: CompA,
    ...
  }
  ```

  :::warning Non recommandé pour la Composition API
  `extends` est conçu pour l'Options API et ne gère pas la fusion du hook `setup()`.

  Avec la Composition API, le modèle mental préféré pour la réutilisation logique est la « composition » plutôt que « l'héritage ». Si vous avez besoin de réutiliser la logique d'un composant dans un autre, envisagez d'extraire ce qui est pertinent dans un [Composable](/guide/reusability/composables#composables).

  Si vous avez toujours l'intention d'« étendre » un composant à l'aide de la Composition API, vous pouvez appeler le `setup()` du composant de base dans le `setup()` du composant d'extension :

  ```js
  import Base from './Base.js'
  export default {
    extends: Base,
    setup(props, ctx) {
      return {
        ...Base.setup(props, ctx),
        // liaisons locales
      }
    }
  }
  ```

  :::

---

---
url: /api/options-lifecycle.md
---
# Options : Cycle de vie {#options-lifecycle}

:::info Voir aussi
Pour en savoir plus sur l'utilisation partagée des hooks du cycle de vie, consultez [Guide - Les hooks du cycle de vie](/guide/essentials/lifecycle)
:::

## beforeCreate {#beforecreate}

Appelé lors de l'initialisation de l'instance.

* **Type :**

  ```ts
  interface ComponentOptions {
    beforeCreate?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Appelé immédiatement lorsque l'instance est initialisée, après la résolution des props.

  Ensuite les props seront définies comme des propriétés réactives et les états comme `data()` ou `computed` seront configurés.

  Notez que le hook `setup()` de la Composition API est appelé avant tous les hooks de l'Options API, même `beforeCreate()`.

## created {#created}

Appelé après que l'instance ait terminé de traiter toutes les options liées à l'état.

* **Type :**

  ```ts
  interface ComponentOptions {
    created?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Lorsque ce hook est appelé, les éléments suivants ont déjà été mis en place : données réactives, propriétés calculées, méthodes et observateurs. Cependant, la phase de montage n'a pas été lancée, et la propriété `$el` n'est encore disponible.

## beforeMount {#beforemount}

Appelé juste avant que le composant soit monté.

* **Type :**

  ```ts
  interface ComponentOptions {
    beforeMount?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Lorsque ce hook est appelé, le composant a fini de configurer son état réactif, mais aucun noeud du DOM n'a encore été créé. Il est sur le point d'exécuter son effet de rendu du DOM pour la première fois.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## mounted {#mounted}

Appelé après que le composant ait été monté.

* **Type :**

  ```ts
  interface ComponentOptions {
    mounted?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Un composant est considéré comme monté après que :

  * Tous ses composants enfants synchrones ont été montés (n'inclut pas les composants asynchrones ou les composants à l'intérieur des arbres `<Suspense>`).

  * Son propre arbre du DOM a été créé et inséré dans le conteneur parent. Notez que cela garantit que seulement l'arbre du DOM du composant est déjà placé dans le document, même si le conteneur racine de l'application y est.

  Ce hook est généralement utilisé pour effectuer des effets de bord qui nécessitent un accès au DOM rendu du composant, ou pour limiter le code lié au DOM au client dans une [application rendue par le serveur](/guide/scaling-up/ssr).

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## beforeUpdate {#beforeupdate}

Appelé juste avant que le composant ne soit sur le point de mettre à jour son arbre du DOM après un changement d'état réactif.

* **Type :**

  ```ts
  interface ComponentOptions {
    beforeUpdate?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Ce hook peut être utilisé pour accéder à l'état du DOM avant que Vue ne le mette à jour. Il est également possible de modifier l'état d'un composant à l'intérieur de ce hook.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## updated {#updated}

Appelé après que le composant ait mis à jour son arbre du DOM suite à un changement d'état réactif.

* **Type :**

  ```ts
  interface ComponentOptions {
    updated?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Le hook *updated* d'un composant parent est appelé après celui de ses composants enfants.

  Ce hook est appelé après toute mise à jour du DOM du composant, laquelle peut être causée par différents changements d'état. Si vous devez accéder au DOM mis à jour après un changement d'état spécifique, utilisez plutôt [nextTick()](/api/general#nexttick).

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

  :::warning
  Ne modifiez pas l'état du composant dans le hook *updated* - cela conduirait à une boucle de mises à jour infinie !
  :::

## beforeUnmount {#beforeunmount}

Appelé juste avant que l'instance d'un composant ne soit démontée.

* **Type :**

  ```ts
  interface ComponentOptions {
    beforeUnmount?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Lorsque ce hook est appelé, l'instance du composant est toujours totalement fonctionnelle.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## unmounted {#unmounted}

Appelé après que le composant ait été démonté.

* **Type :**

  ```ts
  interface ComponentOptions {
    unmounted?(this: ComponentPublicInstance): void
  }
  ```

* **Détails**

  Un composant est considéré comme démonté après que :

  * Tous ses composants enfants ont été démontés.

  * Tous ses effets réactifs associés (effet de rendu et propriétés calculées / observateurs créés pendant `setup()`) ont été arrêtés.

  Utilisez ce hook pour nettoyer manuellement les effets de bord créés, tels que les minuteurs, les écouteurs d'événements du DOM ou les connexions au serveur.

  **Ce hook n'est pas appelé pendant le rendu côté serveur.**

## errorCaptured {#errorcaptured}

Appelé lorsqu'une erreur venant d'un composant descendant a été capturée.

* **Type :**

  ```ts
  interface ComponentOptions {
    errorCaptured?(
      this: ComponentPublicInstance,
      err: unknown,
      instance: ComponentPublicInstance | null,
      info: string
    ): boolean | void
  }
  ```

* **Détails**

  Les erreurs peuvent être capturées à partir des sources suivantes :

  * Rendu de composants
  * Gestionnaires d'événements
  * Hooks de cycle de vie
  * Fonction `setup()`
  * Observateurs
  * Hooks de directives personnalisées
  * Hooks de transition

  Ce hook reçoit trois arguments : l'erreur, l'instance du composant qui a déclenché l'erreur, et une information sous forme de chaînes de caractères spécifiant le type de source de l'erreur.

  :::tip
  En production, le troisième argument (`info`) sera un code raccourci plutôt que toute la chaîne d'information. Vous pouvez trouver le code correspondant dans la [Référence des erreurs en production](/error-reference/#runtime-errors).
  :::

  Vous pouvez modifier l'état du composant dans `errorCaptured()` pour afficher un état d'erreur à l'utilisateur. Cependant, il est important de ne pas rendre le contenu original à l'origine de l'erreur, sinon le composant sera bloqué dans une boucle de rendu infinie.

  Le hook peut retourner `false` pour empêcher la propagation de l'erreur. Consultez les détails sur la propagation des erreurs ci-dessous.

  **Règles concernant la propagation des erreurs**

  * Par défaut, toutes les erreurs sont envoyées à [`app.config.errorHandler`](/api/application#app-config-errorhandler) au niveau de l'application si elle est définie, afin qu'elles puissent être signalées et analysées par un seul service à un seul endroit.

  * Si plusieurs hooks `errorCaptured` existent sur la chaîne descendante ou la chaîne ascendante d'un composant, ils seront tous invoqués sur la même erreur, suivant un ordre allant de bas en haut. Cela est comparable au mécanisme de *bubbling* des événements natifs du DOM.

  * Si le hook `errorCaptured` lui-même lance une erreur, cette erreur et l'erreur capturée originellement sont envoyées à `app.config.errorHandler`.

  * Un hook `errorCaptured` peut retourner `false` pour empêcher l'erreur de se propager plus loin. Cela revient à dire "cette erreur a été traitée et doit être ignorée". Cela empêchera tout autre hook `errorCaptured` ou `app.config.errorHandler` d'être invoqué pour cette erreur.

  **Mises en garde concernant la capture d'erreurs**

  * Dans les composants avec la fonction asynchrone `setup()` (avec le *top-level* `await`) Vue **essayera toujours** de rendre le template du composant, même si `setup()` a lancé une erreur. Cela causera probablement plus d'erreurs parce que pendant le rendu, le template du composant peut essayer d'accéder à des propriétés inexistantes du contexte `setup()` qui a échoué. Lorsque vous capturez des erreurs dans de tels composants, soyez prêt à gérer les erreurs provenant à la fois de l'échec de la fonction asynchrone `setup()` (elles arriveront toujours en premier) et de l'échec du processus de rendu.

  * &#x20;Remplacer le composant enfant erroné par le composant parent à l'intérieur de `<Suspense>` causera des erreurs d'hydratation dans SSR. Au lieu de cela, essayez de séparer la logique qui peut éventuellement être lancée depuis le `setup()` de l'enfant dans une fonction séparée et exécutez-la dans le `setup()` du composant parent, où vous pouvez en toute sécurité  capturer avec `try/catch` le processus d'exécution et faire le remplacement si nécessaire avant de rendre le composant enfant actuel.

## renderTracked  {#rendertracked}

Appelé lorsqu'une dépendance réactive a été traquée par l'effet de rendu du composant.

**Ce hook est réservé au mode développement et n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  interface ComponentOptions {
    renderTracked?(this: ComponentPublicInstance, e: DebuggerEvent): void
  }

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TrackOpTypes /* 'get' | 'has' | 'iterate' */
    key: any
  }
  ```

* **Voir aussi** [La réactivité en détails](/guide/extras/reactivity-in-depth)

## renderTriggered  {#rendertriggered}

Appelé lorsqu'une dépendance réactive déclenche la ré-exécution de l'effet de rendu du composant.

**Ce hook est réservé au mode développement et n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  interface ComponentOptions {
    renderTriggered?(this: ComponentPublicInstance, e: DebuggerEvent): void
  }

  type DebuggerEvent = {
    effect: ReactiveEffect
    target: object
    type: TriggerOpTypes /* 'set' | 'add' | 'delete' | 'clear' */
    key: any
    newValue?: any
    oldValue?: any
    oldTarget?: Map<any, any> | Set<any>
  }
  ```

* **Voir aussi** [La réactivité en détails](/guide/extras/reactivity-in-depth)

## activated {#activated}

Appelé après l'insertion de l'instance du composant dans le DOM en tant que partie d'un arbre mis en cache par [`<KeepAlive>`](/api/built-in-components#keepalive).

**Ce hook n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  interface ComponentOptions {
    activated?(this: ComponentPublicInstance): void
  }
  ```

* **Voir aussi** [Guide - Cycle de vie d'une instance mise en cache](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## deactivated {#deactivated}

Appelé après que l'instance du composant ait été retirée du DOM en tant que partie d'un arbre mis en cache par [`<KeepAlive>`](/api/built-in-components#keepalive).

**Ce hook n'est pas appelé pendant le rendu côté serveur.**

* **Type :**

  ```ts
  interface ComponentOptions {
    deactivated?(this: ComponentPublicInstance): void
  }
  ```

* **Voir aussi** [Guide - Cycle de vie d'une instance mise en cache](/guide/built-ins/keep-alive#lifecycle-of-cached-instance)

## serverPrefetch  {#serverprefetch}

Fonction asynchrone qui doit être résolue avant que l'instance du composant ne soit rendue sur le serveur.

* **Type :**

  ```ts
  interface ComponentOptions {
    serverPrefetch?(this: ComponentPublicInstance): Promise<any>
  }
  ```

* **Détails**

  Si le hook renvoie une promesse, le moteur de rendu du serveur attendra qu'elle soit résolue avant d'effectuer le rendu du composant.

  Ce hook n'est appelé que pendant le rendu côté serveur et peut être utilisé pour effectuer une récupération de données sur le serveur uniquement.

* **Exemple**

  ```js
  export default {
    data() {
      return {
        data: null
      }
    },
    async serverPrefetch() {
      // le composant est rendu dans le cadre de la requête initiale.
      // les données sont pré-récupérées sur le serveur car cela est plus rapide que via le client.
      this.data = await fetchOnServer(/* ... */)
    },
    async mounted() {
      if (!this.data) {
        // si les données ne sont pas définies au moment du montage, cela signifie que le composant
        // est rendu dynamiquement sur le client.
        // Effectue la récupération côté client.
        this.data = await fetchOnClient(/* ... */)
      }
    }
  }
  ```

* **Voir aussi** [Rendu côté serveur](/guide/scaling-up/ssr)

---

---
url: /api/options-misc.md
---
# Options : Divers {#options-misc}

## name {#name}

Déclare explicitement un nom d'affichage pour le composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    name?: string
  }
  ```

* **Détails**

  Le nom d'un composant est utilisé dans les cas suivants :

  * L'auto-référence récursive dans le template du composant
  * Affichage dans l'outil d'inspection de l'arbre des composants de Vue DevTools
  * Affichage dans les avertissements concernant les composants

  Lorsque vous utilisez des composants monofichiers, le composant déduit déjà son propre nom à partir du nom du fichier. Par exemple, un fichier nommé `MyComponent.vue` aura le nom d'affichage déduit "MyComponent".

  Par ailleurs, lorsqu'un composant est enregistré de manière globale via [`app.component`](/api/application#app-component), l'ID global est automatiquement défini comme son nom.

  L'option `name` vous permet de remplacer le nom déduit, ou de fournir explicitement un nom quand aucun nom ne peut être déduit (par exemple quand on n'utilise pas d'outil de build, ou lors de l'utilisation d'un composant en ligne divisé en plusieurs fichiers).

  Il y a un cas où `name` est nécessaire : lors de la recherche d'un composant pouvant être mis en cache dans [`<KeepAlive>`](/guide/built-ins/keep-alive) via ses props `include / exclude`.

  :::tip
  Depuis la version 3.2.34, un composant monofichier utilisant `<script setup>` déduira automatiquement son option `name` en fonction du nom du fichier, supprimant ainsi la nécessité de déclarer manuellement le nom, même lorsqu'il est utilisé avec `<KeepAlive>`.
  :::

## inheritAttrs {#inheritattrs}

Vérifie si le comportement par défaut de l'attribut du composant doit être activé ou non.

* **Type :**

  ```ts
  interface ComponentOptions {
    inheritAttrs?: boolean // default: true
  }
  ```

* **Détails**

  Par défaut, les liaisons d'attributs qui sont situées dans la portée du composant parent et qui ne sont pas reconnues comme des props seront "répercutées". Cela signifie que lorsque nous avons un composant racine unique, ces liaisons seront appliquées à l'élément racine du composant enfant comme des attributs HTML normaux. Lorsque vous créez un composant qui enveloppe un élément cible ou un autre composant, ce n'est pas toujours le comportement souhaité. En donnant à `inheritAttrs` la valeur `false`, ce comportement par défaut peut être désactivé. Les attributs sont disponibles via la propriété d'instance `$attrs` et peuvent être explicitement liés à un élément non racine en utilisant `v-bind`.

* **Exemple**

  ```vue
  <script>
  export default {
    inheritAttrs: false,
    props: ['label', 'value'],
    emits: ['input']
  }
  </script>

  <template>
    <label>
      {{ label }}
      <input
        v-bind="$attrs"
        v-bind:value="value"
        v-on:input="$emit('input', $event.target.value)"
      />
    </label>
  </template>
  ```

  Lorsque vous déclarez cette option dans un composant qui utilise `<script setup>`, vous pouvez utiliser la macro [`defineOptions`](/api/sfc-script-setup#defineoptions) :

  ```vue
  <script setup>
  defineProps(['label', 'value'])
  defineEmits(['input'])
  defineOptions({
    inheritAttrs: false
  })
  </script>

  <template>
    <label>
      {{ label }}
      <input
        v-bind="$attrs"
        v-bind:value="value"
        v-on:input="$emit('input', $event.target.value)"
      />
    </label>
  </template>
  ```

* **Voir aussi**

  * [Attributs implicitement déclarés](/guide/components/attrs)

  - [Utiliser `inheritAttrs` dans un `<script>` normal](/api/sfc-script-setup.html#usage-alongside-normal-script)

## components {#components}

Un objet qui enregistre les composants devant être accessibles par l'instance actuelle du composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    components?: { [key: string]: Component }
  }
  ```

* **Exemple**

  ```js
  import Foo from './Foo.vue'
  import Bar from './Bar.vue'

  export default {
    components: {
      // raccourci
      Foo,
      // enregistrement sous un nom différent
      RenamedBar: Bar
    }
  }
  ```

* **Voir aussi** [Enregistrement de composants](/guide/components/registration)

## directives {#directives}

Un objet qui enregistre les directives devant être accessibles par l'instance actuelle du composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    directives?: { [key: string]: Directive }
  }
  ```

* **Exemple**

  ```js
  export default {
    directives: {
      // permet l'utilisation de v-focus dans le template
      focus: {
        mounted(el) {
          el.focus()
        }
      }
    }
  }
  ```

  ```vue-html
  <input v-focus>
  ```

* **Voir aussi** [Directives personnalisées](/guide/reusability/custom-directives)

---

---
url: /api/options-state.md
---
# Options : État {#options-state}

## data {#data}

Une fonction qui retourne l'état réactif initial de l'instance du composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    data?(
      this: ComponentPublicInstance,
      vm: ComponentPublicInstance
    ): object
  }
  ```

* **Détails**

  La fonction doit retourner un objet JavaScript simple, qui sera rendu réactif par Vue. Après la création de l'instance, l'objet de données réactif est accessible via `this.$data`. L'instance du composant proxifie également toutes les propriétés de l'objet de données, ainsi `this.a` sera équivalent à `this.$data.a`.

  Toutes les propriétés de données de niveau supérieur doivent être incluses dans l'objet de données retourné. Il est possible d'ajouter de nouvelles propriétés à `this.$data`, mais ce n'est **pas** recommandé. Si la valeur souhaitée d'une propriété n'est pas encore disponible, une valeur vide telle que `undefined` ou `null` doit être incluse en tant que placeholder pour s'assurer que Vue sait que la propriété existe.

  Les propriétés commençant par `_` ou `$` ne seront **pas** proxifiées sur l'instance du composant car elles peuvent entrer en conflit avec les propriétés internes de Vue et les méthodes d'API. Vous devrez y accéder via `this.$data._property`.

  Il n'est **pas** recommandé de retourner des objets ayant leur propre comportement d'état comme les objets de l'API du navigateur et les propriétés prototypes. L'objet retourné doit idéalement être un objet simple représentant seulement l'état du composant.

* **Exemple**

  ```js
  export default {
    data() {
      return { a: 1 }
    },
    created() {
      console.log(this.a) // 1
      console.log(this.$data) // { a: 1 }
    }
  }
  ```

  Notez que si vous utilisez une fonction fléchée avec la propriété `data`, `this` ne représentera pas l'instance du composant, mais vous pouvez toujours y accéder via le premier argument de la fonction :

  ```js
  data: (vm) => ({ a: vm.myProp })
  ```

* **Voir aussi** [La réactivité en détails](/guide/extras/reactivity-in-depth)

## props {#props}

Déclare les props d'un composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    props?: ArrayPropsOptions | ObjectPropsOptions
  }

  type ArrayPropsOptions = string[]

  type ObjectPropsOptions = { [key: string]: Prop }

  type Prop<T = any> = PropOptions<T> | PropType<T> | null

  interface PropOptions<T> {
    type?: PropType<T>
    required?: boolean
    default?: T | ((rawProps: object) => T)
    validator?: (value: unknown, rawProps: object) => boolean
  }

  type PropType<T> = { new (): T } | { new (): T }[]
  ```

  > Les types sont simplifiés dans un souci de lisibilité.

* **Détails**

  Dans Vue, toutes les props d'un composant doivent être déclarées de manière explicite. Les props peuvent être déclarées de deux manières :

  * Forme simple utilisant un tableau de chaînes de caractères
  * Forme complète utilisant un objet où chaque clé d'une propriété représente le nom de la prop, et la valeur représente son type (une fonction constructeur) ou des options avancées.

  Avec la syntaxe basée sur les objets, chaque prop peut ensuite définir les options suivantes :

  * **`type`** : Peut être l'un des constructeurs natifs suivants : `String`, `Number`, `Boolean`, `Array`, `Object`, `Date`, `Function`, `Symbol`, toute fonction constructeur personnalisée ou un tableau de ces dernières. En mode développement, Vue vérifiera si la valeur d'une prop correspond au type déclaré, et enverra un avertissement si ce n'est pas le cas. Voir la [validation de prop](/guide/components/props#prop-validation) pour plus de détails.

    Notez également qu'une prop de type `Boolean` modifie le comportement de la conversion de sa valeur, tant en mode développement qu'en production. Voir la [conversion en booléen](/guide/components/props#boolean-casting) pour plus de détails.

  * **`default`** : Spécifie une valeur par défaut pour la prop quand elle n'est pas passée par le parent ou a une valeur valant `undefined`. Les valeurs par défaut des objets ou des tableaux doivent être retournées en utilisant une fonction *factory*. La fonction *factory* reçoit également l'objet props brut comme argument.

  * **`required`** : Définit si la prop est requise. Dans tout autre environnement que celui de production, un message d'avertissement sera affiché dans la console si cette valeur est vraie et que la prop n'est pas passée.

  * **`validator`** : Fonction de validation personnalisée qui prend la valeur de la prop et l'object props comme arguments. En mode développement, un message d'avertissement sera envoyé à la console si cette fonction renvoie une valeur fausse (c'est-à-dire si la validation échoue).

* **Exemple**

  Simple déclaration :

  ```js
  export default {
    props: ['size', 'myMessage']
  }
  ```

  Déclaration d'un objet avec des validations :

  ```js
  export default {
    props: {
      // vérification de type
      height: Number,
      // vérification de type plus d'autres validations
      age: {
        type: Number,
        default: 0,
        required: true,
        validator: (value) => {
          return value >= 0
        }
      }
    }
  }
  ```

* **Voir aussi**
  * [Guide - Props](/guide/components/props)
  * [Guide - Typer les props des composants](/guide/typescript/options-api#typing-component-props)&#x20;

## computed {#computed}

Déclare les propriétés calculées à exposer à l'instance du composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    computed?: {
      [key: string]: ComputedGetter<any> | WritableComputedOptions<any>
    }
  }

  type ComputedGetter<T> = (
    this: ComponentPublicInstance,
    vm: ComponentPublicInstance
  ) => T

  type ComputedSetter<T> = (
    this: ComponentPublicInstance,
    value: T
  ) => void

  type WritableComputedOptions<T> = {
    get: ComputedGetter<T>
    set: ComputedSetter<T>
  }
  ```

* **Détails**

  L'option accepte un objet où la clé est le nom de la propriété calculée, et la valeur est soit un accesseur calculé, soit un objet avec des méthodes `get` et `set` (pour les propriétés calculées modifiables).

  Tous les accesseurs et les mutateurs ont leur contexte `this` automatiquement lié à l'instance du composant.

  Notez que si vous utilisez une fonction fléchée avec une propriété calculée, `this` ne pointera pas vers l'instance du composant, mais vous pourrez toujours accéder à l'instance comme premier argument de la fonction :

  ```js
  export default {
    computed: {
      aDouble: (vm) => vm.a * 2
    }
  }
  ```

* **Exemple**

  ```js
  export default {
    data() {
      return { a: 1 }
    },
    computed: {
      // lecture seulement
      aDouble() {
        return this.a * 2
      },
      // modifiable
      aPlus: {
        get() {
          return this.a + 1
        },
        set(v) {
          this.a = v - 1
        }
      }
    },
    created() {
      console.log(this.aDouble) // => 2
      console.log(this.aPlus) // => 2

      this.aPlus = 3
      console.log(this.a) // => 2
      console.log(this.aDouble) // => 4
    }
  }
  ```

* **Voir aussi**
  * [Guide - Propriétés calculées](/guide/essentials/computed)
  * [Guide - Typer les propriétés calculées](/guide/typescript/options-api#typing-computed-properties)&#x20;

## methods {#methods}

Déclarer les méthodes à rendre accessibles dans l'instance du composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    methods?: {
      [key: string]: (this: ComponentPublicInstance, ...args: any[]) => any
    }
  }
  ```

* **Détails**

  Les méthodes déclarées peuvent être accédées directement sur l'instance du composant, ou utilisées dans des expressions de template. Toutes les méthodes ont leur contexte `this` automatiquement lié à l'instance du composant, même lorsqu'elles sont passées d'un composant à l'autre.

  Évitez d'utiliser les fonctions fléchées lorsque vous déclarez des méthodes, car elles n'auront pas accès à l'instance du composant via `this`.

* **Exemple**

  ```js
  export default {
    data() {
      return { a: 1 }
    },
    methods: {
      plus() {
        this.a++
      }
    },
    created() {
      this.plus()
      console.log(this.a) // => 2
    }
  }
  ```

* **Voir aussi** [Gestion d'événement](/guide/essentials/event-handling)

## watch {#watch}

Déclare les fonctions d'observation à invoquer lors d'un changement de données.

* **Type :**

  ```ts
  interface ComponentOptions {
    watch?: {
      [key: string]: WatchOptionItem | WatchOptionItem[]
    }
  }

  type WatchOptionItem = string | WatchCallback | ObjectWatchOptionItem

  type WatchCallback<T> = (
    value: T,
    oldValue: T,
    onCleanup: (cleanupFn: () => void) => void
  ) => void

  type ObjectWatchOptionItem = {
    handler: WatchCallback | string
    immediate?: boolean // default: false
    deep?: boolean // default: false
    flush?: 'pre' | 'post' | 'sync' // default: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
  }
  ```

  > Les types sont simplifiés dans un souci de lisibilité.

* **Détails**

  L'option `watch` attend un objet où les clés sont les propriétés de l'instance du composant réactif à surveiller (par exemple les propriétés déclarées via `data` ou `computed`) - et les valeurs sont les fonctions de rappel correspondantes. La fonction de rappel reçoit à la fois la nouvelle valeur et l'ancienne valeur de la source surveillée.

  La clé peut être une propriété racine, mais également un simple chemin délimité par des points, par exemple `a.b.c`. Notez que cette utilisation ne prend **pas** en charge les expressions complexes - seuls les chemins délimités par des points sont acceptés. Si vous devez surveiller des sources de données complexes, utilisez plutôt l'API impérative [`$watch()`](/api/component-instance#watch).

  La valeur peut également être une chaîne de caractères d'un nom de méthode (déclarée via `methods`), ou un objet qui contient des options supplémentaires. Lorsque vous utilisez la syntaxe objet, la fonction de rappel doit être déclarée via le champ `handler`. Les options supplémentaires incluent :

  * **`immediate`** : déclenche la fonction de rappel immédiatement à la création de l'observateur. L'ancienne valeur vaudra `undefined` lors du premier appel.
  * **`deep`** : force la traversée profonde de la source si c'est un objet ou un tableau, de sorte que la fonction de rappel se déclenche lors des mutations profondes. Voir [les observateurs profonds](/guide/essentials/watchers#deep-watchers).
  * **`flush`** : ajuste le timing du nettoyage de la fonction de rappel. Voir [Timing de nettoyage des fonctions de rappel](/guide/essentials/watchers#callback-flush-timing) et [`watchEffect()`](/api/reactivity-core#watcheffect).
  * **`onTrack / onTrigger`** : débogue les dépendances de l'observateur. Voir [Débogage des observateur](/guide/extras/reactivity-in-depth#watcher-debugging).

  Évitez d'utiliser les fonctions fléchées lorsque vous déclarez des fonctions de rappel d'un observateur car elles n'auront pas accès à l'instance du composant via `this`.

* **Exemple**

  ```js
  export default {
    data() {
      return {
        a: 1,
        b: 2,
        c: {
          d: 4
        },
        e: 5,
        f: 6
      }
    },
    watch: {
      // observation des propriétés de haut niveau
      a(val, oldVal) {
        console.log(`new: ${val}, old: ${oldVal}`)
      },
      // chaînes de caractères représentant le nom d'une méthode
      b: 'someMethod',
      // la fonction de rappel sera appelée chaque fois que l'une des propriétés de l'objet surveillé changera, quelle que soit la profondeur de l'imbrication
      c: {
        handler(val, oldVal) {
          console.log('c changed')
        },
        deep: true
      },
      // observation d'une seule propriété imbriquée :
      'c.d': function (val, oldVal) {
        // faire quelque chose
      },
      // la fonction de rappel sera appelée immédiatement après le début de l'observation
      e: {
        handler(val, oldVal) {
          console.log('e changed')
        },
        immediate: true
      },
      // vous pouvez passer un tableau de fonctions de rappel, elles seront appelées une par une
      f: [
        'handle1',
        function handle2(val, oldVal) {
          console.log('handle2 triggered')
        },
        {
          handler: function handle3(val, oldVal) {
            console.log('handle3 triggered')
          }
          /* ... */
        }
      ]
    },
    methods: {
      someMethod() {
        console.log('b changed')
      },
      handle1() {
        console.log('handle 1 triggered')
      }
    },
    created() {
      this.a = 3 // => nouvelle valeur : 3, ancienne valeur : 1
    }
  }
  ```

* **Voir aussi** [Observateurs](/guide/essentials/watchers)

## emits {#emits}

Déclare les événements personnalisés émis par le composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    emits?: ArrayEmitsOptions | ObjectEmitsOptions
  }

  type ArrayEmitsOptions = string[]

  type ObjectEmitsOptions = { [key: string]: EmitValidator | null }

  type EmitValidator = (...args: unknown[]) => boolean
  ```

* **Détails**

  Les événements émis peuvent être déclarés de deux manières :

  * Forme simple utilisant un tableau de chaînes de caractères
  * Forme complète utilisant un objet où chaque clé de propriété représente le nom de l'événement, et la valeur est soit `null` soit une fonction de validation.

  La fonction de validation recevra les arguments additionnels passés à l'appel `$emit` du composant. Par exemple, si `this.$emit('foo', 1)` est appelé, le validateur correspondant à `foo` recevra l'argument `1`. La fonction de validation doit retourner un booléen pour indiquer si les arguments de l'événement sont valides.

  Notez que l'option `emits` affecte les écouteurs d'événements considérés comme appartenant au composant, plutôt que des écouteurs d'événements natifs du DOM. Les écouteurs d'événements déclarés seront supprimés de l'objet `$attrs` du composant, et ne seront donc pas transmis à son élément racine. Voir [Attributs implicitement déclarés](/guide/components/attrs) pour plus de détails.

* **Exemple**

  Syntaxe avec un tableau :

  ```js
  export default {
    emits: ['check'],
    created() {
      this.$emit('check')
    }
  }
  ```

  Syntaxe objet :

  ```js
  export default {
    emits: {
      // sans validation
      click: null,

      // avec validation
      submit: (payload) => {
        if (payload.email && payload.password) {
          return true
        } else {
          console.warn(`Invalid submit event payload!`)
          return false
        }
      }
    }
  }
  ```

* **Voir aussi**
  * [Guide - Attributs implicitement déclarés](/guide/components/attrs)
  * [Guide - Typer les événements émis par un composant](/guide/typescript/options-api#typing-component-emits)&#x20;

## expose {#expose}

Déclare les propriétés publiques exposées lorsque l'instance du composant est accédée par un parent via des refs de template.

* **Type :**

  ```ts
  interface ComponentOptions {
    expose?: string[]
  }
  ```

* **Détails**

  Par défaut, une instance de composant expose toutes les propriétés de l'instance au parent lorsqu'on y accède via `$parent`, `$root`, ou les refs de template. Cela peut être indésirable, car un composant a très probablement un état interne ou des méthodes qui doivent rester privées pour éviter des conflits.

  L'option `expose` attend une liste de chaînes de caractères représentant des noms de propriétés. Lorsque `expose` est utilisée, seules les propriétés explicitement listées seront exposées sur l'instance publique du composant.

  `expose` n'affecte que les propriétés définies par l'utilisateur - elle ne filtre pas les propriétés natives de l'instance du composant.

* **Exemple**

  ```js
  export default {
    // seule `publicMethod` sera disponible sur l'instance publique.
    expose: ['publicMethod'],
    methods: {
      publicMethod() {
        // ...
      },
      privateMethod() {
        // ...
      }
    }
  }
  ```

---

---
url: /api/options-rendering.md
---
# Options : Rendu {#options-rendering}

## template {#template}

Un modèle de chaîne de caractères pour le composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    template?: string
  }
  ```

* **Détails**

  Un template fourni via l'option `template` sera compilé à la volée lors de l'exécution. Cette option n'est prise en charge que si vous utilisez une version de Vue qui inclut le compilateur de templates. Ce dernier n'est **PAS** inclus dans les builds de Vue qui ont le mot `runtime` dans leur nom, comme par exemple `vue.runtime.esm-bundler.js`. Consultez le [guide sur le fichier dist](https://github.com/vuejs/core/tree/main/packages/vue#which-dist-file-to-use) pour plus de détails sur les différents builds.

  Si la chaîne de caractères commence par `#`, elle sera utilisée comme `querySelector` et utilisera le `innerHTML` de l'élément sélectionné en guise de chaîne de caractères pour le template. Cela permet de créer le template source à l'aide d'éléments `<template>` natifs.

  Si l'option `render` est également présente dans le même composant, `template` sera ignoré.

  Si le composant racine de votre application n'a pas d'option `template` ou `render` de spécifiée, Vue essaiera à la place d'utiliser le `innerHTML` de l'élément monté comme template.

  :::warning Remarque sur la sécurité
  N'utilisez que des sources de templates auxquelles vous pouvez faire confiance. N'utilisez pas de contenu fourni par l'utilisateur en guise de template. Voir le [guide sur la sécurité](/guide/best-practices/security#rule-no-1-never-use-non-trusted-templates) pour plus de détails.
  :::

## render {#render}

Une fonction qui retourne automatiquement l'arbre du DOM virtuel du composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    render?(this: ComponentPublicInstance) => VNodeChild
  }

  type VNodeChild = VNodeChildAtom | VNodeArrayChildren

  type VNodeChildAtom =
    | VNode
    | string
    | number
    | boolean
    | null
    | undefined
    | void

  type VNodeArrayChildren = (VNodeArrayChildren | VNodeChildAtom)[]
  ```

* **Détails**

  `render` est une alternative aux templates qui vous permet de tirer parti de toute la puissance de JavaScript pour déclarer le rendu du composant.

  Les templates pré-compilés, par exemple ceux des composants monofichiers, sont compilés dans l'option `render` au moment du build. Si les deux options `render` et `template` sont présentes dans un composant, `render` aura la priorité.

* **Voir aussi**
  * [Mécanismes de rendu](/guide/extras/rendering-mechanism)
  * [Fonctions de rendu](/guide/extras/render-function)

## compilerOptions {#compileroptions}

Configure les options du compilateur d'exécution pour le template du composant.

* **Type :**

  ```ts
  interface ComponentOptions {
    compilerOptions?: {
      isCustomElement?: (tag: string) => boolean
      whitespace?: 'condense' | 'preserve' // par défaut: 'condense'
      delimiters?: [string, string] // par défaut : ['{{', '}}']
      comments?: boolean // par défaut : false
    }
  }
  ```

* **Détails**

  Cette option de configuration n'est respectée que lors de l'utilisation du build complet (c'est-à-dire le build `vue.js` autonome qui peut compiler des templates dans le navigateur). Elle prend en charge les mêmes options que [app.config.compilerOptions](/api/application#app-config-compileroptions) au niveau de l'application, et a la plus haute priorité pour le composant actuel.

* **Voir aussi** [app.config.compilerOptions](/api/application#app-config-compileroptions)

## slots {#slots}

* Prise en charge à partir de la version 3.3+

Une option pour aider à l'inférence de type lors de l'utilisation de slots dans les fonctions de rendu.

* **Détails**

  La valeur de cette option lors de l'exécution n'est pas utilisée. Les types réels doivent être déclarés via un casting de type grâce à l'utilitaire de type `SlotsType` :

  ```ts
  import { SlotsType } from 'vue'

  defineComponent({
    slots: Object as SlotsType<{
      default: { foo: string; bar: number }
      item: { data: number }
    }>,
    setup(props, { slots }) {
      expectType<
        undefined | ((scope: { foo: string; bar: number }) => any)
      >(slots.default)
      expectType<undefined | ((scope: { data: number }) => any)>(
        slots.item
      )
    }
  })
  ```

---

---
url: /guide/scaling-up/tooling.md
---
# Outils {#tooling}

## Essayer en ligne {#try-it-online}

Vous n'avez pas besoin d'installer quoi que ce soit sur votre machine pour essayer les composants monofichiers de Vue - il existe des terrains de jeu en ligne qui vous permettent de le faire directement dans le navigateur :

* [Terrain de jeu des composants monofichiers de Vue](https://play.vuejs.org)
  * Toujours déployé à partir du dernier commit
  * Conçu pour inspecter les résultats de la compilation d'un composant
* [Vue + Vite sur StackBlitz](https://vite.new/vue)
  * Environnement semblable à un environnement de développement classique exécutant le serveur de développement Vite dans le navigateur.
  * Le plus proche de la configuration locale

Il est également recommandé d'utiliser ces terrains de jeu en ligne pour fournir des reproductions lors du signalement de bugs.

## Squelette d'un projet {#project-scaffolding}

### Vite {#vite}

[Vite](https://vite.dev/) est un outil de construction léger et rapide avec un support de première classe pour les composants monofichiers de Vue. Il a été créé par Evan You, qui est également l'auteur de Vue !

Pour commencer avec Vite + Vue, exécutez simplement :

::: code-group

```sh [npm]
$ npm create vue@latest
```

```sh [pnpm]
$ pnpm create vue@latest
```

```sh [yarn]
# Avec Yarn Moderne (v2+)
$ yarn create vue@latest

# Avec Yarn ^v4.11
$ yarn dlx create-vue@latest
```

```sh [bun]
$ bun create vue@latest
```

:::

Cette commande installera et exécutera [create-vue](https://github.com/vuejs/create-vue), l'outil officiel d'élaboration d'un projet Vue.

* Pour en savoir plus sur Vite, consultez la [doc Vite](https://vite.dev).
* Pour configurer le comportement spécifique de Vue dans un projet Vite, par exemple en passant des options au compilateur Vue, consultez la documentation de [@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#readme).

Les deux terrains de jeu en ligne mentionnés ci-dessus prennent également en charge le téléchargement de fichiers en tant que projet Vite.

### Vue CLI {#vue-cli}

[Vue CLI](https://cli.vuejs.org/) est la chaîne d'outils officielle basée sur webpack pour Vue. Elle est maintenant en mode maintenance et nous recommandons de commencer les nouveaux projets avec Vite, à moins que vous ne dépendiez de fonctionnalités spécifiques à webpack. Vite offrira une expérience de développement supérieure dans la plupart des cas.

Pour des informations sur la migration de Vue CLI vers Vite :

* [Guide de migration de Vue CLI -> Vite sur VueSchool.io](https://vueschool.io/articles/vuejs-tutorials/how-to-migrate-from-vue-cli-to-vite/)
* [Outils / Plugins utiles pour la migration automatique](https://github.com/vitejs/awesome-vite#vue-cli)

### Note sur la compilation des templates dans le navigateur {#note-on-in-browser-template-compilation}

Lorsque Vue est utilisé sans outil de build, les templates de composants sont écrits soit directement dans le HTML de la page, soit directement sous forme de chaînes de caractères JavaScript. Dans ce cas, Vue doit envoyer le compilateur de templates au navigateur afin d'effectuer la compilation des templates à la volée. D'un autre côté, le compilateur ne serait pas nécessaire si nous pré-compilions les templates avec une étape de build. Pour réduire la taille du paquet client, Vue fournit [différents "builds"](https://unpkg.com/browse/vue@3/dist/) optimisées pour différents cas d'utilisation.

* Les fichiers de build qui commencent par `vue.runtime.*` sont des **builds spécifiques à l'exécution** : ils n'incluent pas le compilateur. Lorsque vous utilisez ces builds, tous les templates doivent être pré-compilés via une étape de build.

* Les fichiers de build qui n'incluent pas `.runtime` sont des **builds complets** : ils incluent le compilateur et supportent la compilation des templates directement dans le navigateur. Cependant, ils augmentent la taille de ~14kb.

Nos configurations d'outils par défaut utilisent le build spécifique à l'exécution puisque tous les templates dans les composants monofichiers sont pré-compilés. Si, pour une raison quelconque, vous avez besoin de compiler les templates dans le navigateur même avec une étape de build, vous pouvez le faire en configurant l'outil de build afin de créer un alias entre `vue` et `vue/dist/vue.esm-bundler.js` à la place.

Si vous recherchez une alternative plus légère pour une utilisation sans étape de build, consultez [petite-vue](https://github.com/vuejs/petite-vue).

## Support des environnements de développement {#ide-support}

* La configuration IDE recommandée est [VS Code](https://code.visualstudio.com/) + l'extension [Vue Language Features (Volar)](https://github.com/johnsoncodehk/volar) (précédemment Volar). L'extension fournit la coloration syntaxique, la prise en charge de TypeScript et l'intellisense pour les expressions des templates et les props des composants.

  :::tip
  Vue - Official remplace [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur), notre précédente extension officielle VS Code pour Vue 2. Si vous avez Vetur actuellement installé, assurez-vous de le désactiver dans les projets Vue 3.
  :::

* [WebStorm](https://www.jetbrains.com/webstorm/) offre également un excellent support intégré pour les composants monofichiers de Vue.

* D'autres IDE qui prennent en charge le [Language Service Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) peuvent également exploiter les fonctionnalités de base de Volar via le LSP :

  * Support de Sublime Text via [LSP-Volar](https://github.com/sublimelsp/LSP-volar).

  * Support de vim / Neovim via [coc-volar](https://github.com/yaegassy/coc-volar).

  * Support emacs via [lsp-mode](https://emacs-lsp.github.io/lsp-mode/page/lsp-volar/)

## Outils de développement du navigateur {#browser-devtools}

L'extension du navigateur Vue devtools vous permet d'explorer l'arborescence des composants d'une application Vue, d'inspecter l'état des composants individuels, de suivre les événements de gestion de l'état et d'analyser les performances.

![devtools screenshot](./images/devtools.png)

* [Documentation](https://devtools.vuejs.org/)
* [Extension Chrome](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
* [Addon Firefox](https://addons.mozilla.org/fr/firefox/addon/vue-js-devtools/)
* [Plugin Vite](https://devtools.vuejs.org/guide/vite-plugin)
* [Application autonome Electron](https://devtools.vuejs.org/guide/installation.html#standalone)

## TypeScript {#typescript}

Article principal : [Utiliser Vue avec TypeScript](/guide/typescript/overview).

* [Extension Vue - Official](https://github.com/vuejs/language-tools) fournit une vérification de type pour les composants monofichiers utilisant des blocs `<script lang="ts">`, y compris les expressions de templates et la validation de props entre composants.

* Utilisez [`vue-tsc`](https://github.com/vuejs/language-tools/tree/master/packages/tsc) pour effectuer la même vérification de type depuis la ligne de commande, ou pour générer des fichiers `d.ts` pour les composants monofichiers.

## Testing {#testing}

Article principal : [Guide de test](/guide/scaling-up/testing).

* [Cypress](https://www.cypress.io/) est recommandé pour les tests E2E. Il peut également être utilisé pour les tests de composants pour les composants monofichiers Vue via le [Cypress Component Test Runner](https://docs.cypress.io/guides/component-testing/introduction).

* [Vitest](https://vitest.dev/) est un exécuteur de tests créé par les membres de l'équipe Vue / Vite qui se concentre sur la vitesse. Il est spécifiquement conçu pour les applications basées sur Vite afin de fournir la même boucle de feedback instantané pour les tests unitaires / de composants.

* [Jest](https://jestjs.io/) peut fonctionner avec Vite via [vite-jest](https://github.com/sodatea/vite-jest). Cependant, ceci n'est recommandé que si vous avez des suites de test existantes basées sur Jest que vous devez migrer vers une configuration basée sur Vite, car Vitest fournit des fonctionnalités similaires avec une intégration beaucoup plus efficace.

## Linting {#linting}

L'équipe Vue maintient [eslint-plugin-vue](https://github.com/vuejs/eslint-plugin-vue), un plugin [ESLint](https://eslint.org/) qui supporte les règles de linting spécifiques aux composants monofichiers.

Les utilisateurs utilisant Vue CLI avant peuvent être habitués à avoir des linters configurés via des loaders webpack. Cependant, lorsque vous utilisez une configuration de build basée sur Vue, notre recommandation générale est la suivante :

1. `npm install -D eslint eslint-plugin-vue`, puis suivez le [guide de configuration](https://eslint.vuejs.org/user-guide/#usage) d'`eslint-plugin-vue`.

2. Configurez les extensions ESLint de votre environnement de développement, par exemple [ESLint pour VS Code](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint), afin d'obtenir un feedback du linter directement dans votre éditeur pendant le développement. Cela évite également les coûts inutiles de linting lors du démarrage du serveur de développement.

3. Exécutez ESLint dans le cadre de la commande de build de production, afin d'obtenir un feedback complet sur le linter avant de l'envoyer en production.

4. (Facultatif) Configurez des outils tels que [lint-staged](https://github.com/okonet/lint-staged) pour vérifier uniquement les fichiers modifiés d'un commit git.

## Mise en page {#formatting}

* L'extension VS Code [Vue - Official](https://github.com/vuejs/language-tools) permet de formater les composants monofichiers de Vue.

* Autrement, [Prettier](https://prettier.io/) offre une prise en charge intégrée du formatage des composants monofichiers de Vue.

## Intégrations de blocs personnalisés dans les composants monofichiers {#sfc-custom-block-integrations}

Les blocs personnalisés sont compilés en importations en provenance du même fichier Vue avec des requêtes différentes. C'est à l'outil de build sous-jacent de gérer ces demandes d'importation.

* Si vous utilisez Vite, un plugin Vite personnalisé doit être utilisé pour transformer les blocs personnalisés assortis en JavaScript exécutable. [Exemple](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#example-for-transforming-custom-blocks)

* Si vous utilisez Vue CLI ou entièrement webpack, un loader webpack doit être configuré pour transformer les blocs correspondants. [Exemple](https://vue-loader.vuejs.org/guide/custom-blocks.html)

## Packages de bas niveau {#lower-level-packages}

### `@vue/compiler-sfc` {#vue-compiler-sfc}

* [Documentation](https://github.com/vuejs/core/tree/main/packages/compiler-sfc)

Ce paquet fait partie du noyau de Vue monorepo et est toujours publié avec la même version que le paquet principal `vue`. Il est inclus en tant que dépendance du paquet principal `vue` et disponible sous `vue/compiler-sfc` afin que vous n'ayez pas besoin de l'installer individuellement.

Le paquet lui-même fournit des utilitaires de bas niveau pour traiter les composants monofichiers de Vue et est seulement destiné aux auteurs d'outils qui ont besoin de supporter les composants monofichiers de Vue dans des outils personnalisés.

:::tip
Préférez toujours utiliser ce paquet via l'importation profonde `vue/compiler-sfc` car cela garantit que sa version est synchronisée avec le moment d'exécution de Vue.
:::

### `@vitejs/plugin-vue` {#vitejs-plugin-vue}

* [Documentation](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue)

Plugin officiel qui permet le support des composants monofichiers de Vue dans Vite.

### `vue-loader` {#vue-loader}

* [Documentation](https://vue-loader.vuejs.org/)

Le loader officiel qui assure le support des composants monofichiers de Vue dans webpack. Si vous utilisez Vue CLI, consultez également la [documentation sur la modification des options `vue-loader` dans Vue CLI](https://cli.vuejs.org/guide/webpack.html#modifying-options-of-a-loader).

## Autres terrains de jeu en ligne {#other-online-playgrounds}

* [Terrain de jeu VueUse](https://play.vueuse.org)
* [Vue + Vite sur Repl.it](https://replit.com/@templates/VueJS-with-Vite)
* [Vue sur CodeSandbox](https://codesandbox.io/p/devbox/github/codesandbox/sandbox-templates/tree/main/vue-vite)
* [Vue sur Codepen](https://codepen.io/pen/editor/vue)
* [Vue sur WebComponents.dev](https://webcomponents.dev/create/cevue)

---

---
url: /guide/best-practices/performance.md
---

# Performance {#performance}

## Vue d'ensemble {#overview}

Vue est conçu pour être performant dans la plupart des cas d'utilisation courants, sans que vous soyez contraints de procéder à des optimisations manuelles. Cependant, il y a toujours des scénarios complexes où un réglage plus fin est requis. Dans cette section, nous allons voir à quoi vous devez faire attention concernant les performances dans une application Vue.

Tout d'abord, discutons des deux principaux aspects de la performance web :

* **Performance de chargement des pages** : rapidité avec laquelle l'application affiche le contenu et devient interactive lors de la première visite. Elle est généralement mesurée à l'aide de mesures web vitales comme [Largest Contentful Paint (LCP)](https://web.dev/lcp/) et [Interaction to Next Paint](https://web.dev/articles/inp).

* **Performance de mise à jour** : vitesse à laquelle l'application se met à jour en réponse aux entrées de l'utilisateur. Par exemple, la vitesse à laquelle une liste se met à jour lorsque l'utilisateur tape dans un champ de recherche, ou la vitesse à laquelle la page change lorsque l'utilisateur clique sur un lien de navigation dans une application monopage (SPA).

L'idéal serait de maximiser les deux, mais les différentes architectures frontend ont tendance à rendre compliqué d'atteindre les performances souhaitées. En outre, le type d'application que vous construisez influence grandement ce à quoi vous devez donner la priorité en termes de performances. Par conséquent, la première étape pour garantir des performances optimales consiste à choisir la bonne architecture pour votre application :

* Consulter les [Manières d'utiliser Vue](/guide/extras/ways-of-using-vue) pour voir comment vous pouvez tirer parti de Vue de différentes manières.

* Jason Miller examine les types d'applications web et leur mise en œuvre idéale dans [les holotypes des applications](https://jasonformat.com/application-holotypes/).

## Options d'analyse {#profiling-options}

Pour améliorer les performances, nous devons d'abord savoir comment les mesurer. Il existe un certain nombre d'outils performants qui peuvent vous aider :

Pour l'analyse des performances de chargement des déploiements de production :

* [PageSpeed Insights](https://pagespeed.web.dev/)
* [WebPageTest](https://www.webpagetest.org/)

Pour l'analyse des performances durant le développement local :

* [Panneau de performances des Chrome DevTools](https://developer.chrome.com/docs/devtools/evaluate-performance/)
  * [`app.config.performance`](/api/application#app-config-performance) active les marqueurs de performance spécifiques à Vue dans la timeline des performances de Chrome DevTools.
* [L'extension Vue DevTools](/guide/scaling-up/tooling#browser-devtools) fournit également une fonctionnalité d'analyse des performances.

## Optimisation du chargement des pages {#page-load-optimizations}

Il existe de nombreux aspects indépendants du framework pour optimiser les performances de chargement des pages - consultez [le guide web.dev](https://web.dev/fast/) pour un tour d'horizon complet. Ici, nous nous concentrerons principalement sur les techniques spécifiques à Vue.

### Choisir la bonne architecture {#choosing-the-right-architecture}

Si votre application est sensible aux performances de chargement des pages, évitez de la rendre en tant que SPA entièrement côté client. Vous voulez que votre serveur envoie directement le HTML contenant le contenu que les utilisateurs veulent voir. Le rendu côté purement client souffre d'un temps d'accès au contenu plus lent. Ceci peut être atténué avec [le rendu côté serveur (SSR)](/guide/extras/ways-of-using-vue#fullstack-ssr) ou [la génération de site statique (SSG)](/guide/extras/ways-of-using-vue#jamstack-ssg). Consultez le [Guide SSR](/guide/scaling-up/ssr) pour en savoir plus sur l'exécution SSR avec Vue. Si votre application n'a pas besoin d'une grande interactivité, vous pouvez également utiliser un serveur backend traditionnel pour rendre le HTML et le rendre interactif avec Vue côté client.

Si votre application doit être une SPA, mais qu'elle comporte des pages marketing (accueil, à propos, blog), envoyez-les séparément ! Vos pages marketing devraient idéalement être déployées en HTML statique avec un minimum de JS, en utilisant la SSG.

### Taille des paquets et *Tree-shaking* {#bundle-size-and-tree-shaking}

L'un des moyens les plus efficaces d'améliorer les performances de chargement des pages consiste à envoyer des paquets JavaScript plus petits. Voici quelques moyens de réduire la taille des paquets lorsque vous utilisez Vue :

* Utilisez un outil de build si possible.

  * De nombreuses API de Vue peuvent être ["retirées de l'arbre"](https://developer.mozilla.org/fr/docs/Glossary/Tree_shaking) si elles sont groupées via un outil de construction moderne. Par exemple, si vous n'utilisez pas le composant natif `<Transition>`, il ne sera pas inclus dans le paquet de production final. Le *tree-shaking* peut également supprimer d'autres modules inutilisés dans votre code source.

  * Lors de l'utilisation d'un outil de build, les templates sont pré-compilés afin que nous n'ayons pas besoin d'envoyer le compilateur Vue au navigateur. Cela permet d'économiser **14kb** de JavaScript au format min + gzipped et d'éviter le coût de la compilation au moment de l'exécution.

* Faites attention à la taille lorsque vous incorporez de nouvelles dépendances ! Dans les applications du monde réel, les paquets trop volumineux sont le plus souvent le résultat de l'introduction de lourdes dépendances sans s'en rendre compte.

  * Si vous utilisez un outil de build, préférez les dépendances qui offrent des formats de modules ES et qui sont compatibles au *tree-shaking.* Par exemple, préférez `lodash-es` à `lodash`.

  * Vérifiez la taille d'une dépendance et évaluez si elle vaut le coup par rapport à la fonctionnalité qu'elle apporte. Notez que si la dépendance peut être supprimée de l'arbre, l'augmentation réelle de la taille dépendra des API que vous importerez réellement. Des outils comme [bundlejs.com](https://bundlejs.com/) peuvent être utilisés pour des vérifications rapides, mais la mesure avec votre configuration de build réelle sera toujours la plus précise.

* Si vous utilisez Vue principalement pour une intégration progressive et préférez éviter un outil de build, envisagez plutôt d'utiliser [petite-vue](https://github.com/vuejs/petite-vue) (seulement **6kb**).

### Séparation du code {#code-splitting}

Le fractionnement du code consiste pour un outil de build à diviser le paquet d'applications en plusieurs petits morceaux, qui peuvent ensuite être chargés à la demande ou en parallèle. Avec un fractionnement de code approprié, les fonctionnalités requises au chargement de la page peuvent être téléchargées immédiatement, les morceaux supplémentaires n'étant chargés à la volée qu'en cas de besoin, ce qui améliore les performances.

Les bundlers comme Rollup (sur lequel Vite est basé) ou webpack peuvent créer automatiquement des morceaux de code fractionnés en détectant la syntaxe d'importation dynamique ESM :

```js
// lazy.js et ses dépendances seront divisées en un morceau à part
// et chargés que lorsque `loadLazy()` sera appelée.
function loadLazy() {
  return import('./lazy.js')
}
```

Le chargement à la volée est optimal pour les fonctionnalités qui ne sont pas immédiatement nécessaires après le chargement initial de la page. Dans les applications Vue, il peut être utilisé en combinaison avec la fonctionnalité [composants asynchrones](/guide/components/async) de Vue pour créer des morceaux fractionnés pour les arbres de composants :

```js
import { defineAsyncComponent } from 'vue'

// un morceau séparé est créé pour Foo.vue et ses dépendances.
// il n'est récupéré à la demande que lorsque le composant asynchrone est
// rendu sur la page.
const Foo = defineAsyncComponent(() => import('./Foo.vue'))
```

Pour les applications utilisant Vue Router, il est fortement recommandé d'utiliser le chargement à la volée pour les composants de route. Vue Router a un support explicite pour le chargement à la volée, séparé de `defineAsyncComponent`. Voir [le chargement à la volée des routes](https://router.vuejs.org/guide/advanced/lazy-loading.html) pour plus de détails.

## Optimisations des mises à jour {#update-optimizations}

### Stabilité des props {#props-stability}

Dans Vue, un composant enfant ne se met à jour que lorsqu'au moins une de ses props reçues a changé. Prenons l'exemple suivant :

```vue-html
<ListItem
  v-for="item in list"
  :id="item.id"
  :active-id="activeId" />
```

Dans le composant `<ListItem>`, les props `id` et `activeId` sont utilisées pour déterminer s'il s'agit de l'élément actif. Bien que cela fonctionne, le problème est que chaque fois que `activeId` change, **l'entièreté** des `<ListItem>` inclus dans la liste doit être mis à jour !

Dans l'idéal, seuls les éléments dont le statut d'activation a changé devraient être mis à jour. Nous pouvons y parvenir en déplaçant le calcul du statut d'activation dans le parent, et en faisant en sorte que `<ListItem>` accepte directement une prop `active` à la place :

```vue-html
<ListItem
  v-for="item in list"
  :id="item.id"
  :active="item.id === activeId" />
```

Désormais, pour la plupart des composants, la prop `active` restera la même lorsque `activeId` change, donc ils n'ont plus besoin de se mettre à jour. En général, l'idée est de garder les props passées aux composants enfants aussi stables que possible.

### `v-once` {#v-once}

`v-once` est une directive intégrée qui peut être utilisée pour rendre un contenu qui repose sur des données d'exécution mais qui n'a jamais besoin d'être mis à jour. Toute la sous-arborescence sur laquelle elle est utilisée sera ignorée pour toutes les mises à jour à venir. Consultez la [référence de son API](/api/built-in-directives#v-once) pour plus de détails.

### `v-memo` {#v-memo}

`v-memo` est une directive intégrée qui peut être utilisée pour éviter conditionnellement la mise à jour de grands sous-arbres ou de listes `v-for`. Consultez la [référence de son API](/api/built-in-directives#v-memo) pour plus de détails.

### Stabilité des Computed {#computed-stability}

À partir de 3.4, une propriété calculée ne déclenchera des effets que lorsque la valeur calculée aura changé par rapport à sa valeur précédente. Par exemple, la propriété calculée `isEven` ne va déclencher des effets que si la valeur retournée a changé de `true` à `false`, ou vice-versa :

```js
const count = ref(0)
const isEven = computed(() => count.value % 2 === 0)

watchEffect(() => console.log(isEven.value)) // true

// ne vas pas déclencher de nouveaux logs car la valeur calculée reste à `true`
count.value = 2
count.value = 4
```

Cela réduit le déclenchement inutile d'effet, mais ne fonctionne pas si la la propriété calculée retourne un nouvel object à chaque calcul :

```js
const computedObj = computed(() => {
  return {
    isEven: count.value % 2 === 0
  }
})
```

Du fait qu'un objet est créé à chaque fois, la nouvelle valeur sera techniquement toujours différente comparée à son ancienne valeur. Même si la propriété `isEven` reste la même, Vue ne sera pas capable de savoir sans une comparaison profonde entre son ancienne et sa nouvelle valeur. Ce genre de comparaison peut être très coûteuse and ne vaudrait pas toujours le coup.

À la place, nous pouvons optimiser cela en comparant manuellement la nouvelle valeur avec l'ancienne, et retourner l'ancienne valeur si l'on détecte aucun changement.

```js
const computedObj = computed((oldValue) => {
  const newValue = {
    isEven: count.value % 2 === 0
  }
  if (oldValue && oldValue.isEven === newValue.isEven) {
    return oldValue
  }
  return newValue
})
```

[Essayer en ligne](https://play.vuejs.org/#eNqVVMtu2zAQ/JUFgSZK4UpuczMkow/40AJ9IC3aQ9mDIlG2EokUyKVt1PC/d0lKtoEminMQQC1nZ4c7S+7Yu66L11awGUtNoesOwQi03ZzLuu2URtiBFtUECtV2FkU5gU2OxWpRVaJA2EOlVQuXxHDJJZeFkgYJayVC5hKj6dUxLnzSjZXmV40rZfFrh3Vb/82xVrLH//5DCQNNKPkweNiNVFP+zBsrIJvDjksgGrRahjVAbRZrIWdBVLz2yBfwBrIsg6mD7LncPyryfIVnywupUmz68HOEEqqCI+XFBQzrOKR79MDdx66GCn1jhpQDZx8f0oZ+nBgdRVcH/aMuBt1xZ80qGvGvh/X6nlXwnGpPl6qsLLxTtitzFFTNl0oSN/79AKOCHHQuS5pw4XorbXsr9ImHZN7nHFdx1SilI78MeOJ7Ca+nbvgd+GgomQOv6CNjSQqXaRJuHd03+kHRdg3JoT+A3a7XsfcmpbcWkQS/LZq6uM84C8o5m4fFuOg0CemeOXXX2w2E6ylsgj2gTgeYio/f1l5UEqj+Z3yC7lGuNDlpApswNNTrql7Gd0ZJeqW8TZw5t+tGaMdDXnA2G4acs7xp1OaTj6G2YjLEi5Uo7h+I35mti3H2TQsj9Jp6etjDXC8Fhu3F9y9iS+vDZqtK2xB6ZPNGGNVYpzHA3ltZkuwTnFf70b+1tVz+MIstCmmGQzmh/p56PGf00H4YOfpR7nV8PTxubP8P2GAP9Q==)

Notez que vous devez toujours effectuer le calcul complet avant la comparaison et retourner l'ancienne valeur, ainsi les mêmes dépendances pourront être réutiliser à chaque exécution.

## Optimisations générales {#general-optimizations}

> Les conseils suivants concernent les performances de chargement et de mise à jour des pages.

### Virtualiser des grandes listes {#virtualize-large-lists}

L'un des problèmes de performance les plus courants dans toutes les applications frontend est le rendu de grandes listes. Quelle que soit la performance d'un framework, le rendu d'une liste contenant des milliers d'éléments **sera** lent en raison du nombre de nœuds du DOM que le navigateur doit gérer.

Cependant, nous ne devons pas nécessairement rendre tous ces nœuds directement. Dans la plupart des cas, l'écran de l'utilisateur ne peut afficher qu'un petit sous-ensemble de notre grande liste. Nous pouvons améliorer considérablement les performances grâce à la **virtualisation de liste**, une technique qui consiste à ne rendre que les éléments d'une grande liste qui se trouvent actuellement dans la fenêtre d'affichage ou à proximité de celle-ci.

La mise en œuvre de la virtualisation des listes n'est pas facile, heureusement il existe des bibliothèques communautaires que vous pouvez utiliser directement :

* [vue-virtual-scroller](https://github.com/Akryum/vue-virtual-scroller)
* [vue-virtual-scroll-grid](https://github.com/rocwang/vue-virtual-scroll-grid)
* [vueuc/VVirtualList](https://github.com/07akioni/vueuc)

### Réduire la surcharge de réactivité pour les grandes structures immuables {#reduce-reactivity-overhead-for-large-immutable-structures}

Le système de réactivité de Vue est profond par défaut. Bien que cela rende la gestion de l'état intuitive, cela crée un certain niveau de surcharge lorsque la taille des données est importante, car chaque accès à une propriété déclenche un mécanisme des proxys qui effectuent un suivi des dépendances. Ce problème est généralement perceptible lorsque l'on traite de grands tableaux d'objets profondément imbriqués, où un seul rendu doit accéder à plus de 100 000 propriétés, et ne devrait donc affecter que des cas d'utilisation très spécifiques.

Vue fournit une échappatoire pour contourner la réactivité profonde en utilisant [`shallowRef()`](/api/reactivity-advanced#shallowref) et [`shallowReactive()`](/api/reactivity-advanced#shallowreactive). Les API partiellement réactives créent un état qui n'est réactif qu'au niveau de la racine, et exposent tous les objets imbriqués sans les modifier. L'accès aux propriétés imbriquées reste ainsi rapide, mais la contrepartie est que nous devons désormais traiter tous les objets imbriqués comme des objets immuables et que les mises à jour ne peuvent être déclenchées qu'en remplaçant l'état racine :

```js
const shallowArray = shallowRef([
  /* grande liste d'objets imbriqués */
])

// cela ne déclenchera pas de mise à jour...
shallowArray.value.push(newObject)
// mais cela si :
shallowArray.value = [...shallowArray.value, newObject]

// cela ne déclenchera pas de mise à jour...
shallowArray.value[0].foo = 1
// mais cela si :
shallowArray.value = [
  {
    ...shallowArray.value[0],
    foo: 1
  },
  ...shallowArray.value.slice(1)
]
```

### Éviter les abstractions de composants inutiles {#avoid-unnecessary-component-abstractions}

Parfois, nous pouvons créer des [composants sans rendu](/guide/components/slots#renderless-components) ou des composants d'ordre supérieur (c'est-à-dire des composants qui rendent d'autres composants avec des props supplémentaires) pour une meilleure abstraction ou organisation du code. Bien qu'il n'y ait rien de mal à cela, gardez à l'esprit que les instances de composants sont beaucoup plus gourmandes d'un point de vue des performances que les simples nœuds du DOM, et que la création d'un trop grand nombre d'entre eux en raison des modèles d'abstraction entraînera des performances réduites.

Notez que la réduction de quelques instances seulement n'aura pas d'effet notable, donc ne vous inquiétez pas si le composant n'est rendu que quelques fois dans l'application. Le meilleur scénario pour envisager cette optimisation concerne à nouveau les grandes listes. Imaginez une liste de 100 éléments où chaque composant d'élément contient de nombreux composants enfants. La suppression d'une abstraction de composant inutile pourrait entraîner une réduction de centaines d'instances de composants.

---

---
url: /guide/reusability/plugins.md
---
# Plugins {#plugins}

## Introduction {#introduction}

Les plugins sont des codes autonomes qui ajoutent généralement des fonctionnalités au niveau de l'application à Vue. Voici comment installer un plugin :

```js
import { createApp } from 'vue'

const app = createApp({})

app.use(myPlugin, {
  /* options facultatives */
})
```

Un plugin est défini comme étant soit un objet qui expose la méthode `install()`, ou simplement comme une fonction qui agit comme la fonction d'installation elle-même. La fonction d'installation reçoit l'[instance de l'application](/api/application) ainsi que les options additionnelles passées à `app.use()`, s'il y en a :

```js
const myPlugin = {
  install(app, options) {
    // configure l'application
  }
}
```

Il n'y a pas de champ d'application strictement défini pour un plugin, mais les scénarios courants où les plugins sont utiles incluent :

1. Enregistrer un ou plusieurs composants globaux ou directives personnalisées avec [`app.component()`](/api/application#app-component) et [`app.directive()`](/api/application#app-directive).

2. Rendre une ressource [injectable](/guide/components/provide-inject) dans toute l'application en appelant [`app.provide()`](/api/application#app-provide).

3. Ajouter quelques propriétés ou méthodes d'instance globale en les attachant à [`app.config.globalProperties`](/api/application#app-config-globalproperties).

4. Une librairie qui doit effectuer une combinaison des éléments ci-dessus (par exemple, [vue-router](https://github.com/vuejs/vue-router-next)).

## Écrire un plugin {#writing-a-plugin}

Afin de mieux comprendre comment créer vos propres plugins Vue.js, nous allons créer une version très simplifiée d'un plugin qui affiche les chaînes de caractères `i18n` (abréviation d'[internationalisation](https://en.wikipedia.org/wiki/Internationalization_and_localization)).

Commençons par configurer l'objet plugin. Il est recommandé de le créer dans un fichier séparé et de l'exporter, comme montré ci-dessous, afin que la logique reste contenue et séparée.

```js [plugins/i18n.js]
export default {
  install: (app, options) => {
    // Le code du plugin s'écrit ici
  }
}
```

Nous voulons créer une fonction de traduction. Cette fonction recevra une chaîne de caractères `key` délimitée par des points, que nous utiliserons pour rechercher la chaîne de caractères traduite dans les options fournies par l'utilisateur. C'est l'utilisation prévue dans les templates :

```vue-html
<h1>{{ $translate('greetings.hello') }}</h1>
```

Puisque cette fonction devrait être disponible globalement dans tous les templates, nous allons nous en assurer en l'attachant à `app.config.globalProperties` dans notre plugin :

```js{3-10} [plugins/i18n.js]
export default {
  install: (app, options) => {
    // injecte une méthode globalement disponible $translate()
    app.config.globalProperties.$translate = (key) => {
      // récupérer une propriété imbriquée dans `options`
      // en utilisant `key` comme chemin
      return key.split('.').reduce((o, i) => {
        if (o) return o[i]
      }, options)
    }
  }
}
```

Notre fonction `$translate` va prendre une chaîne de caractères telle que `greetings.hello`, regarder dans la configuration fournie par l'utilisateur et retourner la valeur traduite.

L'objet contenant les clés traduites doit être passé au plugin pendant l'installation via des paramètres supplémentaires à `app.use()` :

```js
import i18nPlugin from './plugins/i18n'

app.use(i18nPlugin, {
  greetings: {
    hello: 'Bonjour!'
  }
})
```

Maintenant, notre expression initiale `$translate('greetings.hello')` sera remplacée par `Bonjour!` au moment de l'exécution.

Voir aussi : [Augmenter les propriétés globales](/guide/typescript/options-api#augmenting-global-properties)&#x20;

:::tip
N'utilisez que rarement les propriétés globales, car cela peut rapidement devenir confus si trop de propriétés globales injectées par différents plugins sont utilisées dans une application.
:::

### Provide / Inject avec les plugins {#provide-inject-with-plugins}

Les plugins nous permettent également d'utiliser `provide` pour donner aux utilisateurs du plugin l'accès à une fonction ou à un attribut. Par exemple, nous pouvons permettre à l'application d'avoir accès au paramètre `options` pour pouvoir utiliser l'objet translations.

```js{3} [plugins/i18n.js]
export default {
  install: (app, options) => {
    app.provide('i18n', options)
  }
}
```

Les utilisateurs de plugins pourront désormais injecter les options du plugin dans leurs composants en utilisant la clé `i18n` :

```vue{4}
<script setup>
import { inject } from 'vue'

const i18n = inject('i18n')

console.log(i18n.greetings.hello)
</script>
```

```js{2}
export default {
  inject: ['i18n'],
  created() {
    console.log(this.i18n.greetings.hello)
  }
}
```

### Bundle pour NPM {#bundle-for-npm}

Si vous souhaitez ensuite créer et publier votre plugin pour que d'autres puissent l'utiliser, consultez [la section de Vite sur le mode bibliothèque](https://vite.dev/guide/build.html#library-mode).

---

---
url: /guide/essentials/component-basics.md
---
# Principes fondamentaux des composants {#components-basics}

Les composants nous permettent de fractionner l'UI en morceaux indépendants et réutilisables, sur lesquels nous pouvons réfléchir de manière isolée. Il est courant pour une application d'être organisée en un arbre de composants imbriqués.

![Component Tree](./images/components.png)

Cette approche est très similaire à celle d'imbriquer des éléments HTML natifs, mais Vue implémente son propre modèle de composant, nous permettant d'encapsuler du contenu et de la logique au sein de chaque composant. Vue fonctionne également bien avec les Web Components natifs. Pour en savoir plus sur la relation entre les composants Vue et les Web Components natifs, [lisez ceci](/guide/extras/web-components).

## Définir un composant {#defining-a-component}

Lorsqu'on utilise des outils de build, on définit généralement chaque composant Vue dans un fichier dédié en utilisant l'extension `.vue` - aussi appelé [Composant monofichier](/guide/scaling-up/sfc) (ou Single-File Components en anglais, abrégé SFC) :

```vue
<script>
export default {
  data() {
    return {
      count: 0
    }
  }
}
</script>

<template>
  <button @click="count++">You clicked me {{ count }} times.</button>
</template>
```

```vue
<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">You clicked me {{ count }} times.</button>
</template>
```

Sans outils de build, un composant Vue peut être défini comme un simple objet JavaScript contenant des options spécifiques à Vue :

```js
export default {
  data() {
    return {
      count: 0
    }
  },
  template: `
    <button @click="count++">
      You clicked me {{ count }} times.
    </button>`
}
```

```js
import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)
    return { count }
  },
  template: `
    <button @click="count++">
      You clicked me {{ count }} times.
    </button>`
  // Peut également cibler un template dans le DOM :
  // `template: '#my-template-element'`
}
```

Le template est écrit telle une chaîne de caractère JavaScript que Vue va compiler à la volée. Vous pouvez aussi utiliser un sélecteur d'ID pointant sur un élément (généralement des éléments natifs `<template>`) - Vue utilisera son contenu comme la source du template.

L'exemple ci-dessus définit un composant et l'exporte comme l'export par défaut d'un fichier `.js`, mais vous pouvez utiliser les exports nommés pour exporter plusieurs composants à partir d'un même fichier.

## Utiliser un composant {#using-a-component}

:::tip
Nous allons utiliser la syntaxe SFC dans le reste de ce guide - les concepts des composants sont les mêmes que vous utilisiez des outils de build ou non. La section [Exemples](/examples/) illustre l'utilisation des composants dans les deux scénarios.
:::

Afin d'utiliser un composant enfant, nous devons l'importer dans le composant parent. En supposant que nous ayons placé notre composant compteur dans un fichier nommé `ButtonCounter.vue`, le composant apparaîtra comme l'export par défaut du fichier :

```vue
<script>
import ButtonCounter from './ButtonCounter.vue'

export default {
  components: {
    ButtonCounter
  }
}
</script>

<template>
  <h1>Here is a child component!</h1>
  <ButtonCounter />
</template>
```

Pour exposer le composant importé à notre template, nous devons l'[enregistrer](/guide/components/registration) via l'option `components`. Le composant sera alors utilisable grâce à une balise portant la clé utilisée lors de l'enregistrement.

```vue
<script setup>
import ButtonCounter from './ButtonCounter.vue'
</script>

<template>
  <h1>Here is a child component!</h1>
  <ButtonCounter />
</template>
```

Avec `<script setup>`, les composants importés sont directement rendus accessibles au template.

Il est également possible d'enregistrer globalement un composant, le rendant alors accessible à tous les composants d'une application sans avoir à l'importer. Les pour et contre d'un enregistrement global vs. local sont abordés dans la section [Enregistrement des Composants](/guide/components/registration) dédiée.

Vous pouvez réutiliser les composants autant de fois que vous voulez :

```vue-html
<h1>Here are many child components!</h1>
<ButtonCounter />
<ButtonCounter />
<ButtonCounter />
```

[Essayer en ligne](https://play.vuejs.org/#eNqVUE1LxDAQ/StjLqusNHotcfHj4l8QcontLBtsJiGdiFL6301SdrEqyEJyeG9m3ps3k3gIoXlPKFqhxi7awDtN1gUfGR4Ts6cnn4gxwj56B5tGrtgyutEEoAk/6lCPe5MGhqmwnc9KhMRjuxCwFi3UrCk/JU/uGTC6MBjGglgdbnfPGBFM/s7QJ3QHO/TfxC+UzD21d72zPItU8uQrrsWvnKsT/ZW2N2wur45BI3KKdETlFlmphZsF58j/RgdQr3UJuO8G273daVFFtlstahngxSeoNezBIUzTYgPzDGwdjk1VkYvMj4jzF0nwsyQ=)

[Essayer en ligne](https://play.vuejs.org/#eNqVj91KAzEQhV/lmJsqlY3eSlr8ufEVhNys6ZQGNz8kE0GWfXez2SJUsdCLuZiZM9+ZM4qnGLvPQuJBqGySjYxMXOJWe+tiSIznwhz8SyieKWGfgsOqkyfTGbDSXsmFUG9rw+Ti0DPNHavD/faVEqGv5Xr/BXOwww4mVBNPnvOVklXTtKeO8qKhkj++4lb8+fL/mCMS7TEdAy6BtDfBZ65fVgA2s+L67uZMUEC9N0s8msGaj40W7Xa91qKtgbdQ0Ha0gyOM45E+TWDrKHeNIhfMr0DTN4U0me8=)

Notez que lorsque vous cliquez sur les boutons, chacun d'entre eux maintient son propre `count` individuel. Cela s'explique par le fait que chaque fois que vous utilisez un composant, une nouvelle **instance** de ce dernier est créée.

Dans les SFC, il est recommandé d'utiliser des noms de balise en casse Pascal (`PascalCase`) pour les composants enfants afin de les différencier des éléments HTML natifs. Bien que les noms des balises HTML natifs soient insensibles à la casse, les SFC de Vue sont un format compilé, donc nous pouvons y utiliser des noms de balise sensibles à la casse. Nous pouvons également utiliser `/>` pour fermer une balise.

Si vous éditez vos templates directement dans un DOM (par exemple comme le contenu d'un élément natif `<template>`), le template sera soumis au parsing HTML par défaut du navigateur. Dans ces cas de figure, vous aurez besoin d'utiliser la casse kebab (`kebab-case`) et de fermer explicitement les balises pour vos composants :

```vue-html
<!-- Si le template est écrit dans le DOM -->
<button-counter></button-counter>
<button-counter></button-counter>
<button-counter></button-counter>
```

Voir les [mises en garde concernant l'analyse du template DOM](#in-dom-template-parsing-caveats) pour plus de détails.

## Passer des props {#passing-props}

Si nous construisons un blog, il est probable que nous ayons besoin d'un composant pour représenter un article du blog. Nous voulons que tous les articles partagent la même mise en page, mais avec un contenu différent. Un tel composant ne sera utile que si vous pouvez lui passer des données, comme le titre et le contenu d'un article spécifique que l'on voudrait afficher. C'est là que les props entrent en jeu.

Les props sont des attributs personnalisés que l'on peut enregistrer sur un composant. Pour passer un titre au composant article de notre blog, nous devons le déclarer dans la liste des props que ce composant accepte, en utilisant l'option [`props`](/api/options-state#props)la macro [`defineProps`](/api/sfc-script-setup#defineprops-defineemits) :

```vue [BlogPost.vue]
<script>
export default {
  props: ['title']
}
</script>

<template>
  <h4>{{ title }}</h4>
</template>
```

Lorsqu'une valeur est passée à un attribut prop, il devient une propriété de l'instance du composant. La valeur de cette propriété est accessible à l'intérieur du template et dans le contexte `this` du composant, tout comme n'importe quelle autre de ses propriétés.

```vue [BlogPost.vue]
<script setup>
defineProps(['title'])
</script>

<template>
  <h4>{{ title }}</h4>
</template>
```

`defineProps` est une macro de compilation qui est seulement accessible à l'intérieur de `<script setup>` et ne nécessite pas d'être explicitement importée. Les props déclarées sont automatiquement exposées au template. `defineProps` retourne également un objet contenant toutes les propriétés passées au composant, de manière à ce que l'on puisse y accéder en JavaScript si nécessaire :

```js
const props = defineProps(['title'])
console.log(props.title)
```

Voir aussi : [Typer les props d'un composant](/guide/typescript/composition-api#typing-component-props)&#x20;

Si vous n'utilisez pas `<script setup>`, les propriétés doivent être déclarées via l'option `props`, et l'objet props sera passé à `setup()` en premier argument :

```js
export default {
  props: ['title'],
  setup(props) {
    console.log(props.title)
  }
}
```

Un composant peut avoir autant de props que vous voulez, et par défaut, n'importe quelle valeur peut être passée à une prop.

Une fois qu'une prop est enregistrée, vous pouvez lui passer des données via un attribut personnalisé, de cette manière :

```vue-html
<BlogPost title="My journey with Vue" />
<BlogPost title="Blogging with Vue" />
<BlogPost title="Why Vue is so fun" />
```

Toutefois, dans une application classique, vous auriez sûrement un tableau d'article dans votre composant parent :

```js
export default {
  // ...
  data() {
    return {
      posts: [
        { id: 1, title: 'My journey with Vue' },
        { id: 2, title: 'Blogging with Vue' },
        { id: 3, title: 'Why Vue is so fun' }
      ]
    }
  }
}
```

```js
const posts = ref([
  { id: 1, title: 'My journey with Vue' },
  { id: 2, title: 'Blogging with Vue' },
  { id: 3, title: 'Why Vue is so fun' }
])
```

Puis vous voudriez rendre un composant pour chacun d'entre eux, grâce à `v-for` :

```vue-html
<BlogPost
  v-for="post in posts"
  :key="post.id"
  :title="post.title"
 />
```

[Essayer en ligne](https://play.vuejs.org/#eNp9UU1rhDAU/CtDLrawVfpxklRo74We2kPtQdaoaTUJ8bmtiP+9ia6uC2VBgjOZeXnz3sCejAkPnWAx4+3eSkNJqmRjtCU817p81S2hsLpBEEYL4Q1BqoBUid9Jmosi62rC4Nm9dn4lFLXxTGAt5dG482eeUXZ1vdxbQZ1VCwKM0zr3x4KBATKPcbsDSapFjOClx5d2JtHjR1KFN9fTsfbWcXdy+CZKqcqL+vuT/r3qvQqyRatRdMrpF/nn/DNhd7iPR+v8HCDRmDoj4RHxbfyUDjeFto8p8yEh1Rw2ZV4JxN+iP96FMvest8RTTws/gdmQ8HUr7ikere+yHduu62y//y3NWG38xIOpeODyXcoE8OohGYZ5VhhHHjl83sD4B3XgyGI=)

[Essayer en ligne](https://play.vuejs.org/#eNp9kU9PhDAUxL/KpBfWBCH+OZEuid5N9qSHrQezFKhC27RlDSF8d1tYQBP1+N78OpN5HciD1sm54yQj1J6M0A6Wu07nTIpWK+MwwPASI0qjWkQejVbpsVHVQVl30ZJ0WQRHjwFMnpT0gPZLi32w2h2DMEAUGW5iOOEaniF66vGuOiN5j0/hajx7B4zxxt5ubIiphKz+IO828qXugw5hYRXKTnqSydcrJmk61/VF/eB4q5s3x8Pk6FJjauDO16Uye0ZCBwg5d2EkkED2wfuLlogibMOTbMpf9tMwP8jpeiMfRdM1l8Tk+/F++Y6Cl0Lyg1Ha7o7R5Bn9WwSg9X0+DPMxMI409fPP1PELlVmwdQ==)

Remarquez que la [syntaxe `v-bind`](/api/built-in-directives#v-bind) (`:title="post.title"`) est utilisée pour passer des valeurs de props dynamiques. Cela est particulièrement utile lorsque vous ne connaissez pas le contenu exact que vous allez rendre au fur et à mesure du temps.

Pour le moment, c'est tout ce dont vous avez besoin concernant les props, mais une fois que vous aurez terminé de lire cette page et vous sentirez à l'aise avec son contenu, nous vous recommandons de revenir afin de lire le guide complet sur les [Props](/guide/components/props).

## Écouter des événements {#listening-to-events}

Au fur et à mesure que nous développons notre composant `<BlogPost>`, certaines fonctionnalités peuvent nécessiter de communiquer avec le parent. Par exemple, on peut décider d'inclure une fonctionnalité d'accessibilité permettant d'agrandir le texte des articles du blog, tout en laissant la taille par défaut sur le reste de la page.

Dans le parent, nous pouvons développer cette fonctionnalité en ajoutant une propriété de donnéesref `postFontSize` :

```js{6}
data() {
  return {
    posts: [
      /* ... */
    ],
    postFontSize: 1
  }
}
```

```js{5}
const posts = ref([
  /* ... */
])

const postFontSize = ref(1)
```

Qui pourra être utilisée dans le template afin de contrôler la taille de police de tous les articles du blog :

```vue-html{1,7}
<div :style="{ fontSize: postFontSize + 'em' }">
  <BlogPost
    v-for="post in posts"
    :key="post.id"
    :title="post.title"
   />
</div>
```

Maintenant ajoutons un bouton dans le template du composant `<BlogPost>` :

```vue{5} [BlogPost.vue]
<template>
  <div class="blog-post">
    <h4>{{ title }}</h4>
    <button>Enlarge text</button>
  </div>
</template>
```

Pour le moment le bouton ne fait rien - nous voulons que le clique communique au parent qu'il doit agrandir le texte de tous les articles. Pour résoudre ce problème, les composants fournissent un système personnalisé d'événements. Le parent peut choisir d'écouter n'importe quel événement de l'instance du composant enfant grâce à `v-on` ou `@`, comme nous le ferions avec un événement natif du DOM :

```vue-html{3}
<BlogPost
  ...
  @enlarge-text="postFontSize += 0.1"
 />
```

Ensuite le composant enfant peut émettre lui-même un événement en appelant la méthode intégrée [**`$emit`**](/api/component-instance#emit), et en lui passant le nom de l'événement :

```vue{5} [BlogPost.vue]
<template>
  <div class="blog-post">
    <h4>{{ title }}</h4>
    <button @click="$emit('enlarge-text')">Enlarge text</button>
  </div>
</template>
```

Grâce à l'écouteur `@enlarge-text="postFontSize += 0.1"`, le parent va recevoir l'événement et mettre à jour la valeur de `postFontSize`.

[Essayer en ligne](https://play.vuejs.org/#eNqNUsFOg0AQ/ZUJMaGNbbHqidCmmujNxMRED9IDhYWuhV0CQy0S/t1ZYIEmaiRkw8y8N/vmMZVxl6aLY8EM23ByP+Mprl3Bk1RmCPexjJ5ljhBmMgFzYemEIpiuAHAFOzXQgIVeESNUKutL4gsmMLfbBPStVFTP1Bl46E2mup4xLDKhI4CUsMR+1zFABTywYTkD5BgzG8ynEj4kkVgJnxz38Eqaut5jxvXAUCIiLqI/8TcD/m1fKhTwHHIJYSEIr+HbnqikPkqBL/yLSMs23eDooNexel8pQJaksYeMIgAn4EewcyxjtnKNCsK+zbgpXILJEnW30bCIN7ZTPcd5KDNqoWjARWufa+iyfWBlV13wYJRvJtWVJhiKGyZiL4vYHNkJO8wgaQVXi6UGr51+Ndq5LBqMvhyrH9eYGePtOVu3n3YozWSqFsBsVJmt3SzhzVaYY2nm9l82+7GX5zTGjlTM1SyNmy5SeX+7rqr2r0NdOxbFXWVXIEoBGz/m/oHIF0rB5Pz6KTV6aBOgEo7Vsn51ov4GgAAf2A==)

[Essayer en ligne](https://play.vuejs.org/#eNp1Uk1PwkAQ/SuTxqQYgYp6ahaiJngzITHRA/UAZQor7W7TnaK16X93th8UEuHEvPdm5s3bls5Tmo4POTq+I0yYyZTAIOXpLFAySXVGUEKGEVQQZToBl6XukXqO9XahDbXc2OsAO5FlAIEKtWJByqCBqR01WFqiBLnxYTIEkhSjD+5rAV86zxQW8C1pB+88Aaphr73rtXbNVqrtBeV9r/zYFZYHacBoiHLFykB9Xgfq1NmLVvQmf7E1OGFaeE0anAMXhEkarwhtRWIjD+AbKmKcBk4JUdvtn8+6ARcTu87hLuCf6NJpSoDDKNIZj7BtIFUTUuB0tL/HomXHcnOC18d1TF305COqeJVtcUT4Q62mtzSF2/GkE8/E8b1qh8Ljw/if8I7nOkPn9En/+Ug2GEmFi0ynZrB0azOujbfB54kki5+aqumL8bING28Yr4xh+2vePrI39CnuHmZl2TwwVJXwuG6ZdU6kFTyGsQz33HyFvH5wvvyaB80bACwgvKbrYgLVH979DQc=)

Nous pouvons, de manière facultative, déclarer les événements émis en utilisant l'option [`emits`](/api/options-state#emits)[`defineEmits`](/api/sfc-script-setup#defineprops-defineemits)une macro :

```vue{5} [BlogPost.vue]
<script>
export default {
  props: ['title'],
  emits: ['enlarge-text']
}
</script>
```

```vue{4} [BlogPost.vue]
<script setup>
defineProps(['title'])
defineEmits(['enlarge-text'])
</script>
```

Cela documente tous les événements qu'un composant émet et peut éventuellement les [valider](/guide/components/events#events-validation). Cela permet également à Vue d'éviter de les appliquer implicitement en tant qu'écouteurs natifs à l'élément racine du composant enfant.

Comme c'est le cas pour `defineProps`, `defineEmits` n'est utilisable que dans `<script setup>` et ne nécessite pas d'être importé. Une fonction `emit` est retournée, similaire à la méthode `$emit`. Cela peut être utilisé pour émettre des événements dans la section `<script setup>` d'un composant, où `$emit` n'est pas directement accessible :

```vue
<script setup>
const emit = defineEmits(['enlarge-text'])

emit('enlarge-text')
</script>
```

Voir aussi : [Typer les emits d'un composant](/guide/typescript/composition-api#typing-component-emits)&#x20;

Dans le cas où vous n'utilisez pas `<script setup>`, vous pouvez déclarer les événements émis en utilisant l'option `emits`. Vous pouvez accéder à la fonction `emit` via une propriété du contexte du setup (passé à `setup()` en deuxième argument) :

```js
export default {
  emits: ['enlarge-text'],
  setup(props, ctx) {
    ctx.emit('enlarge-text')
  }
}
```

Pour le moment, c'est tout ce dont vous avez besoin concernant les événements personnalisés de composants, mais une fois que vous aurez terminé de lire cette page et vous sentirez à l'aise avec son contenu, nous vous recommandons de revenir afin de lire le guide complet sur la [Gestion des événements](/guide/components/events).

## Distribution de contenu avec les slots {#content-distribution-with-slots}

Comme pour les éléments HTML, il est souvent utile de pouvoir passer du contenu à un composant, de cette manière :

```vue-html
<AlertBox>
  Quelque chose de grave s'est produit.
</AlertBox>
```

Ce qui devrait rendre :

:::danger Il s'agit d'une Erreur à des fins de Démonstration
Quelque chose de grave s'est produit.
:::

Cela peut être réalisé en utilisant l'élément personnalisé de Vue `<slot>` :

```vue{5} [AlertBox.vue]
<template>
  <div class="alert-box">
    <strong>Il s'agit d'une Erreur à des fins de Démonstration</strong>
    <slot />
  </div>
</template>

<style scoped>
.alert-box {
  /* ... */
}
</style>
```

Comme vous le verrez, nous utilisons `<slot>` comme un espace réservé où nous voulons que le contenu aille – et c'est tout. Nous avons terminé !

[Essayer en ligne](https://play.vuejs.org/#eNpVUcFOwzAM/RUTDruwFhCaUCmThsQXcO0lbbKtIo0jx52Kpv07TreWouTynl+en52z2oWQnXqrClXGhtrA28q3XUBi2DlL/IED7Ak7WGX5RKQHq8oDVN4Oo9TYve4dwzmxDcp7bz3HAs5/LpfKyy3zuY0Atl1wmm1CXE5SQeLNX9hZPrb+ALU2cNQhWG9NNkrnLKIt89lGPahlyDTVogVAadoTNE7H+F4pnZTrGodKjUUpRyb0h+0nEdKdRL3CW7GmfNY5ZLiiMhfP/ynG0SL/OAuxwWCNMNncbVqSQyrgfrPZvCVcIxkrxFMYIKJrDZA1i8qatGl72ehLGEY6aGNkNwU8P96YWjffB8Lem/Xkvn9NR6qy+fRd14FSgopvmtQmzTT9Toq9VZdfIpa5jQ==)

[Essayer en ligne](https://play.vuejs.org/#eNpVUEtOwzAQvcpgFt3QBBCqUAiRisQJ2GbjxG4a4Xis8aQKqnp37PyUyqv3mZn3fBVH55JLr0Umcl9T6xi85t4VpW07h8RwNJr4Cwc4EXawS9KFiGO70ubpNBcmAmDdOSNZR8T5Yg0IoOQf7DSfW9tAJRWcpXPaapWM1nVt8ObpukY8ie29GHNzAiBX7QVqI73/LIWMzn2FQylGMcieCW1TfBMhPYSoE5zFitLVZ5BhQnkadt6nGKt5/jMafI1Oq8Ak6zW4xrEaDVIGj4fD4SPiCknpQLy4ATyaVgFptVH2JFXb+wze3DDSTioV/iaD1+eZqWT92xD2Vu2X7af3+IJ6G7/UToVigpJnTzwTO42eWDnELsTtH/wUqH4=)

Pour le moment, c'est tout ce dont vous avez besoin concernant les slots, mais une fois que vous aurez terminé de lire cette page et vous sentirez à l'aise avec son contenu, nous vous recommandons de revenir afin de lire le guide complet sur les [Slots](/guide/components/slots).

## Composants dynamiques {#dynamic-components}

Parfois, il peut être utile d'alterner dynamiquement entre des composants, comme dans une interface avec des onglets :

[Essayer en ligne](https://play.vuejs.org/#eNqNVE2PmzAQ/Ssj9kArLSHbrXpwk1X31mMPvS17cIxJrICNbJMmivLfO/7AEG2jRiDkefP85sNmztlr3y8OA89ItjJMi96+VFJ0vdIWfqqOQ6NVB/midIYj5sn9Sxlrkt9b14RXzXbiMElEO5IAKsmPnljzhg6thbNDmcLdkktrSADAJ/IYlj5MXEc9Z1w8VFNLP30ed2luBy1HC4UHrVH2N90QyJ1kHnUALN1gtLeIQu6juEUMkb8H5sXHqiS+qzK1Cw3Lu76llqMFsKrFAVhLjVlXWc07VWUeR89msFbhhhAWDkWjNJIwPgjp06iy5CV7fgrOOTgKv+XoKIIgpnoGyiymSmZ1wnq9dqJweZ8p/GCtYHtUmBMdLXFitgDnc9ju68b0yxDO1WzRTEcFRLiUJsEqSw3wwi+rMpFDj0psEq5W5ax1aBp7at1y4foWzq5R0hYN7UR7ImCoNIXhWjTfnW+jdM01gaf+CEa1ooYHzvnMVWhaiwEP90t/9HBP61rILQJL3POMHw93VG+FLKzqUYx3c2yjsOaOwNeRO2B8zKHlzBKQWJNH1YHrplV/iiMBOliFILYNK5mOKdSTMviGCTyNojFdTKBoeWNT3s8f/Vpsd7cIV61gjHkXnotR6OqVkJbrQKdsv9VqkDWBh2bpnn8VXaDcHPexE4wFzsojO9eDUOSVPF+65wN/EW7sHRsi5XaFqaexn+EH9Xcpe8zG2eWG3O0/NVzUaeJMk+jGhUXlNPXulw5j8w7t2bi8X32cuf/Vv/wF/SL98A==)

[Essayer en ligne](https://play.vuejs.org/#eNqNVMGOmzAQ/ZURe2BXCiHbrXpwk1X31mMPvS1V5RiTWAEb2SZNhPLvHdvggLZRE6TIM/P8/N5gpk/e2nZ57HhCkrVhWrQWDLdd+1pI0bRKW/iuGg6VVg2ky9wFDp7G8g9lrIl1H80Bb5rtxfFKMcRzUA+aV3AZQKEEhWRKGgus05pL+5NuYeNwj6mTkT4VckRYujVY63GT17twC6/Fr4YjC3kp5DoPNtEgBpY3bU0txwhgXYojsJoasymSkjeqSHweK9vOWoUbXIC/Y1YpjaDH3wt39hMI6TUUSYSQAz8jArPT5Mj+nmIhC6zpAu1TZlEhmXndbBwpXH5NGL6xWrADMsyaMj1lkAzQ92E7mvYe8nCcM24xZApbL5ECiHCSnP73KyseGnvh6V/XedwS2pVjv3C1ziddxNDYc+2WS9fC8E4qJW1W0UbUZwKGSpMZrkX11dW2SpdcE3huT2BULUp44JxPSpmmpegMgU/tyadbWpZC7jCxwj0v+OfTDdU7ITOrWiTjzTS3Vei8IfB5xHZ4PmqoObMEJHryWXXkuqrVn+xEgHZWYRKbh06uLyv4iQq+oIDnkXSQiwKymlc26n75WNdit78FmLWCMeZL+GKMwlKrhLRcBzhlh51WnSwJPFQr9/zLdIZ007w/O6bR4MQe2bseBJMzer5yzwf8MtzbOzYMkNsOY0+HfoZv1d+lZJGMg8fNqdsfbbio4b77uRVv7I0Li8xxZN1PHWbeHdyTWXc/+zgw/8t/+QsROe9h)

Cela est rendu possible par l'élément `<component>` de Vue avec l'attribut spécial `is` :

```vue-html
<!-- Le composant change lorsque currentTab change -->
<component :is="currentTab"></component>
```

```vue-html
<!-- Le composant change lorsque currentTab change -->
<component :is="tabs[currentTab]"></component>
```

Dans l'exemple ci-dessus, la valeur passée à `:is` peut contenir au choix :

* une chaîne de caractères représentant le nom d'un composant enregistré, OU
* le véritable objet composant importé

Vous pouvez également utiliser l'attribut `is` pour créer des éléments HTML classiques.

Lorsqu'on alterne entre plusieurs composants avec `<component :is="...">`, seul celui sélectionné par `:is` reste monté. On peut forcer les composants inactifs à rester "en vie" grâce au [composant intégré `<KeepAlive>`](/guide/built-ins/keep-alive).

## Mises en garde concernant l'analyse du template DOM {#in-dom-template-parsing-caveats}

Si vous écrivez vos templates Vue directement dans le DOM, Vue va devoir extraire du DOM la chaîne de caractères représentant le template. Cela entraîne quelques avertissements à cause du comportement d'analyse du HTML natif des navigateurs.

:::tip
Il est important de rappeler que les limitations que nous allons aborder ne s'appliquent que lorsque vous écrivez vos templates directement dans le DOM. Elles ne s'appliquent PAS si vous utilisez des templates en chaîne de caractères à partir des sources suivantes :

* Composants Monofichiers
* Chaînes de caractères représentant le template écrites en ligne (par exemple `template: '...'`)
* `<script type="text/x-template">`
  :::

### Insensibilité de la casse {#case-insensitivity}

Les balises HTML et les noms des attributs sont insensibles à la casse, donc les navigateurs interpréteront une lettre majuscule comme une lettre minuscule. Cela signifie que lorsque vous utilisez des templates dans le DOM, les noms des composants en casse Pascal et les noms des propriétés en casse Camel ou encore les noms des événements `v-on` doivent tous utiliser leurs équivalent en casse Kebab (séparation par un trait d'union) :

```js
// casse Camel en JavaScript
const BlogPost = {
  props: ['postTitle'],
  emits: ['updatePost'],
  template: `
    <h3>{{ postTitle }}</h3>
  `
}
```

```vue-html
<!-- casse Camel en HTML -->
<blog-post post-title="hello!" @update-post="onUpdatePost"></blog-post>
```

### Balises auto-fermantes {#self-closing-tags}

Nous avons utilisé des balises auto-fermantes pour les composants dans les exemples de code précédents :

```vue-html
<MyComponent />
```

Ceci s'explique par le fait que l'outil d'analyse d'un template Vue respecte `/>` comme une indication de fin de balise, peu importe son type.

Dans les templates du DOM, cependant, nous devons toujours inclure des fermetures de balise explicites :

```vue-html
<my-component></my-component>
```

Cela est dû aux spécifications du HTML qui n'autorisent que [quelques éléments spécifiques](https://html.spec.whatwg.org/multipage/syntax.html#void-elements) à omettre la fermeture des balises, les plus communs étant `<input>` et `<img>`. Pour tous les autres éléments, si vous omettez de fermer les balises, l'outil d'analyse du HTML natif pensera que vous n'avez jamais terminé leur ouverture. Par exemple, le bout de code suivant :

```vue-html
<my-component /> <!-- nous voulons fermer la balise ici... -->
<span>hello</span>
```

Sera analysé comme :

```vue-html
<my-component>
  <span>hello</span>
</my-component> <!-- mais le navigateur le fermera ici -->
```

### Restrictions pour le placement des éléments {#element-placement-restrictions}

Certains éléments HTML, comme `<ul>`, `<ol>`, `<table>` et `<select>` ont des restrictions concernant quels éléments ils peuvent contenir, et certains éléments comme `<li>`, `<tr>`, et `<option>` ne peuvent apparaître qu'à l'intérieur de certains éléments.

Cela va entraîner des problèmes lorsque nous allons utiliser des composants avec des éléments qui ont ce genre de restrictions. Par exemple :

```vue-html
<table>
  <blog-post-row></blog-post-row>
</table>
```

Le composant personnalisé `<blog-post-row>` sera relevé comme contenu invalide, ce qui peut causer des erreurs dans le résultat rendu final. Nous pouvons utiliser [l'attribut spécial `is`](/api/built-in-special-attributes#is) comme solution :

```vue-html
<table>
  <tr is="vue:blog-post-row"></tr>
</table>
```

:::tip
Lorsqu'il est utilisé sur des éléments HTML natifs, la valeur de `is` doit être préfixée de `vue:` afin d'être interprétée comme un composant Vue. Cela est nécessaire afin d'éviter les confusions avec les [éléments personnalisés intégrés](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example).
:::

C'est tout ce que vous avez besoin de savoir à propos des mises en garde concernant l'analyse du template DOM pour le moment - et d'ailleurs, la fin des *Essentiels* de Vue. Félicitations ! Il y a encore à apprendre, mais d'abord, nous vous recommandons de prendre une pause afin d'expérimenter Vue par vous-même - construisez quelque chose d'amusant, ou découvrez certains des [Exemples](/examples/) si ça n'est pas déjà fait.

Dès que vous vous sentez à l'aise avec le savoir que vous venez de digérer, avancez dans le guide pour découvrir les composants en profondeur.

---

---
url: /guide/essentials/computed.md
---
# Propriétés calculées {#computed-properties}

## Exemple basique {#basic-example}

Les expressions dans le template sont pratiques, mais elles sont destinées à des opérations simples. Mettre trop de logique dans vos templates peut les encombrer et les rendre difficiles à maintenir. Par exemple, si nous avons un objet avec un tableau imbriqué :

```js
export default {
  data() {
    return {
      author: {
        name: 'John Doe',
        books: [
          'Vue 2 - Advanced Guide',
          'Vue 3 - Basic Guide',
          'Vue 4 - The Mystery'
        ]
      }
    }
  }
}
```

```js
const author = reactive({
  name: 'John Doe',
  books: [
    'Vue 2 - Advanced Guide',
    'Vue 3 - Basic Guide',
    'Vue 4 - The Mystery'
  ]
})
```

Et que nous voulons afficher des messages différents selon que `author` contiennent déjà ou non des livres :

```vue-html
<p>Has published books:</p>
<span>{{ author.books.length > 0 ? 'Yes' : 'No' }}</span>
```

A ce stade, le template devient un peu chargé. Nous devons bien l'examiner avant de réaliser qu'il effectue une opération dépendante de `author.books`. Plus important encore, nous ne voulons sûrement pas nous répéter si nous avons besoin de cette opération dans le template plus d'une fois.

C'est pourquoi pour des logiques complexes incluant des données réactives, il est recommandé d'utiliser une **propriété calculée**. Voici le même exemple, refactorisé :

```js
export default {
  data() {
    return {
      author: {
        name: 'John Doe',
        books: [
          'Vue 2 - Advanced Guide',
          'Vue 3 - Basic Guide',
          'Vue 4 - The Mystery'
        ]
      }
    }
  },
  computed: {
    // un accesseur calculé
    publishedBooksMessage() {
      // `this` pointe sur l'instance du composant
      return this.author.books.length > 0 ? 'Yes' : 'No'
    }
  }
}
```

```vue-html
<p>Has published books:</p>
<span>{{ publishedBooksMessage }}</span>
```

[Essayer en ligne](https://play.vuejs.org/#eNqFkN1KxDAQhV/l0JsqaFfUq1IquwiKsF6JINaLbDNui20S8rO4lL676c82eCFCIDOZMzkzXxetlUoOjqI0ykypa2XzQtC3ktqC0ydzjUVXCIAzy87OpxjQZJ0WpwxgzlZSp+EBEKylFPGTrATuJcUXobST8sukeA8vQPzqCNe4xJofmCiJ48HV/FfbLLrxog0zdfmn4tYrXirC9mgs6WMcBB+nsJ+C8erHH0rZKmeJL0sot2tqUxHfDONuyRi2p4BggWCr2iQTgGTcLGlI7G2FHFe4Q/xGJoYn8SznQSbTQviTrRboPrHUqoZZ8hmQqfyRmTDFTC1bqalsFBN5183o/3NG33uvoWUwXYyi/gdTEpwK)

Ici nous avons déclaré une propriété calculée `publishedBooksMessage`.

Essayez de changer la valeur du tableau `books` dans l'application `data` et vous remarquerez comment `publishedBooksMessage` change en conséquence.

Vous pouvez lier des données à des propriétés calculées dans les templates comme pour une propriété normale. Vue sait que `this.publishedBooksMessage` dépend de `this.author.books`, donc il va mettre à jour les liaisons dépendantes de `this.publishedBooksMessage` lorsque `this.author.books` change.

Voir aussi : [Typing Computed Properties](/guide/typescript/options-api#typing-computed-properties)&#x20;

```vue
<script setup>
import { reactive, computed } from 'vue'

const author = reactive({
  name: 'John Doe',
  books: [
    'Vue 2 - Advanced Guide',
    'Vue 3 - Basic Guide',
    'Vue 4 - The Mystery'
  ]
})

// a computed ref
const publishedBooksMessage = computed(() => {
  return author.books.length > 0 ? 'Yes' : 'No'
})
</script>

<template>
  <p>Has published books:</p>
  <span>{{ publishedBooksMessage }}</span>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNp1kE9Lw0AQxb/KI5dtoTainkoaaREUoZ5EEONhm0ybYLO77J9CCfnuzta0vdjbzr6Zeb95XbIwZroPlMySzJW2MR6OfDB5oZrWaOvRwZIsfbOnCUrdmuCpQo+N1S0ET4pCFarUynnI4GttMT9PjLpCAUq2NIN41bXCkyYxiZ9rrX/cDF/xDYiPQLjDDRbVXqqSHZ5DUw2tg3zP8lK6pvxHe2DtvSasDs6TPTAT8F2ofhzh0hTygm5pc+I1Yb1rXE3VMsKsyDm5JcY/9Y5GY8xzHI+wnIpVw4nTI/10R2rra+S4xSPEJzkBvvNNs310ztK/RDlLLjy1Zic9cQVkJn+R7gIwxJGlMXiWnZEq77orhH3Pq2NH9DjvTfpfSBSbmA==)

Ici nous avons déclaré une propriété calculée `publishedBooksMessage`. La fonction `computed()` prend une [fonction accesseur](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description) en argument, et la valeur retournée est une **ref calculée**. De la même manière que pour les refs classiques, vous pouvez accéder au résultat calculé grâce à `publishedBooksMessage.value`. Les refs calculées sont automatiquement déballées dans les templates de manière à ce que vous puissiez y faire référence sans `.value` dans les expressions au sein du template.

Une propriété calculée traque automatiquement ses dépendances réactives. Vue sait que le calcul de `publishedBooksMessage` dépend de `author.books`, donc il va mettre à jour les liaisons dépendantes de `publishedBooksMessage` lorsque `author.books` change.

Voir aussi : [Typer les propriétés calculées](/guide/typescript/composition-api#typing-computed)&#x20;

## Propriétés calculées mises en cache vs.. les méthodes {#computed-caching-vs-methods}

Vous avez peut-être remarqué que nous pouvons obtenir le même résultat en invoquant une méthode dans l'expression :

```vue-html
<p>{{ calculateBooksMessage() }}</p>
```

```js
// dans le composant
methods: {
  calculateBooksMessage() {
    return this.author.books.length > 0 ? 'Yes' : 'No'
  }
}
```

```js
// dans le composant
function calculateBooksMessage() {
  return author.books.length > 0 ? 'Yes' : 'No'
}
```

À la place d'une propriété calculée, nous pouvons définir la même fonction comme une méthode. Les deux approches mènent au même résultat final. Cependant, la différence est que **les propriétés calculées sont mises en cache en fonction de leurs dépendances réactives.** Une propriété calculée ne sera réévaluée que lorsque l'une de ses dépendances réactives aura changé. Cela signifie que tant que `author.books` n'a pas changé, les accès multiples à `publishedBooksMessage` vont immédiatement retourner le résultat calculé précédent sans avoir à réexécuter la fonction accesseur.

Cela signifie également que la propriété calculée suivante ne sera jamais mise à jour, car `Date.now()` n'est pas une dépendance réactive :

```js
computed: {
  now() {
    return Date.now()
  }
}
```

```js
const now = computed(() => Date.now())
```

En comparaison, l'invocation d'une méthode va **toujours** exécuter la fonction, à chaque nouveau rendu.

Pourquoi avons nous besoin de la mise en cache ? Imaginons que nous ayons une propriété calculée conséquente `list`, qui nécessite de boucler à travers un important tableau et de réaliser de nombreuses opérations. Nous pourrions également avoir d'autres propriétés calculées dépendantes à leur tour de `list`. Sans mise en cache, nous exécuterions les accesseurs de `list` bien plus de fois que nécessaire ! Dans les cas où vous ne voulez pas de mise en cache, vous pouvez utiliser l'appel à une méthode.

## Propriétés calculées modifiables {#writable-computed}

Par défaut, les propriétés calculées ne sont soumises qu'aux accesseurs. Si vous essayez d'assigner une nouvelle valeur à une propriété calculée, vous aurez un avertissement au moment de l'exécution. Dans les rares cas où vous avez besoin d'une propriété calculée "modifiable", vous pouvez en créer une en lui fournissant à la fois un accesseur et un mutateur :

```js
export default {
  data() {
    return {
      firstName: 'John',
      lastName: 'Doe'
    }
  },
  computed: {
    fullName: {
      // accesseur
      get() {
        return this.firstName + ' ' + this.lastName
      },
      // mutateur
      set(newValue) {
        // Note : nous utilisons ici la syntaxe d'assignation par déstructuration.
        ;[this.firstName, this.lastName] = newValue.split(' ')
      }
    }
  }
}
```

Désormais lorsque vous allez exécuter `this.fullName = 'John Doe'`, le mutateur sera invoqué et `this.firstName` et `this.lastName` seront mis à jour en conséquence.

```vue
<script setup>
import { ref, computed } from 'vue'

const firstName = ref('John')
const lastName = ref('Doe')

const fullName = computed({
  // accesseur
  get() {
    return firstName.value + ' ' + lastName.value
  },
  // mutateur
  set(newValue) {
    // Note : nous utilisons ici la syntaxe d'assignation par déstructuration
    ;[firstName.value, lastName.value] = newValue.split(' ')
  }
})
</script>
```

Désormais lorsque vous allez exécuter `fullName.value = 'John Doe'`, le mutateur sera invoqué et `firstName` et `lastName` seront mis à jour en conséquence.

## Obtenir la valeur précédente {#previous}

* Supporté à partir de la version 3.4

```js
export default {
  data() {
    return {
      count: 2
    }
  },
  computed: {
    // Ce calcul renvoie la valeur de count lorsqu'elle est inférieure ou égale à 3.
    // Lorsque count est >=4, la dernière valeur qui remplit notre condition est renvoyée.
    // jusqu'à ce que count soit inférieur ou égal à 3
    alwaysSmall(_, previous) {
      if (this.count <= 3) {
        return this.count
      }

      return previous
    }
  }
}
```

```vue
<script setup>
import { ref, computed } from 'vue'

const count = ref(2)

// Ce calcul renvoie la valeur de count lorsqu'elle est inférieure ou égale à 3.
// Lorsque count est >=4, la dernière valeur qui remplit notre condition est renvoyée.
// jusqu'à ce que count soit inférieur ou égal à 3
const alwaysSmall = computed((previous) => {
  if (count.value <= 3) {
    return count.value
  }

  return previous
})
</script>
```

Si vous utilisez un valeur calculée modifiable :

```js
export default {
  data() {
    return {
      count: 2
    }
  },
  computed: {
    alwaysSmall: {
      get(_, previous) {
        if (this.count <= 3) {
          return this.count
        }

        return previous;
      },
      set(newValue) {
        this.count = newValue * 2
      }
    }
  }
}
```

```vue
<script setup>
import { ref, computed } from 'vue'

const count = ref(2)

const alwaysSmall = computed({
  get(previous) {
    if (count.value <= 3) {
      return count.value
    }

    return previous
  },
  set(newValue) {
    count.value = newValue * 2
  }
})
</script>
```

## Bonnes Pratiques {#best-practices}

### Les accesseurs ne doivent pas entraîner d'effets de bord {#getters-should-be-side-effect-free}

Il est important de se rappeler que les fonctions accesseurs de propriétés calculées doivent seulement réaliser des opérations pures et ne pas entraîner d'effets de bord. Par exemple, **ne faites pas de requêtes asynchrones ou ne mutez pas le DOM à l'intérieur d'un accesseur calculé !** Pensez à une propriété calculée comme une description déclarative de la manière d'obtenir une valeur selon d'autres valeurs - sa seule responsabilité devrait être de calculer et de retourner cette valeur. Plus loin dans le guide nous traiterons de la manière d'effectuer des effets de bord en réaction à des changements de l'état avec les [observateurs](./watchers).

### Évitez de modifier les valeurs calculées {#avoid-mutating-computed-value}

La valeur retournée par une propriété calculée est un état dérivé. Pensez-y comme un snapshot temporaire - chaque fois que l'état de base change, un nouveau snapshot est créé. Il n'est pas logique de modifier un snapshot, donc une valeur calculée retournée ne devrait être traitée qu'en lecture seule et ne pas être modifiée - à la place, modifiez l'état de base dont elle dépend afin d'engendrer de nouveaux calculs.

---

---
url: /guide/components/props.md
---
# Props {#props}

> Cette page suppose que vous avez déjà lu les [principes fondamentaux des composants](/guide/essentials/component-basics). Lisez-les d'abord si vous débutez avec les composants.

## Déclaration de props {#props-declaration}

Les composants Vue nécessitent une déclaration explicite des props afin que Vue sache quels props externes passés au composant doivent être traités comme des attributs implicitement déclarés (qui seront discutés dans [sa section dédiée](/guide/components/attrs)).

Dans les SFC utilisant `<script setup>`, les props peuvent être déclarés à l'aide de la macro `defineProps()` :

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

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

Dans les composants autres que `<script setup>`, les props sont déclarés à l'aide de l'option [`props`](/api/options-state#props) :

```js
export default {
  props: ['foo'],
  setup(props) {
    // setup() reçoit des props comme premier argument.
    console.log(props.foo)
  }
}
```

Notez que l'argument passé à `defineProps()` est le même que la valeur fournie à l'option `props` : la même API de déclaration de props est partagée entre les deux styles de déclaration.

Les props sont déclarés à l'aide de l'option [`props`](/api/options-state#props) :

```js
export default {
  props: ['foo'],
  created() {
    // les props sont exposés sur `this`
    console.log(this.foo)
  }
}
```

En plus de déclarer des props à l'aide d'un tableau de chaînes de caractères, nous pouvons également utiliser la syntaxe utilisant un objet :

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

```js
// dans <script setup>
defineProps({
  title: String,
  likes: Number
})
```

```js
// dans un fichier autre que <script setup>
export default {
  props: {
    title: String,
    likes: Number
  }
}
```

Pour chaque propriété dans l'objet servant de déclaration, la clé est le nom de la prop, tandis que la valeur doit être la fonction constructeur du type attendu.

Cela documente non seulement votre composant, mais avertira également, dans la console du navigateur, les autres développeurs utilisant votre composant s'ils transmettent le mauvais type. Nous discuterons plus en détail de la [validation de prop](#prop-validation) plus loin sur cette page.

Voir aussi : [Typage de props de composant](/guide/typescript/options-api#typing-component-props)&#x20;

Si vous utilisez TypeScript avec `<script setup>`, il est également possible de déclarer des props en utilisant uniquement des annotations de type :

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

Plus de détails: [Typage de props de composant](/guide/typescript/composition-api#typing-component-props)&#x20;

## Déstructuration réactive des props  \*\* {#reactive-props-destructure}

Le système de réactivité de Vue suit l'utilisation de l'état en fonction de l'accès à la propriété. Par exemple, lorsque vous accédez à `props.foo` dans une computed ou un watcher, la prop `foo` est suivie comme une dépendance.

Ainsi, selon le code suivant :

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

watchEffect(() => {
  // ne s'exécute qu'une seule fois avant 3.5
  // se ré-exécute lorsque la prop "foo" est modifiée dans la version 3.5+.
  console.log(foo)
})
```

Dans les versions 3.4 et inférieures, `foo` est une constante réelle et ne changera jamais. Dans les versions 3.5 et supérieures, le compilateur de Vue ajoute automatiquement le préfixe `props.` lorsque le code dans le même bloc `<script setup>` accède à des variables déstructurées à partir de `defineProps`. Par conséquent, le code ci-dessus devient équivalent à ce qui suit :

```js {5}
const props = defineProps(['foo'])

watchEffect(() => {
  // `foo` transformé en `props.foo` par le compilateur
  console.log(props.foo)
})
```

En outre, vous pouvez utiliser la syntaxe native des valeurs par défaut de JavaScript pour déclarer des valeurs par défaut pour les props. Ceci est particulièrement utile lorsque vous utilisez la déclaration de props basée sur le type :

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

Si vous préférez avoir plus de distinction visuelle entre les props déstructurées et les variables normales dans votre IDE, l'extension VSCode de Vue fournit un paramètre pour activer les indices d'incrustation pour les props déstructurées.

### Passer des props déstructurées dans des fonctions {#passing-destructured-props-into-functions}

Lorsque nous passons une prop déstructurée dans une fonction, par exemple :

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

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

Cela ne fonctionnera pas comme prévu car c'est équivalent à `watch(props.foo, ...)` - nous passons une valeur au lieu d'une source de données réactive à `watch`. En fait, le compilateur de Vue détectera de tels cas et lancera un avertissement.

De la même façon que l'on peut surveiller une prop normale avec `watch(() => props.foo, ...)`, on peut aussi surveiller une prop déstructurée en l'enveloppant dans un getter :

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

En outre, il s'agit de l'approche recommandée lorsque nous devons passer une prop déstructurée dans une fonction externe tout en conservant la réactivité :

```js
useComposable(() => foo)
```

La fonction externe peut appeler le getter (ou le normaliser avec [toValue](/api/reactivity-utilities.html#tovalue)) lorsqu'elle a besoin de suivre les changements de l'objet fourni, par exemple dans un computed ou watcher getter.

## Détails sur le passage de props {#prop-passing-details}

### Casse du nom de prop {#prop-name-casing}

Nous déclarons les noms de props en utilisant le camelCase car cela évite d'avoir à utiliser des guillemets lors de leur utilisation comme clés de propriété, et nous permet de les référencer directement dans les expressions de template car ce sont des identifiants JavaScript valides :

```js
defineProps({
  greetingMessage: String
})
```

```js
export default {
  props: {
    greetingMessage: String
  }
}
```

```vue-html
<span>{{ greetingMessage }}</span>
```

Techniquement, vous pouvez également utiliser le camelCase lors de la transmission de props à un composant enfant (sauf dans les [templates DOM](/guide/essentials/component-basics#in-dom-template-parsing-caveats)). Cependant, la convention utilise le kebab-case dans tous les cas pour s'aligner sur les attributs HTML :

```vue-html
<MyComponent greeting-message="hello" />
```

Nous utilisons le [PascalCase pour les balises de composant](/guide/components/registration#component-name-casing) lorsque cela est possible, car il améliore la lisibilité du template en différenciant les composants Vue des éléments natifs. Cependant, il n'y a pas autant d'avantages pratiques à utiliser le camelCase lors du passage de props, nous avons donc choisi de suivre les conventions de chaque langage.

### Props statiques vs. dynamiques {#static-vs-dynamic-props}

Jusqu'à présent, vous avez vu des props passés en tant que valeurs statiques, comme dans :

```vue-html
<BlogPost title="My journey with Vue" />
```

Vous avez également vu des props assignés dynamiquement avec `v-bind` ou son raccourci `:`, comme dans :

```vue-html
<!-- Attribuer dynamiquement la valeur d'une variable -->
<BlogPost :title="post.title" />

<!-- Attribuer dynamiquement la valeur d'une expression complexe -->
<BlogPost :title="post.title + ' by ' + post.author.name" />
```

### Passage de différents types de valeur {#passing-different-value-types}

Dans les deux exemples ci-dessus, nous passons des chaînes de caractères, mais *n'importe quel* type de valeur peut être passé à une prop.

#### Nombre {#number}

```vue-html
<!-- Même si `42` est statique, nous avons besoin de v-bind pour indiquer à Vue qu'il -->
<!-- s'agit d'une expression JavaScript plutôt que d'une chaîne de caractères.        -->
<BlogPost :likes="42" />

<!-- Attribuer dynamiquement la valeur d'une variable. -->
<BlogPost :likes="post.likes" />
```

#### Booléen {#boolean}

```vue-html
<!-- Inclure la prop sans valeur impliquera `true`. -->
<BlogPost is-published />

<!-- Même si `false` est statique, nous avons besoin de v-bind pour indiquer à Vue qu'il -->
<!-- s'agit d'une expression JavaScript plutôt que d'une chaîne de caractères.           -->
<BlogPost :is-published="false" />

<!-- Attribuer dynamiquement la valeur d'une variable. -->
<BlogPost :is-published="post.isPublished" />
```

#### Tableau {#array}

```vue-html
<!-- Même si le tableau est statique, nous avons besoin de v-bind pour indiquer à Vue qu'il -->
<!-- s'agit d'une expression JavaScript plutôt que d'une chaîne de caractères.              -->
<BlogPost :comment-ids="[234, 266, 273]" />

<!-- Attribuer dynamiquement la valeur d'une variable. -->
<BlogPost :comment-ids="post.commentIds" />
```

#### Objet {object}

```vue-html
<!-- Même si l'objet est statique, nous avons besoin de v-bind pour indiquer à Vue qu'il -->
<!-- s'agit d'une expression JavaScript plutôt que d'une chaîne de caractères.           -->
<BlogPost
  :author="{
    name: 'Veronica',
    company: 'Veridian Dynamics'
  }"
 />

<!-- Attribuer dynamiquement la valeur d'une variable. -->
<BlogPost :author="post.author" />
```

### Liaison de plusieurs propriétés à l'aide d'un objet {#binding-multiple-properties-using-an-object}

Si vous souhaitez transmettre toutes les propriétés d'un objet en tant que props, vous pouvez utiliser [`v-bind` sans argument](/guide/essentials/template-syntax#dynamically-binding-multiple-attributes) (`v-bind` au lieu de `:prop-name`). Par exemple, étant donné un objet `post` :

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

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

Le template suivant :

```vue-html
<BlogPost v-bind="post" />
```

Sera équivalent à :

```vue-html
<BlogPost :id="post.id" :title="post.title" />
```

## Flux de données à sens unique {#one-way-data-flow}

Tous les props forment une **liaison unidirectionnelle** entre la propriété enfant et la propriété parent : lorsque la propriété parent est mise à jour, elle descendra vers l'enfant, mais pas l'inverse. Cela empêche les composants enfants de muter accidentellement l'état du parent, ce qui peut rendre le flux de données de votre application plus difficile à comprendre.

De plus, chaque fois que le composant parent est mis à jour, tous les props du composant enfant seront actualisés avec la dernière valeur. Cela signifie que vous **ne devez pas** tenter de muter une prop à l'intérieur d'un composant enfant. Si vous le faites, Vue vous avertira dans la console :

```js
const props = defineProps(['foo'])

// ❌ avertissement, les props sont en lecture seule !
props.foo = 'bar'
```

```js
export default {
  props: ['foo'],
  created() {
    // ❌ avertissement, les props sont en lecture seule !
    this.foo = 'bar'
  }
}
```

Il y a généralement deux cas où il est tentant de muter une prop :

1. **La prop est utilisée pour passer une valeur initiale; le composant enfant veut ensuite l'utiliser comme propriété de données locale.** Dans ce cas, il est préférable de définir une propriété de données locale qui utilise la prop comme valeur initiale :

   ```js
   const props = defineProps(['initialCounter'])

   // counter utilise uniquement props.initialCounter comme valeur initiale ;
   // il est déconnecté des futures mises à jour de props.
   const counter = ref(props.initialCounter)
   ```

   ```js
   export default {
     props: ['initialCounter'],
     data() {
       return {
         // counter utilise uniquement this.initialCounter comme valeur initiale ;
         // il est déconnecté des futures mises à jour de props.
         counter: this.initialCounter
       }
     }
   }
   ```

2. **La prop est transmise en tant que valeur brute qui doit être transformée.** Dans ce cas, il est préférable de définir une propriété calculée à l'aide de la valeur de la prop :

   ```js
   const props = defineProps(['size'])

   // propriété calculée qui se met à jour automatiquement lorsque la prop change
   const normalizedSize = computed(() => props.size.trim().toLowerCase())
   ```

   ```js
   export default {
     props: ['size'],
     computed: {
       // propriété calculée qui se met à jour automatiquement lorsque la prop change
       normalizedSize() {
         return this.size.trim().toLowerCase()
       }
     }
   }
   ```

### Mutation de props de type objet et tableau {#mutating-object-array-props}

Lorsque des objets et des tableaux sont passés en tant que props, bien que le composant enfant ne puisse pas muter la liaison de la prop, il **pourra** muter les propriétés imbriquées de l'objet ou du tableau. En effet, en JavaScript, les objets et les tableaux sont passés par référence, et il est déraisonnablement coûteux pour Vue d'empêcher de telles mutations.

Le principal inconvénient de ces mutations est qu'elles permettent au composant enfant de modifier l'état parent d'une manière qui n'est pas évidente vis-à-vis du composant parent, ce qui rend potentiellement plus difficile la compréhension du flux de données et sa maintenabilité dans le futur. En tant que bonne pratique, vous devez éviter de telles mutations à moins que le parent et l'enfant ne soient étroitement couplés par conception. Dans la plupart des cas, l'enfant doit [émettre un événement](/guide/components/events) pour laisser le parent effectuer la mutation.

## Validation de prop {#prop-validation}

Les composants peuvent spécifier des exigences pour leurs props, tels que la déclaration des types que vous avez déjà vus. Si une exigence n'est pas remplie, Vue vous avertira dans la console JavaScript du navigateur. Ceci est particulièrement utile lors du développement d'un composant destiné à être utilisé par d'autres.

Pour spécifier les validations de props, vous pouvez fournir un objet avec des exigences de validation à la macro `defineProps()`l'option `props`, au lieu d'un tableau de chaînes de caractères. Par exemple :

```js
defineProps({
  // Contrôle de type de base
  //  (les valeurs `null` et `undefined` autoriseront tous les types)
  propA: Number,
  // Plusieurs types possibles
  propB: [String, Number],
  // Chaîne de caractères requise
  propC: {
    type: String,
    required: true
  },
  // Obligatoire, mais chaîne de caractères nulle
  propD: {
    type: [String, null],
    required: true
  },
  // Nombre avec une valeur par défaut
  propE: {
    type: Number,
    default: 100
  },
  // Objet avec une valeur par défaut
  propF: {
    type: Object,
    // Les valeurs par défaut d'un objet ou d'un tableau doivent être renvoyées à partir
    // d'une fonction factory. La fonction reçoit les props bruts
    // reçus par le composant en tant qu'argument.
    default(rawProps) {
      return { message: 'hello' }
    }
  },
  // Fonction de validation personnalisée
  // Toutes les props passées dans le 2nd argument depuis la 3.4
  propG: {
    validator(value, props) {
      // La valeur doit correspondre à l'une de ces chaînes de caractères
      return ['success', 'warning', 'danger'].includes(value)
    }
  },
  // Fonction avec une valeur par défaut
  propH: {
    type: Function,
    // Contrairement aux valeurs par défaut d'un objet ou d'un tableau, il ne s'agit pas d'une fonction
    // factory - il s'agit d'une fonction servant de valeur par défaut
    default() {
      return 'Default function'
    }
  }
})
```

:::tip
Le code à l'intérieur de l'argument `defineProps()` **ne peut pas accéder aux autres variables déclarées dans `<script setup>`**, car l'expression entière est déplacée vers une portée de fonction externe lors de la compilation.
:::

```js
export default {
  props: {
    // Contrôle de type de base
    //  (les valeurs`null` et `undefined` autoriseront tous les types)
    propA: Number,
    // Plusieurs types possibles
    propB: [String, Number],
    // Chaîne de caractères requise
    propC: {
      type: String,
      required: true
    },
    // Obligatoire, mais chaîne de caractères nulle
    propD: {
      type: [String, null],
      required: true
    },
    // Nombre avec une valeur par défaut
    propE: {
      type: Number,
      default: 100
    },
    // Objet avec une valeur par défaut
    propF: {
      type: Object,
      // Les valeurs par défaut d'un objet ou d'un tableau doivent être renvoyées à partir
      // d'une fonction factory. La fonction reçoit les props bruts
      // reçus par le composant en tant qu'argument.
      default(rawProps) {
        return { message: 'hello' }
      }
    },
    // Fonction de validation personnalisée
    // Toutes les props passées dans le 2nd argument depuis la 3.4
    propG: {
      validator(value, props) {
        // The value must match one of these strings
        return ['success', 'warning', 'danger'].includes(value)
      }
    },
    // Fonction avec une valeur par défaut
    propH: {
      type: Function,
      // Contrairement aux valeurs par défaut d'un objet ou d'un tableau, il ne s'agit pas d'une fonction
      // factory - il s'agit d'une fonction servant de valeur par défaut
      default() {
        return 'Default function'
      }
    }
  }
}
```

Détails supplémentaires :

* Toutes les props sont facultatives par défaut, sauf si `required: true` est spécifié.

* Une prop facultative absente autre que `Boolean` aura la valeur `undefined`.

* Les props `Boolean` absentes seront converties en `false`. Vous pouvez changer cela en définissant une valeur par défaut, c'est-à-dire: `default: undefined` pour se comporter comme une prop non booléen.

* Si une valeur `default` est spécifiée, elle sera utilisée si la valeur prop résolue est `undefined` - cela inclut à la fois lorsque la prop est absente ou lorsqu'une valeur `undefined` explicite est passée.

Lorsque la validation de prop échoue, Vue produira un avertissement dans la console (si vous utilisez la version de développement).

Si vous utilisez des [déclarations de props basées sur les types](/api/sfc-script-setup#type-only-props-emit-declarations) , Vue fera de son mieux pour compiler les annotations de type dans des déclarations de props équivalentes lors de l'exécution. Par exemple, `defineProps<{ msg: string }>` sera compilé en `{ msg: { type: String, required: true }}`.

::: tip Note
Notez que les props sont validés **avant** qu'une instance de composant soit créée, de sorte que les propriétés d'instance (par exemple, `data`, `computed`, etc.) ne seront pas disponibles dans les fonctions `default` ou `validator`.
:::

### Vérifications de type à l'exécution {#runtime-type-checks}

Le `type` peut être l'un des constructeurs natifs suivants :

* `String`
* `Number`
* `Boolean`
* `Array`
* `Object`
* `Date`
* `Function`
* `Symbol`
* `Error`

De plus, `type` peut également être une classe personnalisée ou une fonction constructeur et l'assertion sera faite avec une vérification `instanceof`. Par exemple, étant donné la classe suivante :

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

Vous pouvez l'utiliser comme type de prop :

```js
defineProps({
  author: Person
})
```

```js
export default {
  props: {
    author: Person
  }
}
```

Vue utilisera `instanceof Person` pour valider si la valeur de la prop `author` est bien une instance de la classe `Person`.

### Type Nullable {#nullable-type}

Si le type est obligatoire mais nullable, vous pouvez utiliser la syntaxe des tableaux qui inclut `null` :

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

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

Notez que si `type` est juste `null` sans utiliser la syntaxe du tableau, il autorisera n'importe quel type.

## Conversion en booléen {#boolean-casting}

Les props avec le type `Boolean` ont des règles de conversion spéciales pour imiter le comportement des attributs booléens natifs. Admettons un composant `<MyComponent>` avec la déclaration suivante :

```js
defineProps({
  disabled: Boolean
})
```

```js
export default {
  props: {
    disabled: Boolean
  }
}
```

Le composant peut être utilisé comme ceci :

```vue-html
<!-- équivalent à passer :disabled="true" -->
<MyComponent disabled />

<!-- équivalent à passer :disabled="false" -->
<MyComponent />
```

Lorsqu'une prop est déclarée pour autoriser plusieurs types, les règles de conversion pour `Boolean` seront également appliquées. Cependant, il y a un avantage lorsque `String` et `Boolean` sont autorisés - la règle de casting sur Boolean ne s'applique que si Boolean apparaît avant String :

```js
// disabled sera transformé en true
defineProps({
  disabled: [Boolean, Number]
})

// disabled sera transformé en true
defineProps({
  disabled: [Boolean, String]
})

// disabled sera transformé en true
defineProps({
  disabled: [Number, Boolean]
})

// disabled sera analysé comme une chaîne vide (disabled="")
defineProps({
  disabled: [String, Boolean]
})
```

```js
// disabled sera transformé en true
export default {
  props: {
    disabled: [Boolean, Number]
  }
}

// disabled sera transformé en true
export default {
  props: {
    disabled: [Boolean, String]
  }
}

// disabled sera transformé en true
export default {
  props: {
    disabled: [Number, Boolean]
  }
}

// disabled sera analysé comme une chaîne vide (disabled="")
export default {
  props: {
    disabled: [String, Boolean]
  }
}
```

---

---
url: /guide/components/provide-inject.md
---
# Provide / Inject {#provide-inject}

> Cette page suppose que vous avez déjà lu les [principes fondamentaux des composants](/guide/essentials/component-basics). Lisez-les d'abord si vous débutez avec les composants.

## Passage de props en profondeur (Prop Drilling) {#prop-drilling}

Habituellement, lorsque nous devons transmettre des données du parent à un composant enfant, nous utilisons des [props](/guide/components/props). Cependant, imaginez le cas où nous avons un arbre de composants important, et qu'un composant profondément imbriqué aurait besoin d'accéder à des informations d'un de ses composants parents. Avec seulement des props, nous devrions passer la même prop sur toute la chaîne composants parents :

![prop drilling diagram](./images/prop-drilling.png)

Notez que bien que le composant `<Footer>` n'utilise pas du tout ces props, il doit malgré tout les déclarer et les transmettre uniquement afin que `<DeepChild>` puisse y accéder. S'il y a une chaîne de composants parents plus longue, encore plus de composants seront affectés par le problème. C'est ce qu'on appelle le "props drilling" et ce n'est certainement pas amusant à gérer.

Nous pouvons résoudre le "props drilling" avec `provide` et `inject`. Un composant parent peut servir de **fournisseur de dépendances** pour tous ses descendants. Tout composant enfant de l'arborescence, quelle que soit sa profondeur, peut **injecter** des dépendances fournies par des composants présent dans sa chaîne de composants parents.

![Provide/inject scheme](./images/provide-inject.png)

## Provide {#provide}

Pour fournir des données aux descendants d'un composant, utilisez la fonction [`provide()`](/api/composition-api-dependency-injection#provide) :

```vue
<script setup>
import { provide } from 'vue'

provide(/* clé */ 'message', /* valeur */ 'hello!')
</script>
```

Si vous n'utilisez pas `<script setup>`, assurez-vous que `provide()` est appelé de manière synchrone dans `setup()` :

```js
import { provide } from 'vue'

export default {
  setup() {
    provide(/* clé */ 'message', /* valeur */ 'hello!')
  }
}
```

La fonction `provide()` accepte deux arguments. Le premier argument est appelé la **clé d'injection**, qui peut être une chaîne de caractères ou un `Symbol`. La clé d'injection est utilisée par les composants descendants pour rechercher la valeur souhaitée à injecter. Un composant peut appeler `provide()` plusieurs fois avec différentes clés d'injection pour fournir différentes valeurs.

Le deuxième argument est la valeur fournie. La valeur peut être de n'importe quel type, y compris un état réactif tel que des refs :

```js
import { ref, provide } from 'vue'

const count = ref(0)
provide('key', count)
```

Fournir des valeurs réactives permet aux composants descendants qui les utilisent d'établir une connexion réactive au composant fournisseur.

Pour fournir des données aux descendants d'un composant, utilisez l'option [`provide`](/api/options-composition#provide) :

```js
export default {
  provide: {
    message: 'hello!'
  }
}
```

Pour chaque propriété de l'objet `provide`, la clé est utilisée par les composants enfants pour localiser la valeur correcte à injecter, tandis que la valeur est celle qui finit par être injectée.

Si nous devons fournir un état par instance, par exemple des données déclarées via `data()`, alors `provide` doit utiliser une valeur de type fonction :

```js{7-12}
export default {
  data() {
    return {
      message: 'hello!'
    }
  },
  provide() {
    // utiliser la syntaxe avec une fonction afin de pouvoir accéder à `this`
    return {
      message: this.message
    }
  }
}
```

Cependant, notez que cela **ne rend pas** l'injection réactive. Nous discuterons ci-dessous de la [manière de rendre les injections réactives](#working-with-reactivity).

## Provide au niveau de l'application {#app-level-provide}

En plus de fournir des données dans un composant, nous pouvons également fournir des données au niveau de l'application :

```js
import { createApp } from 'vue'

const app = createApp({})

app.provide(/* clé */ 'message', /* valeur */ 'hello!')
```

Les données fournies au niveau de l'application sont disponibles pour tous les composants rendus dans l'application. Ceci est particulièrement utile lors de l'écriture de [plugins](/guide/reusability/plugins), car les plugins ne seraient généralement pas en mesure de fournir des valeurs à l'aide de composants.

## Inject {#inject}

Pour injecter des données fournies par un composant parent, utilisez la fonction [`inject()`](/api/composition-api-dependency-injection#inject) :

```vue
<script setup>
import { inject } from 'vue'

const message = inject('message')
</script>
```

Si plusieurs parents fournissent des données avec la même clé, l'injection se résoudra à la valeur du parent le plus proche dans la chaîne des parents du composant.

Si la valeur fournie est une référence, elle sera injectée telle quelle et **ne sera pas** automatiquement exposée. Cela permet au composant injecteur de conserver la connexion de réactivité au composant fournisseur.

[Exemple complet provide + inject avec réactivité](https://play.vuejs.org/#eNqFUUFugzAQ/MrKF1IpxfeIVKp66Kk/8MWFDXYFtmUbpArx967BhURRU9/WOzO7MzuxV+fKcUB2YlWovXYRAsbBvQije2d9hAk8Xo7gvB11gzDDxdseCuIUG+ZN6a7JjZIvVRIlgDCcw+d3pmvTglz1okJ499I0C3qB1dJQT9YRooVaSdNiACWdQ5OICj2WwtTWhAg9hiBbhHNSOxQKu84WT8LkNQ9FBhTHXyg1K75aJHNUROxdJyNSBVBp44YI43NvG+zOgmWWYGt7dcipqPhGZEe2ef07wN3lltD+lWN6tNkV/37+rdKjK2rzhRTt7f3u41xhe37/xJZGAL2PLECXa9NKdD/a6QTTtGnP88LgiXJtYv4BaLHhvg==)

Encore une fois, si vous n'utilisez pas `<script setup>`, `inject()` ne doit être appelé que de manière synchrone dans `setup()` :

```js
import { inject } from 'vue'

export default {
  setup() {
    const message = inject('message')
    return { message }
  }
}
```

Pour injecter des données fournies par un composant parent, utilisez l'option [`inject`](/api/options-composition#inject) :

```js
export default {
  inject: ['message'],
  created() {
    console.log(this.message) // valeur injectée
  }
}
```

Les injections sont résolues **avant** l'état même du composant, vous pouvez donc accéder aux propriétés injectées dans `data()` :

```js
export default {
  inject: ['message'],
  data() {
    return {
      // données initiales basées sur la valeur injectée
      fullMessage: this.message
    }
  }
}
```

Si plusieurs parents fournissent des données avec la même clé, l'injection se résoudra à la valeur du parent le plus proche dans la chaîne des parents du composant.

[Exemple complet provide + inject](https://play.vuejs.org/#eNqNkcFqwzAQRH9l0EUthOhuRKH00FO/oO7B2JtERZaEvA4F43+vZCdOTAIJCImRdpi32kG8h7A99iQKobs6msBvpTNt8JHxcTC2wS76FnKrJpVLZelKR39TSUO7qreMoXRA7ZPPkeOuwHByj5v8EqI/moZeXudCIBL30Z0V0FLXVXsqIA9krU8R+XbMR9rS0mqhS4KpDbZiSgrQc5JKQqvlRWzEQnyvuc9YuWbd4eXq+TZn0IvzOeKr8FvsNcaK/R6Ocb9Uc4FvefpE+fMwP0wH8DU7wB77nIo6x6a2hvNEME5D0CpbrjnHf+8excI=)

### Alias d'injection {#injection-aliasing}

Si la syntaxe utilisée avec `inject` est sous la forme d'un tableau, les propriétés injectées sont exposées sur l'instance de composant à l'aide de la même clé. Dans l'exemple ci-dessus, la propriété a été fournie sous la clé `"message"` et injectée en tant que `this.message`. La clé locale est la même que la clé d'injection.

Si nous voulons injecter la propriété en utilisant une clé locale différente, nous devrions utiliser la syntaxe sous la forme d'un objet avec l'option `inject` :

```js
export default {
  inject: {
    /* clé locale */ localMessage: {
      from: /* clé d'injection */ 'message'
    }
  }
}
```

Ici, le composant localisera une propriété fournie avec la clé `"message"`, puis l'exposera en tant que `this.localMessage`.

### Valeurs par défaut lors de l'injection {#injection-default-values}

Par défaut, `inject` suppose que la clé injectée est fournie quelque part dans la chaîne de composants parents. Dans le cas où la clé n'est pas fournie, il y aura un message d'avertissement lors de l'exécution.

Si nous voulons faire fonctionner une propriété injectée avec des fournisseurs facultatifs, nous devons déclarer une valeur par défaut, de la même manière qu'avec les props :

```js
// `value` sera "default value"
// si aucune donnée correspondant à la clé "message" n'a été fournie
const value = inject('message', 'default value')
```

Dans certains cas, la valeur par défaut peut devoir être créée en appelant une fonction ou en instanciant une nouvelle classe. Pour éviter des calculs inutiles ou des effets de bord si la valeur facultative n'est pas utilisée, nous pouvons utiliser une fonction factory pour créer la valeur par défaut :

```js
const value = inject('key', () => new ExpensiveClass(), true)
```

Le troisième paramètre indique la valeur par défaut à traiter comme une fonction *factory*.

```js
export default {
  // la syntaxe utilisant un objet est requise
  // lors de la déclaration des valeurs par défaut pour les injections
  inject: {
    message: {
      from: 'message', // ceci est facultatif si vous utilisez la même clé pour l'injection
      default: 'default value'
    },
    user: {
      // utiliser une fonction factory pour les valeurs non primitives coûteuse
      // à créer, ou celles qui doivent être uniques par instance de composant.
      default: () => ({ name: 'John' })
    }
  }
}
```

## Injections réactives {#working-with-reactivity}

Lors de l'utilisation de valeurs de réactives avec provide / inject, **il est recommandé de conserver toutes les mutations d'un état réactif à l'intérieur du *fournisseur* dans la mesure du possible**. Cela garantit que l'état fourni et ses éventuelles mutations sont localisés dans le même composant, ce qui facilite sa maintenabilité à l'avenir.

Il peut arriver que nous ayons besoin de mettre à jour les données depuis un composant réalisant l'injection. Dans de tels cas, nous vous recommandons de fournir une fonction responsable de la mutation de l'état :

```vue{7-9,13}
<!-- à l'intérieur du composant fournisseur -->
<script setup>
import { provide, ref } from 'vue'

const location = ref('North Pole')

function updateLocation() {
  location.value = 'South Pole'
}

provide('location', {
  location,
  updateLocation
})
</script>
```

```vue{5}
<!-- dans le composant injecteur -->
<script setup>
import { inject } from 'vue'

const { location, updateLocation } = inject('location')
</script>

<template>
  <button @click="updateLocation">{{ location }}</button>
</template>
```

Enfin, vous pouvez encapsuler la valeur fournie avec [`readonly()`](/api/reactivity-core#readonly) si vous souhaitez vous assurer que les données transmises via `provide` ne puissent pas être mutées par le composant réalisant l'injection.

```vue
<script setup>
import { ref, provide, readonly } from 'vue'

const count = ref(0)
provide('read-only-count', readonly(count))
</script>
```

Afin de rendre les injections liées de manière réactive au fournisseur, nous devons fournir une propriété calculée à l'aide de la fonction [computed()](/api/reactivity-core#computed) :

```js{12}
import { computed } from 'vue'

export default {
  data() {
    return {
      message: 'hello!'
    }
  },
  provide() {
    return {
      // fournir explicitement une propriété calculée
      message: computed(() => this.message)
    }
  }
}
```

[Exemple complet provide + inject avec réactivité](https://play.vuejs.org/#eNqNUctqwzAQ/JVFFyeQxnfjBEoPPfULqh6EtYlV9EKWTcH43ytZtmPTQA0CsdqZ2dlRT16tPXctkoKUTeWE9VeqhbLGeXirheRwc0ZBds7HKkKzBdBDZZRtPXIYJlzqU40/I4LjjbUyIKmGEWw0at8UgZrUh1PscObZ4ZhQAA596/RcAShsGnbHArIapTRBP74O8Up060wnOO5QmP0eAvZyBV+L5jw1j2tZqsMp8yWRUHhUVjKPoQIohQ460L0ow1FeKJlEKEnttFweijJfiORElhCf5f3umObb0B9PU/I7kk17PJj7FloN/2t7a2Pj/Zkdob+x8gV8ZlMs2de/8+14AXwkBngD9zgVqjg2rNXPvwjD+EdlHilrn8MvtvD1+Q==)

La fonction `computed()` est généralement utilisée dans les composants utilisant la Composition API, mais peut également être utilisée pour compléter certains cas d'usage avec l'Options API. Vous pouvez en savoir plus sur son utilisation en lisant [les fondamentaux de la réactivité](/guide/essentials/reactivity-fundamentals) et [les propriétés calculées](/guide/essentials/computed) avec la préférence d'API définie sur Composition API.

## Injection avec des Symbols en tant que clés {#working-with-symbol-keys}

Jusqu'à présent, nous avons utilisé dans les exemples des clés d'injection qui étaient des chaînes de caractères. Si vous travaillez dans une application de taille importante avec de nombreux fournisseurs de dépendances, ou si vous créez des composants qui seront utilisés par d'autres développeurs, il est préférable d'utiliser des clés d'injection utilisant des [Symbols](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Symbol) pour éviter les collisions potentielles.

Il est recommandé d'exporter les Symbols dans un fichier dédié :

```js [keys.js]
export const myInjectionKey = Symbol()
```

```js
// dans le composant fournisseur
import { provide } from 'vue'
import { myInjectionKey } from './keys.js'

provide(myInjectionKey, {
  /* données à fournir */
})
```

```js
// dans le composant injecteur
import { inject } from 'vue'
import { myInjectionKey } from './keys.js'

const injected = inject(myInjectionKey)
```

Voir aussi : [Définir le type des données avec Provide / Inject](/guide/typescript/composition-api#typing-provide-inject)&#x20;

```js
// dans le composant fournisseur
import { myInjectionKey } from './keys.js'

export default {
  provide() {
    return {
      [myInjectionKey]: {
        /* données à fournir */
      }
    }
  }
}
```

```js
// dans le composant injecteur
import { myInjectionKey } from './keys.js'

export default {
  inject: {
    injected: { from: myInjectionKey }
  }
}
```

---

---
url: /guide/extras/reactivity-transform.md
---
# Reactivity Transform {#reactivity-transform}

:::danger Fonctionnalité expérimentale dépréciée
Reactivity Transform était une fonctionnalité expérimentale, et a été supprimée dans la dernière version 3.4. Consultez [le raisonnement ici](https://github.com/vuejs/rfcs/discussions/369#discussioncomment-5059028).

Si vous voulez continuer de l'utiliser, cela est désormais possible en utilisant le plugin [Vue Macros](https://vue-macros.sxzz.moe/features/reactivity-transform.html).
:::

:::tip Spécifique à la Composition API
Reactivity Transform est une fonctionnalité spécifique à la Composition API et nécessite un outil de build.
:::

## Refs vs. variables réactives {#refs-vs-reactive-variables}

Depuis l'introduction de la Composition API, l'une des principales questions non résolues est l'utilisation des refs par rapport aux objets réactifs. Il est facile de perdre la réactivité lors de la déstructuration des objets réactifs, mais il peut être fastidieux d'utiliser `.value` partout lors de l'utilisation des refs. De plus, `.value` est facilement oubliable si l'on n'utilise pas un système de typage.

[Reactivity Transform de Vue](https://github.com/vuejs/core/tree/main/packages/reactivity-transform) consiste en une transformation réalisée au moment de la compilation, nous permettant d'écrire du code comme celui-ci :

```vue
<script setup>
let count = $ref(0)

console.log(count)

function increment() {
  count++
}
</script>

<template>
  <button @click="increment">{{ count }}</button>
</template>
```

La méthode `$ref()` est ici une **macro de compilation** : ce n'est pas une méthode réelle qui sera appelée à l'exécution. Au lieu de cela, le compilateur Vue l'utilise comme une indication pour traiter la variable `count` qui en résulte comme une **variable réactive**.

Les variables réactives peuvent être accédées et réassignées comme des variables normales, mais ces opérations sont compilées en des refs avec `.value`. Par exemple, la partie `<script>` du composant ci-dessus est compilée en :

```js{5,8}
import { ref } from 'vue'

let count = ref(0)

console.log(count.value)

function increment() {
  count.value++
}
```

Chaque API de réactivité qui renvoie des refs aura un équivalent en macro préfixé `$`. Ces API incluent :

* [`ref`](/api/reactivity-core#ref) -> `$ref`
* [`computed`](/api/reactivity-core#computed) -> `$computed`
* [`shallowRef`](/api/reactivity-advanced#shallowref) -> `$shallowRef`
* [`customRef`](/api/reactivity-advanced#customref) -> `$customRef`
* [`toRef`](/api/reactivity-utilities#toref) -> `$toRef`

Ces macros sont disponibles globalement et n'ont pas besoin d'être importées lorsque Reactivity Transform est activée, mais vous pouvez éventuellement les importer depuis `vue/macros` si vous voulez être plus explicite :

```js
import { $ref } from 'vue/macros'

let count = $ref(0)
```

## Déstructuration avec `$()` {#destructuring-with}

Il est courant pour une fonction de composition de retourner un objet de refs, et d'utiliser la déstructuration pour récupérer ces même refs. Pour ce faire, Reactivity Transform fournit la macro **`$()`** :

```js
import { useMouse } from '@vueuse/core'

const { x, y } = $(useMouse())

console.log(x, y)
```

Compilé en :

```js
import { toRef } from 'vue'
import { useMouse } from '@vueuse/core'

const __temp = useMouse(),
  x = toRef(__temp, 'x'),
  y = toRef(__temp, 'y')

console.log(x.value, y.value)
```

Notez que si `x` est déjà une ref, `toRef(__temp, 'x')` le retournera simplement tel quel et aucune ref supplémentaire ne sera créée. Si une valeur déstructurée n'est pas une ref (par exemple une fonction), cela fonctionnera quand même - la valeur sera enveloppée dans une ref afin que le reste du code fonctionne comme prévu.

La déstructuration avec `$()` fonctionne à la fois sur les objets réactifs **et** les objets simples contenant des refs.

## Convertir les refs existantes en variables réactives avec `$()` {#convert-existing-refs-to-reactive-variables-with}

Dans certains cas, nous pouvons avoir des fonctions enveloppées qui renvoient également des refs. Cependant, le compilateur Vue ne sera pas capable de savoir à l'avance qu'une fonction va retourner une ref. Dans ce cas, la macro `$()` peut également être utilisée pour convertir les refs existantes en variables réactives :

```js
function myCreateRef() {
  return ref(0)
}

let count = $(myCreateRef())
```

## Déstructuration de props réactives {#reactive-props-destructure}

Il y a deux problèmes avec l'utilisation actuelle de `defineProps()` dans `<script setup>` :

1. Comme pour `.value`, vous devez toujours accéder aux props via `props.x` afin de conserver la réactivité. Cela signifie que vous ne pouvez pas déstructurer `defineProps` car les variables déstructurées résultantes ne sont pas réactives et ne seront pas mises à jour.

2. Lorsque l'on utilise la [déclaration de type pour les props](/api/sfc-script-setup#type-only-props-emit-declarations), il n'y a pas de moyen facile de déclarer des valeurs par défaut pour les props. Nous avons introduit l'API `withDefaults()` dans ce but précis, mais elle reste toujours difficile à utiliser.

Nous pouvons résoudre ces problèmes en appliquant une transformation au moment de la compilation lorsque `defineProps` est utilisée avec la déstructuration, de la même manière que ce que nous avons vu précédemment avec `$()` :

```html
<script setup lang="ts">
  interface Props {
    msg: string
    count?: number
    foo?: string
  }

  const {
    msg,
    // une valeur par défaut fonctionne
    count = 1,
    // l'utilisation d'alias locaux fonctionne également
    // ici nous utilisons l'alias `bar` pour `props.foo`
    foo: bar
  } = defineProps<Props>()

  watchEffect(() => {
    // va loguer chaque fois que les props changent
    console.log(msg, count, bar)
  })
</script>
```

Ce qui précède sera compilé en un équivalent de la déclaration d'exécution suivante :

```js
export default {
  props: {
    msg: { type: String, required: true },
    count: { type: Number, default: 1 },
    foo: String
  },
  setup(props) {
    watchEffect(() => {
      console.log(props.msg, props.count, props.foo)
    })
  }
}
```

## Conserver la réactivité au-delà des frontières des fonctions {#retaining-reactivity-across-function-boundaries}

Bien que les variables réactives nous évitent de devoir utiliser `.value` partout, cela crée un problème de "perte de réactivité" lorsque nous passons des variables réactives à travers les frontières des fonctions. Cela peut se produire dans deux cas :

### Passage dans une fonction comme argument {#passing-into-function-as-argument}

Prenons une fonction qui attend une ref comme argument, par exemple :

```ts
function trackChange(x: Ref<number>) {
  watch(x, (x) => {
    console.log('x changed!')
  })
}

let count = $ref(0)
trackChange(count) // ne fonctionne pas !
```

Le cas ci-dessus ne fonctionnera pas comme prévu car il sera compilé en :

```ts
let count = ref(0)
trackChange(count.value)
```

Ici, `count.value` est passée comme un nombre, alors que `trackChange` attend une ref réelle. Cela peut être corrigé en enveloppant `count` avec `$$()` avant de le passer :

```diff
let count = $ref(0)
- trackChange(count)
+ trackChange($$(count))
```

Se compile comme suit :

```js
import { ref } from 'vue'

let count = ref(0)
trackChange(count)
```

Comme nous pouvons le voir, `$$()` est une macro qui sert d'indice **échappatoire** : les variables réactives contenues dans `$$()` ne se verront pas ajouter `.value`.

### Retour à l'intérieur du scope d'une fonction {#returning-inside-function-scope}

La réactivité peut également être perdue si les variables réactives sont utilisées directement dans une expression retournée :

```ts
function useMouse() {
  let x = $ref(0)
  let y = $ref(0)

  // écout les mouvements de la souris...

  // ne fonctionne pas !
  return {
    x,
    y
  }
}
```

L'instruction de retour ci-dessus se compile comme suit :

```ts
return {
  x: x.value,
  y: y.value
}
```

Afin de conserver la réactivité, nous devrions renvoyer les refs réelles, et non la valeur actuelle au moment du retour.

Encore une fois, nous pouvons utiliser `$$()` pour résoudre ce problème. Dans ce cas, `$$()` peut être utilisée directement sur l'objet retourné - toute référence à des variables réactives à l'intérieur de l'appel `$$()` conservera la référence à leurs refs sous-jacentes :

```ts
function useMouse() {
  let x = $ref(0)
  let y = $ref(0)

  // écoute les mouvements de la souris...

  // corrigé
  return $$({
    x,
    y
  })
}
```

### Utiliser `$$()` sur des props déstructurées {#using-on-destructured-props}

`$$()` fonctionne sur les props déstructurées puisqu'elles sont elles aussi des variables réactives. Le compilateur le convertira avec `toRef` pour plus d'efficacité :

```ts
const { count } = defineProps<{ count: number }>()

passAsRef($$(count))
```

Se compile comme suit :

```js
setup(props) {
  const __props_count = toRef(props, 'count')
  passAsRef(__props_count)
}
```

## Intégration avec TypeScript  {#typescript-integration}

Vue fournit des typages pour ces macros (disponibles globalement) et tous les types fonctionneront comme prévu. Il n'y a aucune incompatibilité avec la sémantique TypeScript standard, et donc la syntaxe fonctionnera avec tous les outils existants.

Cela signifie également que les macros peuvent fonctionner dans n'importe quel fichier où les JS / TS valides sont autorisés - pas seulement dans les SFC de Vue.

Puisque les macros sont disponibles globalement, leurs types doivent être explicitement référencés (par exemple dans un fichier `env.d.ts`) :

```ts
/// <reference types="vue/macros-global" />
```

Si vous importez explicitement les macros à partir de `vue/macros`, le type fonctionnera sans déclarer les globaux.

## Activation explicite {#explicit-opt-in}

:::warning
Ce qui suit ne s'applique qu'aux versions 3.3 et inférieures de Vue. La prise en charge par le noyau a été supprimée depuis la version 3.4, et la version 5 et plus de `@vitejs/plugin-vue`. Si vous voulez continuer à utiliser la transformation, veuillez migrer vers [Vue Macros](https://vue-macros.sxzz.moe/features/reactivity-transform.html) à la place.
:::

### Vite {#vite}

* Nécessite `@vitejs/plugin-vue@>=2.0.0`.
* S'applique aux SFC et aux fichiers js(x)/ts(x). Une vérification rapide de l'utilisation est effectuée sur les fichiers avant d'appliquer la transformation, il ne devrait donc pas y avoir de perte de performance pour les fichiers n'utilisant pas les macros.
* Notez que `reactivityTransform` est désormais une option au niveau de la racine du plugin au lieu d'être imbriquée comme `script.refSugar`, puisqu'elle n'affecte pas seulement les SFC.

```js [vite.config.js]
export default {
  plugins: [
    vue({
      reactivityTransform: true
    })
  ]
}
```

### `vue-cli` {#vue-cli}

* N'affecte actuellement que les SFC
* Nécessite `vue-loader@>=17.0.0`.

```js [vue.config.js]
module.exports = {
  chainWebpack: (config) => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap((options) => {
        return {
          ...options,
          reactivityTransform: true
        }
      })
  }
}
```

### `webpack` simple + `vue-loader` {#plain-webpack-vue-loader}

* N'affecte actuellement que les SFC
* Nécessite `vue-loader@>=17.0.0`.

```js [webpack.config.js]
module.exports = {
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader',
        options: {
          reactivityTransform: true
        }
      }
    ]
  }
}
```

---

---
url: /error-reference.md
---
# Référence des codes d'erreur en production {#error-reference}

## Erreurs d'exécution {#runtime-errors}

Dans les versions de production, le troisième argument transmis aux API de gestion des erreurs suivantes sera un code court au lieu de la chaîne d'information complète :

* [`app.config.errorHandler`](/api/application#app-config-errorhandler)
* [`onErrorCaptured`](/api/composition-api-lifecycle#onerrorcaptured) (Composition API)
* [`errorCaptured`](/api/options-lifecycle#errorcaptured) (Options API)

Le tableau suivant établit une correspondance entre les codes et leurs chaînes d'information complètes d'origine.

## Erreurs de compilation {#compiler-errors}

Le tableau suivant fournit une correspondance entre les codes d'erreur du compilateur en production et leurs messages d'origine.

---

---
url: /style-guide/rules-essential.md
---
# Règles de priorité A : Essentielles {#priority-a-rules-essential}

Ces règles aident à prévenir les erreurs, donc apprenez les et tenez-y vous coûte que coûte. Il peut y avoir des exceptions, mais elles sont rares et devraient être faites par ceux ayant une expertise à la fois dans JavaScript et dans Vue.

## Utilisez des noms de composants avec plusieurs mots {#use-multi-word-component-names}

Les noms de composants créés par l'utilisateur devraient toujours être composés de plusieurs mots, à l'exception du composant racine `App`. Cela [évite les conflits](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) avec les éléments HTML existants et à venir, puisqu'ils sont tous composés d'un seul mot.

```vue-html
<!-- dans les templates pré-compilés -->
<Item />

<!-- dans les templates à l'intérieur du DOM -->
<item></item>
```

```vue-html
<!-- dans les templates pré-compilés -->
<TodoItem />

<!-- dans les templates à l'intérieur du DOM -->
<todo-item></todo-item>
```

## Utilisez des définitions de prop détaillées {#use-detailed-prop-definitions}

Dans le code source, les définitions de prop devraient toujours être le plus détaillées possible, en spécifiant au moins le ou les types.

::: details Explications détaillées
[Les définitions de prop](/guide/components/props#prop-validation) détaillées présentent deux avantages :

* Elles documentent l'API du composant, de manière à ce qu'il soit facile de voir comment le composant doit être utilisé.
* Pendant le développement, Vue vous avertira si jamais un composant se voit fournir des props au mauvais format, ce qui vous aidera à régler les potentielles sources d'erreurs.
  :::

```js
// OK seulement lorsque vous prototyper
props: ['status']
```

```js
props: {
  status: String
}
```

```js
// Encore mieux !
props: {
  status: {
    type: String,
    required: true,

    validator: value => {
      return [
        'syncing',
        'synced',
        'version-conflict',
        'error'
      ].includes(value)
    }
  }
}
```

```js
// OK seulement lorsque vous prototyper
const props = defineProps(['status'])
```

```js
const props = defineProps({
  status: String
})
```

```js
// Encore mieux !

const props = defineProps({
  status: {
    type: String,
    required: true,

    validator: (value) => {
      return ['syncing', 'synced', 'version-conflict', 'error'].includes(
        value
      )
    }
  }
})
```

## Utilisez `v-for` avec une clé {#use-keyed-v-for}

`key` avec `v-for` est *toujours* requis sur les composants, afin de maintenir l'état interne du composant à travers le sous-arbre. Cependant même pour les éléments, une bonne pratique est de maintenir un comportement prédictible, telle que [la persistance de l'objet](https://bost.ocks.org/mike/constancy/) dans les animations.

::: details Explications détaillées
Imaginons que vous ayez une liste de todos :

```js
data() {
  return {
    todos: [
      {
        id: 1,
        text: 'Learn to use v-for'
      },
      {
        id: 2,
        text: 'Learn to use key'
      }
    ]
  }
}
```

```js
const todos = ref([
  {
    id: 1,
    text: 'Learn to use v-for'
  },
  {
    id: 2,
    text: 'Learn to use key'
  }
])
```

Puis vous les triez par ordre alphabétique. Lors de la mise à jour du DOM, Vue va optimiser le rendu de manière à réaliser les mutations du DOM les moins coûteuses. Cela peut signifier supprimer la première todo, puis la remettre à la fin de la liste.

Le problème est que, dans certains cas il peut être important de ne pas supprimer d'éléments qui vont rester dans le DOM. Par exemple, vous pouvez vouloir utiliser `<transition-group>` pour animer le tri de la liste, ou maintenir le focus si l'élément rendu est un `<input>`. Dans ces cas, ajouter une clé unique pour chaque item (par exemple `:key="todo.id"`) précisera de manière plus prédictible à Vue comment se comporter.

De notre expérience, il est préférable de *toujours* ajouter une clé unique, de sorte que vous et votre équipe n'ayez jamais à vous soucier de ces rares cas. Dans les scenarios rares et critiques, d'un point de vue des performances, où la persistance de l'objet n'est pas nécessaire, vous pouvez faire une exception.
:::

```vue-html
<ul>
  <li v-for="todo in todos">
    {{ todo.text }}
  </li>
</ul>
```

```vue-html
<ul>
  <li
    v-for="todo in todos"
    :key="todo.id"
  >
    {{ todo.text }}
  </li>
</ul>
```

## Évitez les `v-if` avec les `v-for` {#avoid-v-if-with-v-for}

**N'utilisez jamais `v-if` et `v-for` sur le même élément.**

Il y a deux situations courantes où cela peut être tentant :

* Pour filtrer des items dans une liste (par exemple `v-for="user in users" v-if="user.isActive"`). Dans ces cas, remplacez `users` par une nouvelle propriété calculée qui vous retourne votre liste filtrée (par exemple `activeUsers`).

* Pour éviter le rendu d'une liste si elle doit être cachée (par exemple `v-for="user in users" v-if="shouldShowUsers"`). Dans ces cas, déplacez le `v-if` sur un élément conteneur (par exemple `ul`, `ol`).

::: details Explications détaillées
Lorsque Vue traite les directives, `v-if` a la priorité sur `v-for`, donc ce template :

```vue-html
<ul>
  <li
    v-for="user in users"
    v-if="user.isActive"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

Va produire une erreur, car la directive `v-if` sera d'abord évaluée et la variable d'itération `user` n'existe pas à ce moment précis.

Cela peut être résolu en itérant sur une propriété calculée à la place, de cette façon :

```js
computed: {
  activeUsers() {
    return this.users.filter(user => user.isActive)
  }
}
```

```js
const activeUsers = computed(() => {
  return users.filter((user) => user.isActive)
})
```

```vue-html
<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

Ou encore, nous pouvons utiliser une balise `<template>` avec `v-for` pour envelopper l'élément `<li>` :

```vue-html
<ul>
  <template v-for="user in users" :key="user.id">
    <li v-if="user.isActive">
      {{ user.name }}
    </li>
  </template>
</ul>
```

:::

```vue-html
<ul>
  <li
    v-for="user in users"
    v-if="user.isActive"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

```vue-html
<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>
```

```vue-html
<ul>
  <template v-for="user in users" :key="user.id">
    <li v-if="user.isActive">
      {{ user.name }}
    </li>
  </template>
</ul>
```

## Utilisez du style avec une portée limitée au composant {#use-component-scoped-styling}

Pour les applications, les styles du composant `App` et des composants de mise en page peuvent être globaux, mais tous les autres styles des composants devraient avoir une portée limitée.

Cela n'est pertinent que pour les [composants monofichiers](/guide/scaling-up/sfc). Cela ne nécessite *pas* que l'[attribut `scoped`](/api/sfc-css-features#scoped-css) soit utilisé. La limitation de la portée peut se faire via des [modules CSS](/api/sfc-css-features#css-modules), une stratégie basée sur les classes telle que [BEM](https://getbem.com/), ou tout autre librairie/convention.

**Toutefois, pour les librairies de composants, il est préférable d'utiliser une stratégie basée sur les classes au lieu d'utiliser l'attribut `scoped`.**

Cela permet de remplacer les styles internes plus facilement, avec des noms de classe compréhensibles par des humains et qui ne sont pas trop spécifiques, mais ont tout de même qu'une faible probabilité d'être à l'origine d'un conflit.

::: details Explications détaillées
Si vous développez un projet conséquent, travaillez avec d'autres développeurs, or incluez parfois du HTML/CSS tiers (par exemple à partir d'Auth0), une gestion des portées cohérente assurera que vos styles ne s'appliquent qu'aux composants pour lesquels ils sont destinés.

Au-delà de l'attribut `scoped`, utiliser des noms de classe uniques permet de s'assurer que du CSS tiers ne s'applique pas à votre HTML. Par exemple, de nombreux projets utilise les noms de classe `button`, `btn`, ou `icon`, donc même si vous n'utilisez pas de stratégie comme BEM, ajouter un préfixe spécifique à votre application ou votre composant (par exemple `ButtonClose-icon`) peut fournir une certaine protection.
:::

```vue-html
<template>
  <button class="btn btn-close">×</button>
</template>

<style>
.btn-close {
  background-color: red;
}
</style>
```

```vue-html
<template>
  <button class="button button-close">×</button>
</template>

<!-- Using the `scoped` attribute -->
<style scoped>
.button {
  border: none;
  border-radius: 2px;
}

.button-close {
  background-color: red;
}
</style>
```

```vue-html
<template>
  <button :class="[$style.button, $style.buttonClose]">×</button>
</template>

<!-- En utilisant des modules CSS -->
<style module>
.button {
  border: none;
  border-radius: 2px;
}

.buttonClose {
  background-color: red;
}
</style>
```

```vue-html
<template>
  <button class="c-Button c-Button--close">×</button>
</template>

<!-- En utilisant la convention BEM -->
<style>
.c-Button {
  border: none;
  border-radius: 2px;
}

.c-Button--close {
  background-color: red;
}
</style>
```

---

---
url: /style-guide/rules-strongly-recommended.md
---
# Règles de priorité B : Fortement recommandées {#priority-b-rules-strongly-recommended}

Ces règles améliorent la lisibilité et/ou l'expérience des développeurs dans la plupart des projets. Votre code fonctionnera toujours si vous les enfreignez, mais les violations doivent être rares et bien justifiées.

## Fichiers de composants {#component-files}

**Chaque fois qu'un système de build est disponible pour concaténer des fichiers, chaque composant doit être dans son propre fichier.**

Cela vous aide à trouver plus rapidement un composant lorsque vous devez le modifier ou revoir comment l'utiliser.

```js
app.component('TodoList', {
  // ...
})

app.component('TodoItem', {
  // ...
})
```

```
components/
|- TodoList.js
|- TodoItem.js
```

```
components/
|- TodoList.vue
|- TodoItem.vue
```

## La casse des noms de composants {#single-file-component-filename-casing}

**Le nom des [composants monofichiers](/guide/scaling-up/sfc) doit toujours être soit en PascalCase soit en kebab-case.**

PascalCase fonctionne mieux avec l'auto-complétion dans les éditeurs de code, car elle est cohérente avec la façon dont nous référençons les composants en JS(X) et les templates, dans la mesure du possible. Cependant, le nom des fichiers à casse mixte peut parfois créer des problèmes sur les systèmes de fichiers insensibles à la casse, c'est pourquoi kebab-case est également parfaitement acceptable.

```
components/
|- mycomponent.vue
```

```
components/
|- myComponent.vue
```

```
components/
|- MyComponent.vue
```

```
components/
|- my-component.vue
```

## Nom des composants de base {#base-component-names}

**Les composants de base (a.k.a. présentation, muet, ou composant pure) qui appliquent un style et des conventions spécifiques à l'application doivent tous commencer par un préfixe spécifique, tel que `Base`, `App`, ou `V`.**

::: details Explications détaillées
Ces composants jettent les bases d'un style et d'un comportement cohérents dans votre application. Ils peuvent **seulement** contenir :

* Des éléments HTML,
* D'autres composants de base, et
* Un composant UI tiers.

Mais ils ne contiendront **jamais** des états globaux (par exemple, provenant de Pinia ou Vuex).

Leurs noms incluent souvent le nom d'un élément qu'ils encapsulent (par exemple, `BaseButton`, `BaseTable`), à moins qu'aucun élément n'existe pour leur usage spécifique (par exemple `BaseIcon`). Si vous créez des composants similaires pour un contexte plus spécifique, ils utiliseront presque toujours ces composants (par exemple, `BaseButton` peut être utilisé dans `ButtonSubmit`).

Quelques avantages de cette convention :

* Lorsqu'ils sont classés par ordre alphabétique dans les éditeurs, les composants de base de votre application sont tous répertoriés ensemble, ce qui facilite leur identification.

* Puisque les noms des composants doivent toujours être des mots composés, cette convention vous fait éviter d'avoir à choisir des préfixes arbitraires pour des composants simples (e.g. MyButton, VueButton).

* Étant donné que ces composants sont fréquemment utilisés, vous pouvez simplement les rendre globaux au lieu de les importer partout. Un préfixe rend cela possible avec Vite :

  ```js
  const modules = import.meta.glob('./src/**/Base*.vue', { eager: true })
  for (const path in modules) {
    const config = modules[path].default
    const name = config.name || path.match(/Base[A-Z]\w+/)[0]
    app.component(name, config)
  }
  ```

  :::

```
components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue
```

```
components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue
```

```
components/
|- AppButton.vue
|- AppTable.vue
|- AppIcon.vue
```

```
components/
|- VButton.vue
|- VTable.vue
|- VIcon.vue
```

## Noms des composants étroitement liés {#tightly-coupled-component-names}

**Les composants enfants étroitement couplés à leur parent doivent inclure le nom du composant parent comme préfixe.**

Si un composant n'a de sens que dans le contexte d'un seul composant parent, cette relation doit être évidente dans son nom. Étant donné que les éditeurs organisent généralement les fichiers par ordre alphabétique, cela permet également de conserver ces fichiers associés les uns à côté des autres.

::: details Explications détaillées
Vous pourriez être tenté de résoudre ce problème en imbriquant les composants enfants dans des répertoires nommés d'après leur parent. Par exemple :

```
components/
|- TodoList/
   |- Item/
      |- index.vue
      |- Button.vue
   |- index.vue
```

ou :

```
components/
|- TodoList/
   |- Item/
      |- Button.vue
   |- Item.vue
|- TodoList.vue
```

Ceci n'est pas recommandé, car pourrait entraîner :

* De nombreux fichiers avec des noms similaires, ce qui rend le changement rapide de fichier dans les éditeurs de code plus difficile.
* De nombreux sous-répertoires imbriqués, ce qui augmente le temps nécessaire pour parcourir les composants dans la barre latérale d'un éditeur.
  :::

```
components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue
```

```
components/
|- SearchSidebar.vue
|- NavigationForSearchSidebar.vue
```

```
components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue
```

```
components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue
```

## Ordre des mots dans les noms des composants {#order-of-words-in-component-names}

**Les noms des composants doivent commencer par les mots de plus haut niveau (souvent les plus généraux) et se terminer par des mots de modification descriptifs.**

::: details Explications détaillées
Vous vous demandez peut-être :

> "Pourquoi forcerions-nous les noms de composants à utiliser un langage moins naturel ?"

En anglais naturel, les adjectifs et autres descripteurs apparaissent généralement avant les noms, tandis que les exceptions nécessitent des mots connecteurs. Par exemple :

* Coffee *with* milk
* Soup *of the* day
* Visitor *to the* museum

Vous pouvez certainement inclure ces connecteurs dans les noms de composants si vous le souhaitez, mais l'ordre est toujours important.

Notez également que **ce qui est considéré comme "de plus haut niveau" sera contextuel à votre application**. Par exemple, imaginez une application avec un formulaire de recherche. Il peut inclure des composants comme celui-ci :

```
components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue
```

Comme vous le remarquerez peut-être, il est assez difficile de voir quels composants sont spécifiques à la recherche. Renommons maintenant les composants selon la règle :

```
components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputExcludeGlob.vue
|- SearchInputQuery.vue
|- SettingsCheckboxLaunchOnStartup.vue
|- SettingsCheckboxTerms.vue
```

Étant donné que les éditeurs organisent généralement les fichiers par ordre alphabétique, toutes les relations importantes entre les composants sont désormais évidentes en un coup d'œil.

Vous pourriez être tenté de résoudre ce problème différemment, en imbriquant tous les composants de recherche dans un répertoire "recherche", puis tous les composants de paramètres dans un répertoire "paramètres". Nous vous recommandons de ne considérer cette approche que dans les très grandes applications (par exemple, plus de 100 composants), pour les raisons suivantes :

* Il faut généralement plus de temps pour naviguer dans les sous-répertoires imbriqués que pour parcourir un seul répertoire `components`.
* Les conflits de nom (par exemple, plusieurs composants ButtonDelete.vue) rendent plus difficile la navigation rapide vers un composant spécifique dans un éditeur de code.
* Le refactoring devient plus difficile, car la recherche et le remplacement ne sont souvent pas suffisants pour mettre à jour les références relatives à un composant déplacé.
  :::

```
components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue
```

```
components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue
```

## Composants auto-fermants {#self-closing-components}

**Les composants sans contenu doivent être auto-fermants dans les [composants monofichiers](/guide/scaling-up/sfc), dans les templates, et dans [JSX](/guide/extras/render-function#jsx-tsx) - mais jamais dans les templates du DOM.**

Les composants auto-fermants n'indiquent pas seulement qu'ils n'ont pas de contenu, mais aussi qu'ils ne sont pas censés en avoir. C'est la différence entre une page blanche dans un livre et une autre intitulée «Cette page est laissée vierge intentionnellement». Votre code est également plus propre sans la balise de fermeture inutile.

Malheureusement, HTML n'autorise pas que les éléments personnalisés soient auto-fermants - seulement les [éléments officiels "void"](https://html.spec.whatwg.org/multipage/syntax.html#void-elements). C'est pourquoi la stratégie n'est possible que lorsque le compilateur de templates de Vue peut atteindre le template avant le DOM, puis servir le HTML conforme aux spécifications.

```vue-html
<!-- Dans les composants monofichiers, string templates, et JSX -->
<MyComponent></MyComponent>
```

```vue-html
<!-- Dans les templates du DOM -->
<my-component/>
```

```vue-html
<!-- Dans les composants monofichiers, string templates, et JSX -->
<MyComponent/>
```

```vue-html
<!-- Dans les templates du DOM -->
<my-component></my-component>
```

## La casse des noms de composants dans les templates {#component-name-casing-in-templates}

**Dans la plupart des projets, les noms de composants doivent toujours être en PascalCase dans les [composants monofichiers](/guide/scaling-up/sfc) et dans les string templates - mais en kebab-case dans les templates du DOM.**

PascalCase a quelques avantages par rapport au kebab-case :

* Les éditeurs peuvent compléter automatiquement les noms de composants dans les templates, car le PascalCase est également utilisé en JavaScript.
* `<MyComponent>` est visuellement plus distinct d'un élément HTML que `<my-component>`, car il y a deux différences de caractères (les deux majuscules), plutôt qu'une seule (un trait d'union).
* Si vous utilisez des éléments personnalisés non-Vue dans vos templates, tels qu'un Web Component, le PascalCase garantit que vos composants Vue restent clairement visibles.

Malheureusement, en raison de l'insensibilité à la casse de HTML, les templates du DOM doivent toujours utiliser le kebab-case.

Notez également que si vous êtes déjà beaucoup investi dans l'usage du kebab-case, la cohérence avec les conventions HTML et la possibilité d'utiliser la même casse dans tous vos projets peuvent être plus importantes que les avantages énumérés ci-dessus. Dans ces cas, **l'utilisation de kebab-case partout est également acceptable**.

```vue-html
<!-- Dans les composants monofichiers, string templates, et JSX -->
<mycomponent/>
```

```vue-html
<!-- Dans les composants monofichiers, string templates, et JSX -->
<myComponent/>
```

```vue-html
<!-- Dans les templates du DOM -->
<MyComponent></MyComponent>
```

```vue-html
<!-- Dans les composants monofichiers, string templates, et JSX -->
<MyComponent/>
```

```vue-html
<!-- Dans les templates du DOM -->
<my-component></my-component>
```

OU

```vue-html
<!-- Partout -->
<my-component></my-component>
```

## La casse des noms de composants en JS/JSX {#component-name-casing-in-js-jsx}

**Les noms de composants en JS/[JSX](/guide/extras/render-function#jsx-tsx) devraient toujours être en PascalCase, quoiqu'ils puissent être en kebab-case dans des strings pour des applications plus simples qui n'utilisent que l'enregistrement global des composants via `app.component`.**

::: details Explications détaillées
En JavaScript, le PascalCase est la convention pour les classes et les constructeurs de prototypes - essentiellement, tout ce qui peut avoir des instances distinctes. Les composants Vue ont également des instances, il est donc logique d'utiliser également PascalCase. Comme avantage supplémentaire, l'utilisation de PascalCase dans JSX (et les templates) permet aux gens qui lisent le code de distinguer plus facilement les composants et les éléments HTML.

Cependant, pour les applications qui utilisent **uniquement** les définitions de composants globales via `app.component`, nous recommandons plutôt le kebab-case. Les raisons sont :

* Il est rare que des composants globaux soient référencés en JavaScript, donc suivre une convention pour JavaScript a peu de sens.
* Ces applications incluent toujours de nombreux templates du DOM, où [kebab-case **doit** être utilisée](#component-name-casing-in-templates).
  :::

```js
app.component('myComponent', {
  // ...
})
```

```js
import myComponent from './MyComponent.vue'
```

```js
export default {
  name: 'myComponent'
  // ...
}
```

```js
export default {
  name: 'my-component'
  // ...
}
```

```js
app.component('MyComponent', {
  // ...
})
```

```js
app.component('my-component', {
  // ...
})
```

```js
import MyComponent from './MyComponent.vue'
```

```js
export default {
  name: 'MyComponent'
  // ...
}
```

## Nom des composants en mot entier {#full-word-component-names}

**Les noms des composants devraient être écrit avec des mots entiers plutôt ques des abréviations.**

L'auto-complétion dans les éditeurs de code fait gagner énormément de temps, tandis que la clarté qu'ils fournissent est inestimable. Les abréviations peu courantes, en particulier, doivent toujours être évitées.

```
components/
|- SdSettings.vue
|- UProfOpts.vue
```

```
components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue
```

## La casse des noms de prop {#prop-name-casing}

**Les noms de prop doivent toujours utiliser camelCase lors des déclarations. Lorsqu'elles sont utilisées dans des template du DOM, les props doivent être écrites en kebab-case. Les templates des composants monofichiers et [JSX](/guide/extras/render-function#jsx-tsx) peuvent utiliser des props en kebab-case ou en camelCase. La casse doit être cohérente - si vous choisissez d'utiliser des props en camelCase, assurez-vous de ne pas utiliser la casse kebab-case ailleurs dans votre application.**

```js
props: {
  'greeting-text': String
}
```

```js
const props = defineProps({
  'greeting-text': String
})
```

```vue-html
// for in-DOM templates
<welcome-message greetingText="hi"></welcome-message>
```

```js
props: {
  greetingText: String
}
```

```js
const props = defineProps({
  greetingText: String
})
```

```vue-html
// pour les SFC - assurez-vous que la casse est cohérente tout au long du projet
// vous pouvez utiliser l'une ou l'autre des conventions, mais nous vous déconseillons de mélanger deux styles de casse différents
<WelcomeMessage greeting-text="hi"/>
// ou
<WelcomeMessage greetingText="hi"/>
```

```vue-html
// pour les template du DOM
<welcome-message greeting-text="hi"></welcome-message>
```

## Éléments à attributs multiples {#multi-attribute-elements}

**Les éléments avec plusieurs attributs doivent s'étendre sur plusieurs lignes, avec un attribut par ligne.**

En JavaScript, étendre des objets avec plusieurs propriétés sur plusieurs lignes est largement considéré comme une bonne convention, car ils sont beaucoup plus faciles à lire. Les templates et [JSX](/guide/extras/render-function#jsx-tsx) méritent la même considération.

```vue-html
<img src="https://vuejs.org/images/logo.png" alt="Vue Logo">
```

```vue-html
<MyComponent foo="a" bar="b" baz="c"/>
```

```vue-html
<img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo"
>
```

```vue-html
<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>
```

## Expressions simples dans les templates {#simple-expressions-in-templates}

Les templates de composants ne doivent inclure que des expressions simples, avec des expressions plus complexes refactorisées en propriétés calculées ou en méthodes.

Les expressions complexes dans vos templates les rendent moins déclaratifs. Nous devons nous efforcer de décrire *ce qui* devrait apparaître, et non *comment* nous calculons cette valeur. Les propriétés calculées et les méthodes permettent également de réutiliser le code.

```vue-html
{{
  fullName.split(' ').map((word) => {
    return word[0].toUpperCase() + word.slice(1)
  }).join(' ')
}}
```

```vue-html
<!-- Dans un template -->
{{ normalizedFullName }}
```

```js
// L'expression complexe a été déplacée vers une propriété calculée
computed: {
  normalizedFullName() {
    return this.fullName.split(' ')
      .map(word => word[0].toUpperCase() + word.slice(1))
      .join(' ')
  }
}
```

```js
// L'expression complexe a été déplacée vers une propriété calculée
const normalizedFullName = computed(() =>
  fullName.value
    .split(' ')
    .map((word) => word[0].toUpperCase() + word.slice(1))
    .join(' ')
)
```

## Propriétés calculées simples {#simple-computed-properties}

**Les propriétés calculées complexes doivent être divisées en propriétés plus simples.**

::: details Explications détaillées
Les propriétés calculées plus simples et bien nommées sont :

* **Plus faciles à tester**

  Lorsque chaque propriété calculée ne contient qu'une expression très simple, avec très peu de dépendances, il est beaucoup plus facile d'écrire des tests qui vérifient leur bon fonctionnement.

* **Plus faciles à lire**

  Simplifier les propriétés calculées vous oblige à donner à chaque valeur un nom descriptif, même si elle n'est pas réutilisée. Cela permet aux autres développeurs (et à vous-même) de se concentrer beaucoup plus facilement sur le code qui leur tient à cœur et de comprendre ce qui se passe.

* **Plus adaptables à l'évolution des besoins**

  Toute valeur pouvant être nommée peut être utile pour la vue. Par exemple, nous pourrions décider d'afficher un message indiquant à l'utilisateur combien d'argent il a économisé. Nous pourrions également décider de calculer la taxe de vente, mais peut-être l'afficher séparément, plutôt que dans le cadre du prix final.

  Les propriétés calculées simples et ciblées font réduire le nombre d'hypothèses sur la façon dont les informations seront utilisées, elles nécessitent donc moins de refactoring à mesure que les exigences changent.
  :::

```js
computed: {
  price() {
    const basePrice = this.manufactureCost / (1 - this.profitMargin)
    return (
      basePrice -
      basePrice * (this.discountPercent || 0)
    )
  }
}
```

```js
const price = computed(() => {
  const basePrice = manufactureCost.value / (1 - profitMargin.value)
  return basePrice - basePrice * (discountPercent.value || 0)
})
```

```js
computed: {
  basePrice() {
    return this.manufactureCost / (1 - this.profitMargin)
  },

  discount() {
    return this.basePrice * (this.discountPercent || 0)
  },

  finalPrice() {
    return this.basePrice - this.discount
  }
}
```

```js
const basePrice = computed(
  () => manufactureCost.value / (1 - profitMargin.value)
)

const discount = computed(
  () => basePrice.value * (discountPercent.value || 0)
)

const finalPrice = computed(() => basePrice.value - discount.value)
```

## Les valeurs des attributs entres guillemets {#quoted-attribute-values}

**Les valeurs des attributs HTML non-vide doivent toujours être entre des guillemets (simple (' ') ou double (" "), celui qui n'est pas utilisé dans votre JS).**

Bien que les valeurs d'attribut sans espace ne soient pas obligées d'avoir des guillemets en HTML, cette pratique conduit souvent à *éviter* les espaces, ce qui rend les valeurs d'attribut moins lisibles.

```vue-html
<input type=text>
```

```vue-html
<AppSidebar :style={width:sidebarWidth+'px'}>
```

```vue-html
<input type="text">
```

```vue-html
<AppSidebar :style="{ width: sidebarWidth + 'px' }">
```

## Les raccourcis de directives {#directive-shorthands}

**Les raccourcis de directives (`:` pour `v-bind:`, `@` pour `v-on:` et `#` pour `v-slot`) doivent toujours être utilisés ou ne jamais l'être.**

```vue-html
<input
  v-bind:value="newTodoText"
  :placeholder="newTodoInstructions"
>
```

```vue-html
<input
  v-on:input="onInput"
  @focus="onFocus"
>
```

```vue-html
<template v-slot:header>
  <h1>Ceci est le titre de la page</h1>
</template>

<template #footer>
  <p>Ici quelques infos contacts</p>
</template>
```

```vue-html
<input
  :value="newTodoText"
  :placeholder="newTodoInstructions"
>
```

```vue-html
<input
  v-bind:value="newTodoText"
  v-bind:placeholder="newTodoInstructions"
>
```

```vue-html
<input
  @input="onInput"
  @focus="onFocus"
>
```

```vue-html
<input
  v-on:input="onInput"
  v-on:focus="onFocus"
>
```

```vue-html
<template v-slot:header>
  <h1>Here might be a page title</h1>
</template>

<template v-slot:footer>
  <p>Here's some contact info</p>
</template>
```

```vue-html
<template #header>
  <h1>Here might be a page title</h1>
</template>

<template #footer>
  <p>Here's some contact info</p>
</template>
```

---

---
url: /style-guide/rules-recommended.md
---
# Règles de priorité C : Recommandées {#priority-c-rules-recommended}

Lorsqu'il existe plusieurs options correctes, un choix arbitraire peut être fait pour assurer une certaine cohérence. Dans ces règles, nous décrivons chaque option acceptable et suggérons un choix par défaut. Cela signifie que vous être libres de faire un choix différent dans votre code, tant que vous restez cohérent et avez une bonne raison. Vous avez certainement une bonne raison ! En adaptant les standards de la communauté, vous :

1. Entraînerez votre cerveau à analyser plus facilement la plupart du code que vous rencontrerez
2. Serez capable de copier et coller la plupart du code de la communauté sans modification
3. Réaliserez souvent que les nouvelles recrues sont habituées à votre style de code favori, du moins en ce qui concerne Vue

## Ordre des options du composant/de l'instance {#component-instance-options-order}

**Les options du composant/de l'instance devraient être ordonnées de manière constante.**

Voici l'ordre par défaut que nous recommandons pour les options d'un composant. Les options sont divisées en catégories, afin que vous sachiez où ajouter de nouvelles propriétés depuis les plugins.

1. **Conscience globale** (requiert des informations au-delà du composant)

   * `name`

2. **Options du compilateur de templates** (change la manière dont les templates sont compilés)

   * `compilerOptions`

3. **Dépendances du template** (ressources utilisées dans le template)

   * `components`
   * `directives`

4. **Composition** (fusionne les propriétés dans les options)

   * `extends`
   * `mixins`
   * `provide`/`inject`

5. **Interface** (l'interface du composant)

   * `inheritAttrs`
   * `props`
   * `emits`
   * `expose`

6. **Composition API** (le point d'entrée pour l'utilisation de la Composition API)

   * `setup`

7. **État local** (propriétés réactives locales)

   * `data`
   * `computed`

8. **Événements** (fonctions de rappel déclenchées par des événements réactifs)

   * `watch`
   * Événements du cycles de vie (dans l'ordre où ils sont appelés)
     * `beforeCreate`
     * `created`
     * `beforeMount`
     * `mounted`
     * `beforeUpdate`
     * `updated`
     * `activated`
     * `deactivated`
     * `beforeUnmount`
     * `unmounted`
     * `errorCaptured`
     * `renderTracked`
     * `renderTriggered`
     * `serverPrefetch` (SSR seulement)

9. **Propriétés non réactives** (propriétés de l'instance indépendantes du système de réactivité)

   * `methods`

10. **Rendu** (la description déclaratif du résultat du composant)
    * `template`/`render`

## Ordre des attributs des éléments {#element-attribute-order}

**Les attributs des éléments (et des composants) devraient être ordonnés de manière constante.**

Voici l'ordre par défaut que nous recommandons pour les options d'un composant. Les options sont divisées en catégories, afin que vous sachiez où ajouter des attributs personnalisés et des directives.

1. **Définition** (fourni les options du composant)

   * `is`

2. **Rendu de liste** (crée plusieurs variations d'un même élément)

   * `v-for`

3. **Conditionnelles** (indiquent si l'élément est rendu/affiché)

   * `v-if`
   * `v-else-if`
   * `v-else`
   * `v-show`
   * `v-cloak`

4. **Modificateurs du rendu** (changent la façon dont l'élément est rendu)

   * `v-pre`
   * `v-once`

5. **Conscience globale** (requiert des informations au-delà du composant)

   * `id`

6. **Attributs uniques** (attributs nécessitant des valeurs uniques)

   * `ref`
   * `key`

7. **Liaison bidirectionnelle** (combinaison de la liaison et des événements)

   * `v-model`

8. **Autres attributs** (tous les attributs liés et non liés non spécifiés)

9. **Événements** (écouteurs d'événements du composant)

   * `v-on`

10. **Contenu** (remplace le contenu de l'élément)
    * `v-html`
    * `v-text`

## Lignes vides dans les options du composant/de l'instance {#empty-lines-in-component-instance-options}

**Vous pouvez être tenté d'ajouter une ligne vide entre les propriétés multi-lignes, notamment si les options ne peuvent plus tenir sur votre écran sans défilement.**

Lorsque les composants commencent à prendre beaucoup d'espace ou deviennent difficiles à lire, l'ajout d'espaces entre les propriétés multi-lignes peut les rendre plus faciles à parcourir. Dans certains éditeurs, comme Vim, des options de formatage comme celle-ci peuvent également faciliter la navigation au clavier.

```js
props: {
  value: {
    type: String,
    required: true
  },

  focused: {
    type: Boolean,
    default: false
  },

  label: String,
  icon: String
},

computed: {
  formattedValue() {
    // ...
  },

  inputClasses() {
    // ...
  }
}
```

```js
// Sans espace c'est aussi bon tant que
// le composant soit toujours facile à lire
props: {
  value: {
    type: String,
    required: true
  },
  focused: {
    type: Boolean,
    default: false
  },
  label: String,
  icon: String
},
computed: {
  formattedValue() {
    // ...
  },
  inputClasses() {
    // ...
  }
}
```

```js
defineProps({
  value: {
    type: String,
    required: true
  },
  focused: {
    type: Boolean,
    default: false
  },
  label: String,
  icon: String
})
const formattedValue = computed(() => {
  // ...
})
const inputClasses = computed(() => {
  // ...
})
```

```js
defineProps({
  value: {
    type: String,
    required: true
  },

  focused: {
    type: Boolean,
    default: false
  },

  label: String,
  icon: String
})

const formattedValue = computed(() => {
  // ...
})

const inputClasses = computed(() => {
  // ...
})
```

## Ordre des éléments de premier niveau des composants monofichiers {#single-file-component-top-level-element-order}

**[Les composants monofichiers](/guide/scaling-up/sfc) devraient toujours ordonner les balises `<script>`, `<template>`, et `<style>` de manière constante, avec `<style>` en dernier, car au moins l'un des deux autres est toujours nécessaire.**

```vue-html [ComponentX.vue]
<style>/* ... */</style>
<script>/* ... */</script>
<template>...</template>
```

```vue-html [ComponentA.vue]
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>
```

```vue-html [ComponentB.vue]
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>
```

```vue-html [ComponentA.vue]
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>
```

```vue-html [ComponentB.vue]
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>
```

```vue-html [ComponentA.vue]
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>
```

```vue-html [ComponentB.vue]
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>
```

---

---
url: /style-guide/rules-use-with-caution.md
---
# Règles de priorité D: À utiliser avec précaution {#priority-d-rules-use-with-caution}

Certaines fonctionnalités de Vue existent pour prévoir de rares cas particuliers ou des migrations plus douces depuis une base de code héritée. Toutefois, lorsqu'elles sont surexploitées, elles peuvent rendre le code plus difficile à maintenir ou même devenir une source de bugs. Ces règles mettent en lumière ces fonctionnalités potentiellement risquées, en décrivant quand et pourquoi elles devraient être évitées.

## Sélecteurs d'éléments avec `scoped` {#element-selectors-with-scoped}

**Les sélecteurs d'éléments ne devraient pas être utilisés avec `scoped`.**

Préférez les sélecteurs de classes aux sélecteurs d'éléments dans les styles `scoped`, parce qu'un grand nombre de sélecteurs d'éléments sont lents.

::: details Explications détaillées
Pour limiter la portée des styles, Vue ajoute un attribut unique aux éléments des composants, tel que `data-v-f3f3eg9`. Les sélecteurs sont ensuite modifiés de manière à ce que seuls les éléments correspondant à cet attribut soient sélectionnés (par exemple `button[data-v-f3f3eg9]`).

Le problème est qu'un large nombre de sélecteurs d'éléments-attributs (par exemple `button[data-v-f3f3eg9]`) sera considérablement plus lent que des sélecteurs de classes-attributs (par exemple `.btn-close[data-v-f3f3eg9]`), donc les sélecteurs de classes doivent être privilégiés lorsque c'est possible.
:::

```vue-html
<template>
  <button>×</button>
</template>

<style scoped>
button {
  background-color: red;
}
</style>
```

```vue-html
<template>
  <button class="btn btn-close">×</button>
</template>

<style scoped>
.btn-close {
  background-color: red;
}
</style>
```

## Communication parent-enfant implicite {#implicit-parent-child-communication}

**Les props et les événements doivent être privilégiés pour la communication entre les composants parent-enfant, plutôt que `this.$parent` ou les props mutants.**

Une application Vue idéale est composée de flux de props vers le bas, et d'événements vers le haut. Respecter cette convention rendra vos composants beaucoup plus faciles à comprendre. Cependant, il existe des cas limites où la mutation de prop ou `this.$parent` peuvent simplifier deux composants déjà profondément couplés.

Le problème, c'est qu'il existe aussi de nombreux cas *simples* où ces modèles peuvent être pratiques. Attention : ne vous laissez pas séduire par l'idée d'échanger la simplicité (être capable de comprendre le flux de votre état) contre la commodité à court terme (écrire moins de code).

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  template: '<input v-model="todo.text">'
})
```

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  methods: {
    removeTodo() {
      this.$parent.todos = this.$parent.todos.filter(
        (todo) => todo.id !== vm.todo.id
      )
    }
  },

  template: `
    <span>
      {{ todo.text }}
      <button @click="removeTodo">
        ×
      </button>
    </span>
  `
})
```

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  emits: ['input'],

  template: `
    <input
      :value="todo.text"
      @input="$emit('input', $event.target.value)"
    >
  `
})
```

```js
app.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },

  emits: ['delete'],

  template: `
    <span>
      {{ todo.text }}
      <button @click="$emit('delete')">
        ×
      </button>
    </span>
  `
})
```

```vue
<script setup>
defineProps({
  todo: {
    type: Object,
    required: true
  }
})
</script>

<template>
  <input v-model="todo.text" />
</template>
```

```vue
<script setup>
const props = defineProps({
  todo: {
    type: Object,
    required: true
  }
})

function renameTodo() {
  // Modifie l'objet réactif du parent via la prop
  // En d'autres termes, l'enfant accède à un état appartenant au parent et le modifie.
  props.todo.text = 'renamed by child'
}
</script>
<template>
  <span>
    {{ todo.text }}
    <button @click="renameTodo">renommer</button>
  </span>
</template>
```

```vue
<script setup>
defineProps({
  todo: {
    type: Object,
    required: true
  }
})

const emit = defineEmits(['input'])
</script>

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

```vue
<script setup>
const props = defineProps({
  todo: {
    type: Object,
    required: true
  }
})

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

function renameTodo() {
  // Émet un nouvel objet — le parent est responsable de la mise à jour.
  emit('update:todo', { ...props.todo, text: 'renamed by parent' })
}
</script>

<template>
  <span>
    {{ todo.text }}
    <button @click="renameTodo">renommer</button>
  </span>
</template>
```

---

---
url: /about/releases.md
---

# Releases {#releases}

Un journal complet des précédentes releases est disponible sur [GitHub](https://github.com/vuejs/core/blob/main/CHANGELOG.md).

## Cycle des releases {#release-cycle}

Vue n'a pas de cycle fixe pour les releases.

* Les correctifs sont publiés selon les besoins.

* Les releases mineures contiennent toujours de nouvelles fonctionnalités, avec un intervalle de temps typique allant de 3 à 6 mois. Les releases mineures passent toujours par une phase de pré-release bêta.

* Les releases majeures seront annoncées à l'avance, et passeront assez tôt par une phase de discussion et des phases de pré-release alpha/bêta.

## Versionnement sémantique - Cas limites {#semantic-versioning-edge-cases}

Les releases de Vue suivent le [versionnement sémantique](https://semver.org/) avec quelques cas limites.

### Définitions TypeScript {#typescript-definitions}

Il se peut que nous sortions des modifications incompatibles avec les définitions TypeScript entre chaque versions **mineure**. Cela est dû au fait que :

1. Parfois, TypeScript lui-même apporte des modifications incompatibles entre les versions mineures, et nous pouvons être amenés à ajuster les types pour prendre en charge les nouvelles versions de TypeScript.

2. Parfois, il peut arriver que nous devions sortir des fonctionnalités qui ne sont disponibles que dans une version récente de TypeScript, ce qui augmente la version minimale requise de TypeScript.

Si vous utilisez TypeScript, vous pouvez utiliser un gestionnaire sémantique de version qui verrouille la version mineure actuelle et effectuer une mise à niveau manuelle lorsqu'une nouvelle version mineure de Vue est publiée.

### Compatibilité du code compilé avec d'anciens moteurs {#compiled-code-compatibility-with-older-runtime}

Une version **mineur** plus récente du compilateur Vue peut générer du code qui n'est pas compatible avec le moteur Vue d'une version mineure plus ancienne. Par exemple, le code généré par le compilateur Vue 3.2 peut ne pas être totalement compatible s'il est consommé par le moteur de Vue 3.1.

Ce problème ne concerne que les auteurs de bibliothèques, car dans les applications, la version du compilateur et la version d'exécution sont toujours les mêmes. Un décalage de version ne peut se produire que si vous envoyez du code de composant Vue précompilé sous forme de package et qu'un développeur l'utilise dans un projet utilisant une version antérieure de Vue. Par conséquent, votre paquet peut avoir besoin de déclarer explicitement une version mineure minimale requise de Vue.

## Pré-releases {#pre-releases}

Les versions mineures et majeures passent généralement par une série de phases de pré-lancement : **alpha**, **bêta** et **candidate à la publication (RC)**. Le nombre et le type de versions préliminaires dépendent de l'ampleur des modifications. Par exemple, une version mineure comportant des mises à jour limitées peut ne comporter qu'une phase bêta, tandis qu'une version majeure inclura généralement les trois phases afin de permettre des tests approfondis et de recueillir les commentaires de la communauté.

Vous pouvez installer les dernières versions préliminaires depuis npm à l'aide de `npx install-vue@alpha`, `npx install-vue@beta` ou `npx install-vue@rc`. Pour tester les modifications qui ne sont pas encore incluses dans les versions préliminaires taguées, chaque commit du dépôt [vuejs/core](https://github.com/vuejs/core) est publié sous forme d'aperçu temporaire en publication continue, que vous pouvez installer à l'aide de `npx install-vue@edge`.

Les pré-releases sont destinées aux tests d'intégration et de stabilité, ainsi qu'aux utilisateurs précoces qui peuvent fournir des retours sur les fonctionnalités instables. N'utilisez pas les pré-releases en production. Elles sont considérées comme instables et peuvent contenir des modifications importante de l'une à l'autre, il faut donc toujours se référer aux versions exactes lorsque vous utilisez des pré-releases.

## Dépréciations {#deprecations}

Nous pouvons périodiquement déprécier des fonctionnalités qui sont remplacées dans les releases mineures. Les fonctionnalités dépréciées continueront à fonctionner, et seront supprimées lors de la prochaine release majeure après avoir atteint le statut de fonctionnalité dépréciée.

## RFC {#rfcs}

Les nouvelles fonctionnalités avec un potentiel d'API et des changements majeurs à Vue passeront par le processus de **demande de commentaires, ou *Request for Comments*** (RFC). Le processus RFC a pour but de fournir une voie cohérente et contrôlée pour l'introduction de nouvelles fonctionnalités dans le framework, et de donner aux utilisateurs l'opportunité de participer et d'offrir des retours dans le processus de conception.

Le processus RFC est mené dans le repo [vuejs/rfcs](https://github.com/vuejs/rfcs) sur GitHub.

## Fonctionnalités expérimentales {#experimental-features}

Certaines fonctionnalités sont livrées et documentées dans une version stable de Vue, mais marquées comme expérimentales. Les fonctionnalités expérimentales sont typiquement des fonctionnalités qui ont une discussion RFC associée avec la plupart des problèmes de conception résolus sur le papier, mais qui manquent encore de retour de cas d'utilisation réelle.

L'objectif des fonctionnalités expérimentales est de permettre aux utilisateurs de fournir un retour en les testant dans un environnement de production, sans avoir à utiliser une version instable de Vue. Les fonctionnalités expérimentales sont elles-mêmes considérées comme instables, et ne doivent être utilisées que de manière contrôlée, en sachant que la fonctionnalité peut changer entre deux versions.

---

---
url: /guide/essentials/conditional.md
---
# Rendu conditionnel {#conditional-rendering}

## `v-if` {#v-if}

La directive `v-if` est utilisée pour restituer conditionnellement un bloc. Le bloc ne sera rendu que si l'expression de la directive retourne une valeur évaluée à vrai.

```vue-html
<h1 v-if="awesome">Vue is awesome!</h1>
```

## `v-else` {#v-else}

Vous pouvez utiliser la directive `v-else` pour indiquer un bloc "sinon" lié à un `v-if`:

```vue-html
<button @click="awesome = !awesome">Basculer</button>

<h1 v-if="awesome">Vue is awesome!</h1>
<h1 v-else>Oh no 😢</h1>
```

[Essayer en ligne](https://play.vuejs.org/#eNpFjkEOgjAQRa8ydIMulLA1hegJ3LnqBskAjdA27RQXhHu4M/GEHsEiKLv5mfdf/sBOxux7j+zAuCutNAQOyZtcKNkZbQkGsFjBCJXVHcQBjYUSqtTKERR3dLpDyCZmQ9bjViiezKKgCIGwM21BGBIAv3oireBYtrK8ZYKtgmg5BctJ13WLPJnhr0YQb1Lod7JaS4G8eATpfjMinjTphC8wtg7zcwNKw/v5eC1fnvwnsfEDwaha7w==)

[Essayer en ligne](https://play.vuejs.org/#eNpFjj0OwjAMha9iMsEAFWuVVnACNqYsoXV/RJpEqVOQqt6DDYkTcgRSWoplWX7y56fXs6O1u84jixlvM1dbSoXGuzWOIMdCekXQCw2QS5LrzbQLckje6VEJglDyhq1pMAZyHidkGG9hhObRYh0EYWOVJAwKgF88kdFwyFSdXRPBZidIYDWvgqVkylIhjyb4ayOIV3votnXxfwrk2SPU7S/PikfVfsRnGFWL6akCbeD9fLzmK4+WSGz4AA5dYQY=)

Un élément `v-else` doit immédiatement suivre un élément `v-if` ou un élément `v-else-if` sinon il ne sera pas reconnu.

## `v-else-if` {#v-else-if}

Le `v-else-if`, comme son nom l'indique, sert de bloc "else if" lié à un `v-if`. Il peut également être enchaîné plusieurs fois :

```vue-html
<div v-if="type === 'A'">
  A
</div>
<div v-else-if="type === 'B'">
  B
</div>
<div v-else-if="type === 'C'">
  C
</div>
<div v-else>
  Not A/B/C
</div>
```

Similaire à `v-else`, un bloc `v-else-if` doit immédiatement suivre un bloc `v-if` ou `v-else-if`.

## `v-if` avec `<template>` {#v-if-on-template}

Puisque `v-if` est une directive, elle doit être attachée à un seul élément. Mais que se passe-t-il si nous voulons basculer plus d'un élément ? Dans ce cas, nous pouvons utiliser `v-if` sur un élément `<template>`, qui sert de conteneur invisible. Le résultat du rendu final n'inclura pas l'élément `<template>`.

```vue-html
<template v-if="ok">
  <h1>Title</h1>
  <p>Paragraph 1</p>
  <p>Paragraph 2</p>
</template>
```

`v-else` et `v-else-if` peuvent également être utilisées dans `<template>`.

## `v-show` {#v-show}

Une autre option pour afficher conditionnellement un élément est la directive `v-show`. L'utilisation est sensiblement la même :

```vue-html
<h1 v-show="ok">Hello!</h1>
```

La différence est qu'un élément avec `v-show` sera toujours rendu et restera dans le DOM; `v-show` bascule uniquement la propriété CSS `display` de l'élément.

`v-show` ne prend pas en charge l'élément `<template>`, et ne fonctionne pas avec `v-else`.

## `v-if` vs. `v-show` {#v-if-vs-v-show}

`v-if` est un rendu conditionnel "réel" car il garantit que les écouteurs d'événements et les composants enfants à l'intérieur du bloc conditionnel sont correctement détruits et recréés lors des basculements.

`v-if` fonctionne également **à la volée** : si la condition est fausse lors du rendu initial, elle ne fera rien - le bloc conditionnel ne sera rendu que lorsque la condition deviendra vraie pour la première fois.

En comparaison, `v-show` est beaucoup plus simple - l'élément est toujours rendu quelle que soit la condition initiale, avec un basculement basé sur du CSS.

De manière générale, `v-if` a des coûts de basculement plus élevés tandis que `v-show` a des coûts de rendu initiaux plus élevés. Préférez donc `v-show` si vous avez besoin de basculer quelque chose très souvent, et préférez `v-if` si la condition est peu susceptible de changer à l'exécution.

## `v-if` avec `v-for` {#v-if-with-v-for}

Lorsque `v-if` et `v-for` sont toutes les deux utilisées sur le même élément, `v-if` sera évaluée en premier. Voir le [guide de rendu de liste](list#v-for-with-v-if) pour plus de détails.

::: warning Note
Il n'est **pas** recommandé d'utiliser `v-if` et `v-for` sur le même élément en raison de la priorité implicite. Reportez-vous au [guide de rendu de liste](list#v-for-with-v-if) pour plus de détails.
:::

---

---
url: /guide/scaling-up/ssr.md
---

# Rendu côté serveur (SSR) {#server-side-rendering-ssr}

## Vue d'ensemble {#overview}

### Qu'est-ce que le SSR ? {#what-is-ssr}

Vue.js est un framework pour développer des applications côté client avec des composants qui produisent et manipulent le DOM. Il peut également rendre les composants en HTML côté serveur et les hydrater en une application interactive côté client.

Une application Vue côté serveur peut être "isomorphe" ou "universelle", avec la majorité du code qui s'exécute sur le serveur **et** le client.

### Pourquoi le SSR ? {#why-ssr}

L'avantage du SSR par rapport à une application monopage SPA côté client :

* **Temps d'affichage plus rapide** : cela est plus important sur une connexion internet ou sur des périphériques lents. Le rendu côté serveur permet qu'une page soit rendue plus rapidement car elle n'a pas besoin d'attendre le téléchargement et l'exécution du JavaScript. La récupération des données se fait également côté serveur, ce qui peut améliorer la vitesse de connexion à la base de données. Cela peut entraîner une amélioration de l'expérience utilisateur et des métriques [Core Web Vitals](https://web.dev/vitals/), en particulier pour les applications où le temps d'affichage est important pour le taux de conversion.

* **Modèle mental unifié** : vous pouvez utiliser le même langage et le même modèle mental déclaratif orienté composant pour développer votre application entière, au lieu de sauter sans arrêt entre un système de modèle de backend et un framework frontend.

* **Meilleur référencement** : les robots d'indexation de moteur de recherche verront directement la page entièrement rendue.

  :::tip
  Les moteurs de recherche, par exemple Google et Bing, peuvent indexer correctement les applications JavaScript synchronisées. Si l'application utilise du contenu chargé de manière asynchrone, le rendu côté serveur peut être nécessaire pour un bon référencement.
  :::

Il y a aussi des compromis à considérer lors de l'utilisation du SSR :

* Contraintes de développement. Le code spécifique à un navigateur ne peut être utilisé que dans certains hooks de cycle de vie, certaines bibliothèques externes peuvent nécessiter un traitement spécial pour fonctionner dans une application SSR.

* Configuration de build et exigences de déploiement plus complexes. Contrairement à une SPA entièrement statique qui peut être déployée sur n'importe quel serveur de fichiers statiques, une application SSR nécessite un environnement où un serveur Node.js peut s'exécuter.

* Charge supplémentaire côté serveur. Le rendu d'une application dans Node.js sera plus gourmand en ressources, il faut prévoir une charge supplémentaire sur le serveur et utiliser les stratégies de mise en cache

Pensez à vos besoins en temps d'affichage avant d'utiliser SSR pour votre application, car cela peut consommer plus de CPU que les fichiers statiques. Si le temps d'affichage n'est pas crucial, SSR peut être inutile. Mais si c'est important, SSR peut améliorer les performances au chargement initial.

### SSR vs. SSG {#ssr-vs-ssg}

**La génération de site statique (SSG)**, également appelée pré-rendu, est une autre technique populaire pour construire des sites web rapides. Le rendu préalable des pages peut améliorer les performances en les rendant en une seule fois pour chaque utilisateur si les données nécessaires sont les mêmes. Les pages sont alors générées et servies sous forme de fichiers HTML statiques.

SSG conserve les mêmes caractéristiques de performance que les applications SSR : il offre une excellente performance en termes de délai de mise à disposition du contenu. De plus, il est moins cher et plus facile à déployer que les applications SSR parce que le résultat est un HTML statique avec des assets. SSG ne peut être appliqué qu'aux pages fournissant des données statiques, c'est-à-dire des données qui sont connues au moment de la création et qui ne peuvent pas changer entre les requêtes. Chaque fois que les données changent, un nouveau déploiement est nécessaire.

Si vous envisagez l'utilisation du SSR uniquement pour améliorer le référencement (SEO) d'un petit nombre de pages marketing (par exemple, `/`, `/about`, `/contact`, etc.), alors vous voulez probablement du SSG au lieu du SSR. Le SSG convient aux sites web de contenu, tels que les blogs et les sites de documentation. Il est utilisé pour générer des sites web statiques, comme ce site que vous lisez maintenant qui est créé avec [VitePress](https://vitepress.dev/).

## Tutoriel de base {#basic-tutorial}

### Rendu d'une application {#rendering-an-app}

Jetons un coup d'œil à l'exemple le plus simple du SSR de Vue en action.

1. Créez un nouveau répertoire et `cd` à l'intérieur
2. Exécutez `npm init -y`
3. Ajoutez `"type": "module"` dans `package.json` pour que Node.js fonctionne en [Mode modules ES](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
4. Exécutez `npm install vue`
5. Créez un fichier `example.js` :

```js
// cela fonctionne en Node.js sur le serveur.
import { createSSRApp } from 'vue'
// L'API de rendu de serveur de Vue est exposée sous `vue/server-renderer`.
import { renderToString } from 'vue/server-renderer'

const app = createSSRApp({
  data: () => ({ count: 1 }),
  template: `<button @click="count++">{{ count }}</button>`
})

renderToString(app).then((html) => {
  console.log(html)
})
```

Après, lancez :

```sh
> node example.js
```

Cela devrait retourner :

```
<button>1</button>
```

La fonction [`renderToString()`](/api/ssr#rendertostring) rend une application Vue en HTML et renvoie une Promise avec le rendu. Il peut également être rendu en continu avec l'API de stream [Node.js Stream API](https://nodejs.org/api/stream.html) ou [Web Streams API](https://developer.mozilla.org/fr/docs/Web/API/Streams_API). Voir la [référence de l'API SSR](/api/ssr) pour plus d'informations.

Nous utilisons [`express`](https://expressjs.com/) pour inclure le code Vue SSR dans une page HTML complète sur le serveur :

* Lancez `npm install express`
* Créez le fichier `server.js` suivant :

```js
import express from 'express'
import { createSSRApp } from 'vue'
import { renderToString } from 'vue/server-renderer'

const server = express()

server.get('/', (req, res) => {
  const app = createSSRApp({
    data: () => ({ count: 1 }),
    template: `<button @click="count++">{{ count }}</button>`
  })

  renderToString(app).then((html) => {
    res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <title>Vue SSR Example</title>
      </head>
      <body>
        <div id="app">${html}</div>
      </body>
    </html>
    `)
  })
})

server.listen(3000, () => {
  console.log('ready')
})
```

Enfin, exécutez `node server.js` et visitez `http://localhost:3000`. Vous devriez voir la page fonctionner avec le bouton.

[Essayez-le sur StackBlitz](https://stackblitz.com/fork/vue-ssr-example-basic?file=index.js)

### Hydratation des clients {#client-hydration}

Si vous cliquez sur le bouton, vous verrez que le nombre ne change pas. L'HTML est complètement statique côté client car nous n'avons pas chargé Vue dans le navigateur.

Pour rendre l'application côté client interactive, Vue doit effectuer l'étape de l'**hydratation**. Pendant l'hydratation, il crée la même application Vue qui a été exécutée sur le serveur, associe chaque composant aux nœuds DOM qu'il doit contrôler et attache les écouteurs d'événements du DOM.

Pour monter une application en mode hydratation, nous devons utiliser [`createSSRApp()`](/api/application#createssrapp) au lieu de `createApp()` :

```js{2}
// cela fonctionne dans le navigateur.
import { createSSRApp } from 'vue'

const app = createSSRApp({
  // ...même application que sur le serveur
})

// Le montage d'une application SSR sur le client suppose
// que le HTML a été pré-rendu et qu'il effectuera une
// hydratation au lieu de monter de nouveaux nœuds du DOM.
app.mount('#app')
```

### Structure du code {#code-structure}

Remarquez que nous devons réutiliser la même implémentation d'application côté serveur. C'est là que nous devons commencer à réfléchir à la structure du code dans une application SSR - comment partager le même code d'application entre le serveur et le client ?

Ici, nous allons démontrer la configuration la plus simple. Tout d'abord, divisons la logique de création d'application en un fichier dédié, `app.js`:

```js [app.js]
// (partagé entre le serveur et le client)
import { createSSRApp } from 'vue'

export function createApp() {
  return createSSRApp({
    data: () => ({ count: 1 }),
    template: `<button @click="count++">{{ count }}</button>`
  })
}
```

Ce fichier et ses dépendances sont partagés entre le serveur et le client - nous les appelons **code universel**. Il y a un certain nombre de choses à prendre en compte lors de la rédaction du code universel, nous allons le [voir ci-dessous](#writing-ssr-friendly-code).

Notre entrée client importe le code universel, crée l'application et effectue le montage :

```js [client.js]
import { createApp } from './app.js'

createApp().mount('#app')
```

Et le serveur utilise la même logique de création d'application dans le gestionnaire de demande :

```js{2,5} [server.js]
// (code non pertinent omis)
import { createApp } from './app.js'

server.get('/', (req, res) => {
  const app = createApp()
  renderToString(app).then(html => {
    // ...
  })
})
```

De plus, pour charger les fichiers client dans le navigateur, nous devons également :

1. Servir les fichiers client en ajoutant `server.use(express.static('.'))` dans `server.js`.
2. Charger l'entrée client en ajoutant `<script type="module" src="/client.js"></script>` au fichier HTML.
3. Prendre en charge l'utilisation comme `import * from 'vue'` dans le navigateur en ajoutant [Import Map](https://github.com/WICG/import-maps) au fichier HTML.

[Essayez l'exemple complété sur StackBlitz](https://stackblitz.com/fork/vue-ssr-example?file=index.js). Le bouton est maintenant interactif !

## Solutions de haut niveau {#higher-level-solutions}

Pour une application SSR en production, plusieurs considérations supplémentaires doivent être prises en compte :

* Prendre en charge les SFC Vue et d'autres exigences de l'étape de build. En fait, nous aurons besoin de coordonner deux builds pour la même application : un pour le client et un pour le serveur.

  :::tip
  Les composants Vue sont compilés différemment en SSR : les templates compilés sont compilés en chaînes, par rapport à des fonctions de rendu de DOM virtuel, pour une performance accrue.
  :::

* Dans le gestionnaire de requête du serveur, afficher le HTML avec les liens corrects des ressources clientes et autres ressources optimisées. Il peut également être nécessaire de basculer entre le mode SSR et SSG, ou même de mélanger les deux dans la même application.

* Gestion du routage, de la récupération de données et des stores de gestion d'état de manière universelle.

Une implémentation complète serait assez complexe et dépend de la chaîne d'outils de build que vous avez choisie. Par conséquent, nous vous recommandons fortement d'adopter une solution plus élevée et orientée afin d'abstraire la complexité pour vous. Ci-dessous, nous présenterons quelques solutions SSR recommandées dans l'écosystème Vue.

### Nuxt {#nuxt}

[Nuxt](https://nuxt.com/) est une plateforme Vue simplifiée pour développer des applications universelles et peut être utilisée comme générateur de site statique. Nous vous recommandons fortement de l'essayer.

### Quasar {#quasar}

[Quasar](https://quasar.dev) est une plateforme basée sur Vue qui vous permet de développer des applications pour plusieurs plateformes (SSR, SPA, PWA, mobile, bureau, extension de navigateur) avec un seul code de base. Il fournit également des composants d'interface utilisateur conformes à Material Design.

### Vite SSR {#vite-ssr}

Vite fournit [un support natif pour le rendu côté serveur de Vue](https://vite.dev/guide/ssr.html), mais il est intentionnellement de bas niveau. Si vous souhaitez utiliser directement avec Vite, consultez [vite-plugin-ssr](https://vite-plugin-ssr.com/), un plugin communautaire qui fait abstraction de nombreux détails complexes pour vous.

Vous pouvez également trouver un exemple de projet Vue + Vite SSR en utilisant une configuration manuelle ici, qui peut servir de base pour le build. Notez que ceci n'est recommandé que si vous avez de l'expérience avec SSR / outils de build et que vous souhaitez avoir un contrôle complet sur l'architecture de haut niveau.

## Écrire du code SSR propre {#writing-ssr-friendly-code}

Indépendamment de votre configuration de build ou de votre choix de framework de haut niveau, il existe des principes qui s'appliquent à toutes les applications Vue SSR.

### Réactivité sur le serveur {#reactivity-on-the-server}

Pendant le SSR, chaque URL requêtée correspond à un état souhaité de notre application. Il n'y a pas d'interaction utilisateur et aucune mise à jour du DOM, donc la réactivité n'est pas nécessaire sur le serveur. Par défaut, la réactivité est désactivée pendant le SSR pour une meilleure performance.

### Les hooks du cycle de vie du composant {#component-lifecycle-hooks}

Vu qu'il n'y a pas de mises à jour dynamiques, les hooks de cycle de vie tels que `mounted``onMounted` ou `updated``onUpdated` ne seront **PAS** appelés pendant le SSR et ne seront exécutés que côté client. Les seuls hooks qui sont appelés pendant le SSR sont `beforeCreate` et `created`

Vous devriez éviter le code qui produit des effets de bord qui nécessitent un nettoyage dans `beforeCreate` et `created``setup()` ou dans la portée de `<script setup>`. Un exemple d'effets de bord est la configuration de minuteries avec `setInterval`. Dans le code exécuté côté client, nous pouvons configurer une minuterie et la démonter dans `beforeUnmount``onBeforeUnmount` ou `unmounted``onUnmounted`. Cependant, étant donné que les hooks de démontage ne seront jamais appelés pendant le SSR, les minuteries resteront à jamais. Pour éviter cela, déplacez votre code d'effets de bord dans `mounted``onMounted`.

### Accès aux API spécifiques à la plateforme {#access-to-platform-specific-apis}

Le code universel ne peut pas supposer l'accès aux API spécifiques à la plateforme, donc si votre code utilise directement des éléments spécifiques au navigateur comme `window` ou `document`, ils lanceront des erreurs lorsqu'ils seront exécutés dans Node.js et vice-versa.

Pour les tâches partagées entre le serveur et le client mais avec des API de plateforme différentes, il est recommandé d'envelopper les implémentations spécifiques à la plateforme dans une API universelle ou d'utiliser des bibliothèques qui le font pour vous. Par exemple, vous pouvez utiliser [`node-fetch`](https://github.com/node-fetch/node-fetch) pour utiliser la même API fetch sur le serveur et le client.

Pour les API spécifiques au navigateur, la démarche courante consiste à y accéder de manière paresseuse dans des hooks de cycle de vie client uniquement tels que `mounted``onMounted`.

Notez que si une bibliothèque tiers n'est pas écrite en vue d'une utilisation universelle, il peut être difficile de l'intégrer dans une application rendue côté serveur. Vous *pourriez* être en mesure de la faire fonctionner en simulant certaines des globales, mais ce serait un bricolage et pourrait interférer avec le code de détection de l'environnement d'autres bibliothèques.

### Pollution d'état par demandes croisées {#cross-request-state-pollution}

Dans le chapitre de Gestion d'État, nous avons introduit un [patron de gestion d'état simple en utilisant les API de réactivité](state-management.html#simple-state-management-with-reactivity-api). Dans un contexte SSR, ce modèle nécessite des ajustements supplémentaires.

Le modèle déclare un état partagé dans la portée d'un module JavaScript. Cela les rend **singletons** - c'est-à-dire qu'il n'y a qu'une seule instance de l'objet réactif tout au long de la vie de notre application. Cela fonctionne comme prévu dans une application Vue côté client, car les modules de notre application sont initialisés à nouveau pour chaque visite de page navigateur.

Cependant, dans un contexte SSR, les modules d'application sont généralement initialisés une seule fois sur le serveur, lorsque le serveur démarre. Les mêmes instances de modules seront réutilisées à travers plusieurs demandes de serveur, et donc nos objets d'état singletons. Si nous modifions l'état partagé singleton avec des données spécifiques à un utilisateur, cela peut accidentellement causer une fuite vers une demande provenant d'un autre utilisateur. Nous appelons cela une **pollution d'état par demandes croisées.**

Techniquement, nous pouvons ré-initialiser tous les modules JavaScript à chaque demande, tout comme nous le faisons dans les navigateurs. Cependant, l'initialisation des modules JavaScript peut être coûteuse, ce qui affecterait significativement les performances du serveur.

La solution recommandée est de créer une nouvelle instance de l'application entière - y compris le routeur et les stores globaux - à chaque demande. Ensuite, au lieu de l'importer directement dans nos composants, nous fournissons l'état partagé en utilisant [provide au niveau de l'application](/guide/components/provide-inject#app-level-provide) et l'injecterons dans les composants qui en ont besoin :

```js [app.js]
// (partagé entre le serveur et le client)
import { createSSRApp } from 'vue'
import { createStore } from './store.js'

// appelée sur chaque demande
export function createApp() {
  const app = createSSRApp(/* ... */)
  // crée une nouvelle instance de store par requête
  const store = createStore(/* ... */)
  // fournit un store au niveau de l'application
  app.provide('store', store)
  // expose également le store à des fins d'hydratation
  return { app, store }
}
```

Les bibliothèques de gestion d'état comme Pinia sont conçues dans cet esprit. Consultez le [guide SSR de Pinia](https://pinia.vuejs.org/ssr/) pour plus de détails.

### Déséquilibre de l'hydratation {#hydration-mismatch}

Si la structure du DOM du HTML pré-rendu ne correspond pas à la sortie attendue de l'application côté client, il y aura une erreur de désaccord d'hydratation. Le désaccord d'hydratation est généralement introduit par les causes suivantes :

1. Le modèle contient une structure HTML imbriqué non valide, et le HTML rendu a été "corrigé" par le comportement d'analyse syntaxique du HTML natif du navigateur. Par exemple, une erreur courante est que [`<div>` ne peut pas être placée à l'intérieur de `<p>`](https://stackoverflow.com/questions/8397852/why-cant-the-p-tag-contain-a-div-tag-inside-it):

   ```html
   <p><div>hi</div></p>
   ```

   Si nous produisons ceci dans notre HTML rendu par le serveur, le navigateur terminera le premier `<p>` lorsque `<div>` sera rencontré et l'analysera en la structure de DOM suivante :

   ```html
   <p></p>
   <div>hi</div>
   <p></p>
   ```

2. Les données de mise en forme avec des valeurs aléatoires causent des incohérences lors de l'exécution serveur/client. Pour éviter cela, il existe deux solutions.

   1. Utilisez `v-if` + `onMounted` pour rendre uniquement sur le client la partie dépendante de valeurs aléatoires. Votre framework peut également disposer de fonctionnalités intégrées pour faciliter cela, par exemple le composant `<ClientOnly>` de VitePress.

   2. Utilisez une bibliothèque de générateur de nombres aléatoires qui prend en charge la génération avec des seeds, et assurez-vous que l'exécution du serveur et l'exécution du client utilisent la même seed (par exemple en incluant la seed dans l'état sérialisé et en la récupérant sur le client).

3. Le temps local pour l'utilisateur ne peut pas toujours être déterminé sur le serveur en raison de différences de fuseau horaire, il doit donc être converti côté client.

Lorsque Vue rencontre une incohérence d'hydratation, il tentera de récupérer automatiquement et de régler le DOM pré-rendu pour correspondre à l'état côté client. Cela entraînera une perte de performance de rendu due à la suppression de nœuds incorrects et au montage de nouveaux nœuds, mais dans la plupart des cas, l'application devrait continuer à fonctionner comme prévu. Cela dit, il est toujours préférable d'éliminer les incohérences d'hydratation pendant le développement.

#### Suppression de la non-concordance lors de l'hydratation  {#suppressing-hydration-mismatches}

Dans Vue 3.5+, il est possible de supprimer sélectivement les non-concordances lors de l'hydratation inévitables en utilisant l'attribut [`data-allow-mismatch`](/api/ssr#data-allow-mismatch).

### Directives personnalisées {#custom-directives}

Les directives personnalisées ne sont pas prises en compte lors du SSR. Mais si vous souhaitez spécifier comment une directive personnalisée doit être rendue, vous pouvez les rendre en utilisant le hook `getSSRProps` :

```js
const myDirective = {
  mounted(el, binding) {
    // implémentation côté client :
    // mettre à jour directement le DOM
    el.id = binding.value
  },
  getSSRProps(binding) {
    // implémentation côté serveur :
    // renvoie les props à rendre.
    // getSSRProps ne reçoit que la liaison de la directive.
    return {
      id: binding.value
    }
  }
}
```

### Teleports {#teleports}

L'utilisation de Teleports nécessite une gestion spéciale lors de la SSR. Si l'application rendue contient Teleports, le contenu téléporté ne sera pas inclus dans la chaîne rendue. Une solution plus facile consiste à rendre Teleport lors du montage.

Si vous devez hydrater le contenu téléporté, ils seront exposés dans la propriété `teleports` de l'objet de contexte du SSR :

```js
const ctx = {}
const html = await renderToString(app, ctx)

console.log(ctx.teleports) // { '#teleported': 'teleported content' }
```

Vous devez injecter le markup de téléportation dans l'emplacement correct dans votre HTML de page finale, tout comme vous devez injecter le markup principal de l'application.

:::tip
Évitez de cibler `body` lorsque vous utilisez Teleports et le SSR ensemble - généralement, `<body>` contiendra d'autres contenus rendus sur le serveur ce qui rend impossible pour Teleports de déterminer le bon emplacement de départ pour l'hydratation.

Préférez plutôt un conteneur dédié, par exemple `<div id="teleported"></div>` qui ne contient que le contenu téléporté.
:::

---

---
url: /guide/essentials/list.md
---
# Rendu de liste {#list-rendering}

## `v-for` {#v-for}

Nous pouvons utiliser la directive `v-for` pour rendre une liste d'items basée sur un tableau. La directive `v-for` nécessite une syntaxe spéciale de la forme `item in items`, où `items` est le tableau de données source et `item` est un **alias** pour l'élément du tableau sur lequel on itère :

```js
const items = ref([{ message: 'Foo' }, { message: 'Bar' }])
```

```js
data() {
  return {
    items: [{ message: 'Foo' }, { message: 'Bar' }]
  }
}
```

```vue-html
<li v-for="item in items">
  {{ item.message }}
</li>
```

À l'intérieur de la portée du `v-for`, les expressions du template ont accès à toutes les propriétés de la portée du parent. De plus, `v-for` supporte également un second et optionnel alias pour l'index de l'item actuel :

```js
const parentMessage = ref('Parent')
const items = ref([{ message: 'Foo' }, { message: 'Bar' }])
```

```js
data() {
  return {
    parentMessage: 'Parent',
    items: [{ message: 'Foo' }, { message: 'Bar' }]
  }
}
```

```vue-html
<li v-for="(item, index) in items">
  {{ parentMessage }} - {{ index }} - {{ item.message }}
</li>
```

[Essayer en ligne](https://play.vuejs.org/#eNpdTsuqwjAQ/ZVDNlFQu5d64bpwJ7g3LopOJdAmIRlFCPl3p60PcDWcM+eV1X8Iq/uN1FrV6RxtYCTiW/gzzvbBR0ZGpBYFbfQ9tEi1ccadvUuM0ERyvKeUmithMyhn+jCSev4WWaY+vZ7HjH5Sr6F33muUhTR8uW0ThTuJua6mPbJEgGSErmEaENedxX3Z+rgxajbEL2DdhR5zOVOdUSIEDOf8M7IULCHsaPgiMa1eK4QcS6rOSkhdfapVeQLQEWnH)

[Essayer en ligne](https://play.vuejs.org/#eNpVTssKwjAQ/JUllyr0cS9V0IM3wbvxEOxWAm0a0m0phPy7m1aqhpDsDLMz48XJ2nwaUZSiGp5OWzpKg7PtHUGNjRpbAi8NQK1I7fbrLMkhjc5EJAn4WOXQ0BWHQb2whOS24CSN6qjXhN1Qwt1Dt2kufZ9ASOGXOyvH3GMNCdGdH75VsZVjwGa2VYQRUdVqmLKmdwcpdjEnBW1qnPf8wZIrBQujoff/RSEEyIDZZeGLeCn/dGJyCSlazSZVsUWL8AYme21i)

La portée des variables de `v-for` est similaire au JavaScript suivant :

```js
const parentMessage = 'Parent'
const items = [
  /* ... */
]

items.forEach((item, index) => {
  // a accès à `parentMessage` de la portée extérieure
  // mais `item` et `index` ne sont disponibles qu'ici
  console.log(parentMessage, item.message, index)
})
```

Remarquez comment la valeur de `v-for` correspond à la fonction signature du rappel du `forEach`. En fait, vous pouvez utiliser la déstructuration sur l'alias item du `v-for` de la même manière que la déstructuration des arguments de fonction :

```vue-html
<li v-for="{ message } in items">
  {{ message }}
</li>

<!-- avec l'index alias -->
<li v-for="({ message }, index) in items">
  {{ message }} {{ index }}
</li>
```

Pour les `v-for` imbriqués, les portées fonctionnent de la même manière qu'avec les fonctions imbriquées. Chaque portée de `v-for` a accès aux portées de ses parents :

```vue-html
<li v-for="item in items">
  <span v-for="childItem in item.children">
    {{ item.message }} {{ childItem }}
  </span>
</li>
```

Vous pouvez également utiliser `of` comme séparateur au lieu de `in`, pour que cela soit plus proche de la syntaxe JavaScript pour les itérateurs :

```vue-html
<div v-for="item of items"></div>
```

## `v-for` avec un objet {#v-for-with-an-object}

Vous pouvez également utiliser `v-for` pour itérer sur les propriétés d'un objet. L'ordre d'itération sera basé sur le résultat de l'appel à `Object.values()` sur l'objet :

```js
const myObject = reactive({
  title: 'How to do lists in Vue',
  author: 'Jane Doe',
  publishedAt: '2016-04-10'
})
```

```js
data() {
  return {
    myObject: {
      title: 'How to do lists in Vue',
      author: 'Jane Doe',
      publishedAt: '2016-04-10'
    }
  }
}
```

```vue-html
<ul>
  <li v-for="value in myObject">
    {{ value }}
  </li>
</ul>
```

Vous pouvez également fournir un second alias pour le nom de la propriété (aussi appelé clé) :

```vue-html
<li v-for="(value, key) in myObject">
  {{ key }}: {{ value }}
</li>
```

Et un autre pour l'index :

```vue-html
<li v-for="(value, key, index) in myObject">
  {{ index }}. {{ key }}: {{ value }}
</li>
```

[Essayer en ligne](https://play.vuejs.org/#eNo9jjFvgzAQhf/KE0sSCQKpqg7IqRSpQ9WlWycvBC6KW2NbcKaNEP+9B7Tx4nt33917Y3IKYT9ESspE9XVnAqMnjuFZO9MG3zFGdFTVbAbChEvnW2yE32inXe1dz2hv7+dPqhnHO7kdtQPYsKUSm1f/DfZoPKzpuYdx+JAL6cxUka++E+itcoQX/9cO8SzslZoTy+yhODxlxWN2KMR22mmn8jWrpBTB1AZbMc2KVbTyQ56yBkN28d1RJ9uhspFSfNEtFf+GfnZzjP/oOll2NQPjuM4xTftZyIaU5VwuN0SsqMqtWZxUvliq/J4jmX4BTCp08A==)

[Essayer en ligne](https://play.vuejs.org/#eNo9T8FqwzAM/RWRS1pImnSMHYI3KOwwdtltJ1/cRqXe3Ng4ctYS8u+TbVJjLD3rPelpLg7O7aaARVeI8eS1ozc54M1ZT9DjWQVDMMsBoFekNtucS/JIwQ8RSQI+1/vX8QdP1K2E+EmaDHZQftg/IAu9BaNHGkEP8B2wrFYxgAp0sZ6pn2pAeLepmEuSXDiy7oL9gduXT+3+pW6f631bZoqkJY/kkB6+onnswoDw6owijIhEMByjUBgNU322/lUWm0mZgBX84r1ifz3ettHmupYskjbanedch2XZRcAKTnnvGVIPBpkqGqPTJNGkkaJ5+CiWf4KkfBs=)

## `v-for` avec une plage {#v-for-with-a-range}

`v-for` peut également prendre un nombre entier. Dans ce cas il va répéter le template un certain nombre de fois, basé sur une plage `1...n`.

```vue-html
<span v-for="n in 10">{{ n }}</span>
```

Notez qu'ici `n` démarre avec une valeur initiale de `1` au lieu de `0`.

## `v-for` sur le `<template>` {#v-for-on-template}

Comme le modèle `v-if`, vous pouvez aussi utiliser une balise `<template>` avec `v-for` pour effectuer le rendu d'un bloc composé de plusieurs éléments. Par exemple :

```vue-html
<ul>
  <template v-for="item in items">
    <li>{{ item.msg }}</li>
    <li class="divider" role="presentation"></li>
  </template>
</ul>
```

## `v-for` avec `v-if` {#v-for-with-v-if}

Lorsqu'ils existent sur le même nœud, `v-if` a une priorité plus importante que `v-for`. Cela signifie que la condition du `v-if` n'aura pas accès aux variables de la portée du `v-for` :

```vue-html
<!--
Une erreur va être levée car la propriété "todo" n'est pas définie sur l'instance.
-->
<li v-for="todo in todos" v-if="!todo.isComplete">
  {{ todo.name }}
</li>
```

Cela peut être résolu en déplaçant le `v-for` sur une balise `<template>` enveloppante (ce qui est également plus explicite) :

```vue-html
<template v-for="todo in todos">
  <li v-if="!todo.isComplete">
    {{ todo.name }}
  </li>
</template>
```

:::warning Note
Il n'est **pas** recommandé d'utiliser `v-if` et `v-for` sur le même élément à cause de la préséance implicite.

Il y a deux cas courants où cela peut être tentant :

* Pour filtrer les éléments d'une liste (par exemple `v-for="user in users" v-if="user.isActive"`). Dans ce cas, remplacez `users` par une nouvelle propriété calculée qui retourne votre liste filtrée (par exemple `activeUsers`).

* Pour éviter de rendre une liste si elle doit être cachée (par exemple, `v-for="user in users" v-if="shouldShowUsers"`). Dans ce cas, déplacez le `v-if` dans un élément conteneur (par exemple `ul`, `ol`).

:::

## Maintenir l'état avec `key` {#maintaining-state-with-key}

Lorsque Vue met à jour une liste d'éléments rendue avec `v-for`, il utilise par défaut une stratégie d'"ajustement sur place". Si l'ordre des données a changé, au lieu de déplacer les éléments du DOM de manière à respecter l'ordre des items, Vue va ajuster chaque élément en place et s'assurer qu'il reflète ce qui devrait être rendu à un index particulier.

Ce mode par défaut est efficace, mais **seulement approprié lorsque votre rendu de liste ne dépend pas de l'état d'un composant enfant ou de l'état temporaire du DOM (par exemple les valeurs d'entrées d'un formulaire)**.

Pour aiguiller Vue afin qu'il puisse tracer l'identité de chaque nœud, et ainsi réutiliser et réarranger l'ordre des éléments existants, vous devez fournir un attribut `key` unique pour chaque item :

```vue-html
<div v-for="item in items" :key="item.id">
  <!-- contenu -->
</div>
```

Lorsque vous utilisez `<template v-for>`, la `key` doit être placée sur le conteneur `<template>` :

```vue-html
<template v-for="todo in todos" :key="todo.name">
  <li>{{ todo.name }}</li>
</template>
```

:::tip Note
Ici, `key` est un attribut spécial qui est lié avec `v-bind`. Il ne doit pas être confondu avec la variable de clé de propriété utilisée dans le cas d'un [`v-for` avec un objet](#v-for-with-an-object).
:::

Il est recommandé de fournir un attribut `key` avec `v-for` dès que possible, sauf si le contenu du DOM itéré est simple (c'est-à-dire qu'il ne comporte pas de composants ou d'éléments du DOM avec un état), ou si vous comptez intentionnellement sur le comportement par défaut dans un but de gain de performances.

La liaison `key` attend des valeurs - c'est-à-dire des chaînes de caractères et des nombres. N'utilisez pas d'objets comme clé de `v-for`. Pour l'utilisation détaillée de l'attribut `key`, référez-vous à la [documentation de l'API `key`](/api/built-in-special-attributes#key).

## `v-for` avec un composant {#v-for-with-a-component}

> Cette section part du principe que vous connaissez déjà les [Composants](/guide/essentials/component-basics). N'hésitez pas à la sauter et à revenir plus tard !

Vous pouvez utiliser `v-for` directement sur un composant, comme avec n'importe quel élément (n'oubliez pas de fournir une `key`) :

```vue-html
<MyComponent v-for="item in items" :key="item.id" />
```

Toutefois, les données ne vont pas être automatiquement passées au composant, car les composants ont chacun leur propre portée isolée. Afin de passer la donnée itérée au composant, il faut également utiliser les props :

```vue-html
<MyComponent
  v-for="(item, index) in items"
  :item="item"
  :index="index"
  :key="item.id"
/>
```

La raison pour laquelle on n'injecte pas automatiquement `item` dans le composant est que cela rendrait le composant étroitement lié au fonctionnement de `v-for`. Être explicite sur la source d'où proviennent les données rend le composant réutilisable dans d'autres situations.

Regardez [cet exemple d'une simple todo list](https://play.vuejs.org/#eNp1U8Fu2zAM/RXCGGAHTWx02ylwgxZYB+ywYRhyq3dwLGYRYkuCJTsZjPz7KMmK3ay9JBQfH/meKA/Rk1Jp32G0jnJdtVwZ0Gg6tSkEb5RsDQzQ4h4usG9lAzGVxldoK5n8ZrAZsTQLCduRygAKUUmhDQg8WWyLZwMPtmESx4sAGkL0mH6xrMH+AHC2hvuljw03Na4h/iLBHBAY1wfUbsTFVcwoH28o2/KIIDuaQ0TTlvrwNu/TDe+7PDlKXZ6EZxTiN4kuRI3W0dk4u4yUf7bZfScqw6WAkrEf3m+y8AOcw7Qv6w5T1elDMhs7Nbq7e61gdmme60SQAvgfIhExiSSJeeb3SBukAy1D1aVBezL5XrYN9Csp1rrbNdykqsUehXkookl0EVGxlZHX5Q5rIBLhNHFlbRD6xBiUzlOeuZJQz4XqjI+BxjSSYe2pQWwRBZizV01DmsRWeJA1Qzv0Of2TwldE5hZRlVd+FkbuOmOksJLybIwtkmfWqg+7qz47asXpSiaN3lxikSVwwfC8oD+/sEnV+oh/qcxmU85mebepgLjDBD622Mg+oDrVquYVJm7IEu4XoXKTZ1dho3gnmdJhedEymn9ab3ysDPdc4M9WKp28xE5JbB+rzz/Trm3eK3LAu8/E7p2PNzYM/i3ChR7W7L7hsSIvR7L2Aal1EhqTp80vF95sw3WcG7r8A0XaeME=) pour comprendre comment rendre une liste de composants en utilisant `v-for`, et en passant des données différentes à chaque instance.

Consultez [cet exemple d'une simple todo list](https://play.vuejs.org/#eNqNVE2PmzAQ/SsjVIlEm4C27Qmx0a7UVuqhPVS5lT04eFKsgG2BSVJF+e8d2xhIu10tihR75s2bNx9wiZ60To49RlmUd2UrtNkUUjRatQa2iquvBhvYt6qBOEmDwQbEhQQoJJ4dlOOe9bWBi7WWiuIlStNlcJlYrivr5MywxdIDAVo0fSvDDUDiyeK3eDYZxLGLsI8hI7H9DHeYQuwjeAb3I9gFCFMjUXxSYCoELroKO6fZP17Mf6jev0i1ZQcE1RtHaFrWVW/l+/Ai3zd1clQ1O8k5Uzg+j1HUZePaSFwfvdGhfNIGTaW47bV3Mc6/+zZOfaaslegS18ZE9121mIm0Ep17ynN3N5M8CB4g44AC4Lq8yTFDwAPNcK63kPTL03HR6EKboWtm0N5MvldtA8e1klnX7xphEt3ikTbpoYimsoqIwJY0r9kOa6Ag8lPeta2PvE+cA3M7k6cOEvBC6n7UfVw3imPtQ8eiouAW/IY0mElsiZWqOdqkn5NfCXxB5G6SJRvj05By1xujpJWUp8PZevLUluqP/ajPploLasmk0Re3sJ4VCMnxvKQ//0JMqrID/iaYtSaCz+xudsHjLpPzscVGHYO3SzpdixIXLskK7pcBucnTUdgg3kkmcxhetIrmH4ebr8m/n4jC6FZp+z7HTlLsVx1p4M7odcXPr6+Lnb8YOne5+C2F6/D6DH2Hx5JqOlCJ7yz7IlBTbZsf7vjXVBzjvLDrH5T0lgo=) pour voir comment rendre une liste de composants en utilisant `v-for`, en passant des données différentes à chaque instance.

## Détection des changements pour un tableau {#array-change-detection}

### Méthodes de mutation {#mutation-methods}

Vue est capable de détecter quand une méthode de mutation d'un tableau réactif est appelée et d'engendrer les mises à jour nécessaires. Ces méthodes de mutation sont :

* `push()`
* `pop()`
* `shift()`
* `unshift()`
* `splice()`
* `sort()`
* `reverse()`

### Remplacer un tableau {#replacing-an-array}

Les méthodes de mutation, comme leur nom l'indique, vont entrainer des mutations du tableau sur lequel elles sont appelées. En comparaison, il existe également des méthodes non-mutantes, par exemple `filter()`, `concat()` et `slice()`, qui ne modifient pas le tableau original mais **retournent toujours un nouveau tableau**. Lorsqu'on travaille avec des méthodes non-mutantes, il faut remplacer l'ancien tableau par le nouveau :

```js
// `items` est une ref qui a pour valeur un tableau
items.value = items.value.filter((item) => item.message.match(/Foo/))
```

```js
this.items = this.items.filter((item) => item.message.match(/Foo/))
```

On pourrait penser que cela va pousser Vue à se débarrasser du DOM actuel et à rendre à nouveau toute la liste - heureusement, ça n'est pas le cas. Vue implémente des approches intelligentes afin de maximiser la réutilisation des éléments du DOM, de manière à ce que remplacer un tableau par un autre tableau composé en partie des mêmes éléments soit une opération très efficace.

## Afficher des résultats filtrés/triés {#displaying-filtered-sorted-results}

Il arrive parfois que nous voulions afficher une version filtrée ou triée d'un tableau sans muter ou remettre à zéro les données originales. Dans ce cas, on peut créer une propriété calculée qui retourne le tableau filtré ou trié.

Par exemple :

```js
const numbers = ref([1, 2, 3, 4, 5])

const evenNumbers = computed(() => {
  return numbers.value.filter((n) => n % 2 === 0)
})
```

```js
data() {
  return {
    numbers: [1, 2, 3, 4, 5]
  }
},
computed: {
  evenNumbers() {
    return this.numbers.filter(n => n % 2 === 0)
  }
}
```

```vue-html
<li v-for="n in evenNumbers">{{ n }}</li>
```

Dans les situations où les propriétés calculées ne sont pas envisageables (par exemple dans des boucles imbriquées `v-for`), vous pouvez utiliser une méthode :

```js
const sets = ref([
  [1, 2, 3, 4, 5],
  [6, 7, 8, 9, 10]
])

function even(numbers) {
  return numbers.filter((number) => number % 2 === 0)
}
```

```js
data() {
  return {
    sets: [[ 1, 2, 3, 4, 5 ], [6, 7, 8, 9, 10]]
  }
},
methods: {
  even(numbers) {
    return numbers.filter(number => number % 2 === 0)
  }
}
```

```vue-html
<ul v-for="numbers in sets">
  <li v-for="n in even(numbers)">{{ n }}</li>
</ul>
```

Faites attention à `reverse()` et `sort()` dans une propriété calculée ! Ces deux méthodes vont muter le tableau original, ce qui doit être évité dans des accesseurs calculés. Créez plutôt une copie du tableau original avant d'appeler ces méthodes :

```diff
- return numbers.reverse()
+ return [...numbers].reverse()
```

---

---
url: /guide/scaling-up/routing.md
---
# Routage {#routing}

## Routage côté client vs. côté serveur {#client-side-vs-server-side-routing}

Le routage côté serveur signifie que le serveur envoie une réponse basée sur le chemin URL que l'utilisateur visite. Lorsque nous cliquons sur un lien dans une application web traditionnelle à rendu serveur, le navigateur reçoit une réponse HTML du serveur et recharge la page entière avec le nouveau HTML.

Cependant, dans une [application monopage](https://developer.mozilla.org/fr/docs/Glossary/SPA) (SPA), le JavaScript côté client peut intercepter la navigation, récupérer dynamiquement de nouvelles données, et mettre à jour la page actuelle sans la recharger entièrement. Il en résulte généralement une expérience utilisateur plus rapide, en particulier pour les cas d'utilisation qui ressemblent davantage à des "applications" réelles, où l'utilisateur est censé effectuer de nombreuses interactions sur une longue période de temps.

Dans ces SPA, le "routage" est effectué côté client, dans le navigateur. Un routeur côté client est chargé de gérer la vue rendue de l'application à l'aide d'API de navigateur telles que [l'API History](https://developer.mozilla.org/fr/docs/Web/API/History) ou [l'événement `hashchange`](https://developer.mozilla.org/fr/docs/Web/API/Window/hashchange_event).

## Router officiel {#official-router}

Vue est bien adapté à la création de SPA. Pour la plupart des SPA, il est recommandé d'utiliser la [bibliothèque Vue Router](https://github.com/vuejs/router) officiellement supportée. Pour plus de détails, consultez la [documentation de Vue Router](https://router.vuejs.org/).

## Routage simple à partir de zéro {#simple-routing-from-scratch}

Si vous n'avez besoin que d'un routage très simple et que vous ne souhaitez pas utiliser une bibliothèque de routeurs complète, vous pouvez utiliser des [Composants dynamiques](/guide/essentials/component-basics#dynamic-components) et mettre à jour l'état actuel du composant en écoutant les [événements `hashchange`](https://developer.mozilla.org/fr/docs/Web/API/Window/hashchange_event) du navigateur ou en utilisant l'[API History](https://developer.mozilla.org/fr/docs/Web/API/History).

Voici un exemple concret :

```vue
<script setup>
import { ref, computed } from 'vue'
import Home from './Home.vue'
import About from './About.vue'
import NotFound from './NotFound.vue'

const routes = {
  '/': Home,
  '/about': About
}

const currentPath = ref(window.location.hash)

window.addEventListener('hashchange', () => {
  currentPath.value = window.location.hash
})

const currentView = computed(() => {
  return routes[currentPath.value.slice(1) || '/'] || NotFound
})
</script>

<template>
  <a href="#/">Home</a> |
  <a href="#/about">About</a> |
  <a href="#/non-existent-path">Broken Link</a>
  <component :is="currentView" />
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNptUk1vgkAQ/SsTegAThZp4MmhikzY9mKanXkoPWxjLRpgly6JN1P/eWb5Eywlm572ZN2/m5GyKwj9U6CydsIy1LAyUaKpiHZHMC6UNnEDjbgqxyovKYAIX2GmVg8sktwe9qhzbdz+wga15TW++VWX6fB3dAt6UeVEVJT2me2hhEcWKSgOamVjCCk4RAbiBu6xbT5tI2ML8VDeI6HLlxZXWSOZdmJTJPJB3lJSoo5+pWBipyE9FmU4soU2IJHk+MGUrS4OE2nMtIk4F/aA7BW8Cq3WjYlDbP4isQu4wVp0F1Q1uFH1IPDK+c9cb1NW8B03tyJ//uvhlJmP05hM4n60TX/bb2db0CoNmpbxMDgzmRSYMcgQQCkjZhlXkPASRs7YmhoFYw/k+WXvKiNrTcQgpmuFv7ZOZFSyQ4U9a7ZFgK2lvSTXFDqmIQbCUJTMHFkQOBAwKg16kM3W6O7K3eSs+nbeK+eee1V/XKK0dY4Q3vLhR6uJxMUK8/AFKaB6k)

```vue
<script>
import Home from './Home.vue'
import About from './About.vue'
import NotFound from './NotFound.vue'

const routes = {
  '/': Home,
  '/about': About
}

export default {
  data() {
    return {
      currentPath: window.location.hash
    }
  },
  computed: {
    currentView() {
      return routes[this.currentPath.slice(1) || '/'] || NotFound
    }
  },
  mounted() {
    window.addEventListener('hashchange', () => {
		  this.currentPath = window.location.hash
		})
  }
}
</script>

<template>
  <a href="#/">Home</a> |
  <a href="#/about">About</a> |
  <a href="#/non-existent-path">Broken Link</a>
  <component :is="currentView" />
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNptUstO6zAQ/ZVR7iKtVJKLxCpKK3Gli1ggxIoNZmGSKbFoxpEzoUi0/87YeVBKNonHPmfOmcdndN00yXuHURblbeFMwxtFpm6sY7i1NcLW2RriJPWBB8bT8/WL7Xh6D9FPwL3lG9tROWHGiwGmqLDUMjhhYgtr+FQEEKdxFqRXfaR9YrkKAoqOnocfQaDEre523PNKzXqx7M8ADrlzNEYAReccEj9orjLYGyrtPtnZQrOxlFS6rXqgZJdPUC5s3YivMhuTDCkeDe6/dSalvognrkybnIgl7c4UuLhcwuHgS3v2/7EPvzRruRXJ7/SDU12W/98l451pGQndIvaWi0rTK8YrEPx64ymKFQOce5DOzlfs4cdlkA+NzdNpBSRgrJudZpQIINdQOdyuVfQnVdHGzydP9QYO549hXIII45qHkKUL/Ail8EUjBgX+z9k3JLgz9OZJgeInYElAkJlWmCcDUBGkAsrTyWS0isYV9bv803x1OTiWwzlrWtxZ2lDGDO90mWepV3+vZojHL3QQKQE=)

---

---
url: /guide/best-practices/security.md
---
# Sécurité {#security}

## Signalement des vulnérabilités {#reporting-vulnerabilities}

Lorsqu'une vulnérabilité est signalée, elle devient immédiatement notre principale préoccupation, et un collaborateur à temps plein se concentre pour y remédier. Pour signaler une vulnérabilité, veuillez envoyer un mail à <security@vuejs.org>.

Bien que la découverte de nouvelles vulnérabilités soit rare, nous recommandons également de toujours utiliser les dernières versions de Vue et de ses bibliothèques annexes officielles pour garantir que votre application reste aussi sûre que possible.

## Règle n°1: N'utilisez jamais de templates non fiables {#rule-no-1-never-use-non-trusted-templates}

La règle de sécurité la plus fondamentale lorsque vous utilisez Vue est de **ne jamais utiliser de contenu non fiable comme template de composant**. Cela équivaut à autoriser l'exécution arbitraire de JavaScript dans votre application - et pire encore, cela pourrait entraîner des failles dans le serveur si le code est exécuté pendant le rendu côté serveur. Un exemple d'une telle utilisation :

```js
Vue.createApp({
  template: `<div>` + userProvidedString + `</div>` // NE JAMAIS FAIRE ÇA
}).mount('#app')
```

Les templates Vue sont compilés en JavaScript, et les expressions qui y sont contenues seront exécutées dans le cadre du processus de rendu. Bien que les expressions soient évaluées par rapport à un contexte de rendu spécifique, en raison de la complexité des environnements d'exécution globaux potentiels, il n'est pas possible pour un framework comme Vue de vous protéger complètement de l'exécution potentielle de code malveillant sans risquer une dégradation critique des performances. La façon la plus simple d'éviter complètement ce genre de problèmes est de s'assurer que le contenu de vos templates Vue est toujours fiable et que vous le contrôlez totalement.

## Ce que Vue fait pour vous protéger {#what-vue-does-to-protect-you}

### Contenu HTML {#html-content}

Que vous utilisiez des templates ou des fonctions de rendu, le contenu est automatiquement échappé. Cela signifie que dans ce template :

```vue-html
<h1>{{ userProvidedString }}</h1>
```

si `userProvidedString` contient :

```js
'<script>alert("hi")</script>'
```

alors il sera échappé en l'HTML suivant :

```vue-html
&lt;script&gt;alert(&quot;hi&quot;)&lt;/script&gt;
```

empêchant ainsi l'injection de script. Cet échappement est effectué en utilisant les API natives du navigateur, comme `textContent`, donc une vulnérabilité ne peut exister que si le navigateur lui-même est vulnérable.

### Liaisons d'attributs {#attribute-bindings}

De même, les liaisons d'attributs dynamiques sont automatiquement échappées. Cela signifie que dans ce template :

```vue-html
<h1 :title="userProvidedString">
  hello
</h1>
```

si `userProvidedString` contient :

```js
'" onclick="alert(\'hi\')'
```

alors il sera échappé en l'HTML suivant :

```vue-html
&quot; onclick=&quot;alert('hi')
```

empêchant ainsi la fermeture de l'attribut `title` pour injecter du nouveau HTML arbitraire. Cet échappement est effectué en utilisant les API natives du navigateur, comme `setAttribute`, donc une vulnérabilité ne peut exister que si le navigateur lui-même est vulnérable.

## Dangers potentiels {#potential-dangers}

Dans toute application Web, le fait d'autoriser l'exécution de contenu non nettoyé fourni par l'utilisateur sous forme d'HTML, de CSS ou de JavaScript est potentiellement dangereux et doit donc être évité dans la mesure du possible. Il y a cependant des cas où un certain risque peut être acceptable.

Par exemple, des services tels que CodePen et JSFiddle permettent l'exécution de contenu fourni par l'utilisateur, mais dans un contexte où cela est attendu et encadré dans une certaine mesure par des iframes. Dans les cas où une fonctionnalité importante nécessite intrinsèquement un certain niveau de vulnérabilité, il appartient à votre équipe d'évaluer l'importance de cette dernière par rapport aux pires scénarios qu'elle peut apporter.

### Injection HTML {#html-injection}

Comme vous l'avez appris précédemment, Vue échappe automatiquement le contenu HTML, ce qui vous empêche d'injecter accidentellement du HTML exécutable dans votre application. Cependant, **dans les cas où vous savez que le HTML est sûr**, vous pouvez rendre le contenu HTML de manière explicite :

* En utilisant un template :

  ```vue-html
  <div v-html="userProvidedHtml"></div>
  ```

* En utilisant une fonction de rendu :

  ```js
  h('div', {
    innerHTML: this.userProvidedHtml
  })
  ```

* En utilisant une fonction de rendu avec JSX :

  ```jsx
  <div innerHTML={this.userProvidedHtml}></div>
  ```

:::warning
Le HTML fourni par l'utilisateur ne peut jamais être considéré comme 100 % sûr, sauf s'il se trouve dans une iframe protégée enveloppée dans une sandbox ou dans une partie de l'application où seul l'utilisateur qui a écrit ce HTML peut y être exposé. En outre, permettre aux utilisateurs d'écrire leurs propres templates Vue présente des dangers similaires.
:::

### Injection d'URL {#url-injection}

Dans une URL comme celle-ci :

```vue-html
<a :href="userProvidedUrl">
  click me
</a>
```

Il existe un problème de sécurité potentiel si l'URL n'a pas été "nettoyée" pour empêcher l'exécution de JavaScript en utilisant `javascript:`. Il existe des bibliothèques telles que [sanitize-url](https://www.npmjs.com/package/@braintree/sanitize-url) pour vous aider dans cette tâche, mais attention : si vous effectuez le nettoyage des URL côté front-end, vous avez déjà un problème de sécurité. **Les URL fournies par l'utilisateur doivent toujours être nettoyées par votre backend avant même d'être enregistrées dans une base de données**. Le problème est alors évité pour *tous* les clients qui se connectent à votre API, y compris depuis les applications mobiles natives. Notez également que même avec des URL nettoyées, Vue ne peut pas vous aider à garantir qu'elles mènent à des destinations sûres.

### Injection de style {#style-injection}

Regardons cet exemple :

```vue-html
<a
  :href="sanitizedUrl"
  :style="userProvidedStyles"
>
  click me
</a>
```

Supposons que `sanitizedUrl` ait été nettoyée, de sorte qu'il s'agisse bien d'une véritable URL et non de JavaScript. Avec le `userProvidedStyles`, les utilisateurs malveillants peuvent toujours fournir du CSS pour "détourner le clic", par exemple en transformant le lien en une boîte transparente au-dessus du bouton "Se connecter". Ensuite, si `https://user-controlled-website.com/` est codé pour ressembler à la page de connexion de votre application, ils peuvent avoir capturé les véritables informations de connexion d'un utilisateur.

Vous pouvez peut-être imaginer comment le fait d'autoriser le contenu fourni par l'utilisateur pour un élément `<style>` créerait une vulnérabilité encore plus grande, en donnant à cet utilisateur un contrôle total sur la façon de styliser la page entière. C'est pourquoi Vue empêche le rendu des balises de style à l'intérieur des templates, comme :

```vue-html
<style>{{ userProvidedStyles }}</style>
```

Pour que vos utilisateurs soient totalement à l'abri du détournement de clic, nous vous recommandons de n'autoriser le contrôle total du CSS qu'à l'intérieur d'une iframe enveloppée dans une sandbox. Par ailleurs, lorsque vous offrez un contrôle à l'utilisateur via une liaison de style, nous vous recommandons d'utiliser sa [syntaxe objet](/guide/essentials/class-and-style#binding-to-objects-1) et de n'autoriser les utilisateurs à fournir des valeurs que pour des propriétés spécifiques qu'ils peuvent contrôler en toute sécurité, comme ceci :

```vue-html
<a
  :href="sanitizedUrl"
  :style="{
    color: userProvidedColor,
    background: userProvidedBackground
  }"
>
  click me
</a>
```

### Injection JavaScript {#javascript-injection}

Nous déconseillons fortement de rendre un élément `<script>` avec Vue, car les templates et les fonctions de rendu ne devraient jamais avoir d'effets de bord. Cependant, ce n'est pas la seule façon d'inclure des chaînes de caractères qui peuvent être évaluées comme du JavaScript au moment de l'exécution.

Chaque élément HTML possède des attributs dont les valeurs acceptent des chaînes de caractères JavaScript, comme `onclick`, `onfocus` et `onmouseenter`. Lier du JavaScript fourni par l'utilisateur à l'un de ces attributs d'événement constitue un risque potentiel pour la sécurité et doit donc être évité.

:::warning
Le JavaScript fourni par l'utilisateur ne peut jamais être considéré comme 100 % sûr, sauf s'il se trouve dans une iframe protégée enveloppée dans une sandbox ou dans une partie de l'application où seul l'utilisateur qui a écrit ce JavaScript peut y être exposé.
:::

Nous recevons parfois des rapports de vulnérabilité sur la façon dont il est possible de faire du cross-site scripting (XSS) dans les templates Vue. En général, nous ne considérons pas ces cas comme de véritables vulnérabilités car il n'existe aucun moyen pratique de protéger les développeurs contre les deux scénarios qui permettraient le XSS :

1. Le développeur demande explicitement à Vue de rendre le contenu fourni par l'utilisateur, non nettoyé, sous forme de templates Vue. Ceci est intrinsèquement dangereux, et Vue n'a aucun moyen de connaître la source.

2. Le développeur monte Vue sur une page HTML entière qui contient du contenu rendu par le serveur et fourni par l'utilisateur. Il s'agit fondamentalement du même problème que le point #1, mais les développeurs peuvent parfois le faire sans s'en rendre compte. Cela peut conduire à des vulnérabilités où l'attaquant fournit du HTML qui est sûr en tant que HTML ordinaire mais qui ne l'est pas en tant que template Vue. La meilleure pratique est de **ne jamais monter Vue sur des nœuds qui peuvent contenir du contenu rendu par le serveur et fourni par l'utilisateur**.

## Bonne pratiques {#best-practices}

La règle générale est que si vous autorisez l'exécution d'un contenu non nettoyé fourni par l'utilisateur (HTML, JavaScript ou même CSS), vous vous exposez à des attaques. Ce conseil est valable que vous utilisiez Vue, un autre framework ou même aucun framework.

Outre les recommandations formulées ci-dessus concernant les [dangers potentiels](#potential-dangers), nous vous recommandons également de vous familiariser avec ces ressources :

* [Aide-mémoire sur la sécurité HTML5](https://html5sec.org/)
* [Aide-mémoire de l'OWASP sur la prévention du Cross Site Scripting (XSS)](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)

Profitez ensuite de ce que vous avez appris pour examiner le code source de vos dépendances afin d'y déceler des modèles potentiellement dangereux, si l'un d'entre eux inclut des composants tiers ou influence de quelque manière que ce soit le rendu dans le DOM.

## Coordination avec le backend {#backend-coordination}

Les vulnérabilités de sécurité HTTP, telles que la falsification des requêtes inter-sites (CSRF/XSRF) et l'inclusion de scripts inter-sites (XSSI), sont principalement traitées au niveau du backend, et ne sont donc pas une préoccupation de Vue. Cependant, il est toujours bon de communiquer avec votre équipe backend pour apprendre comment interagir au mieux avec leur API, par exemple en soumettant des jetons CSRF pour les soumissions de formulaires.

## Rendu côté serveur (SSR) {#server-side-rendering-ssr}

L'utilisation de SSR pose quelques problèmes de sécurité supplémentaires. Veillez donc à suivre les meilleures pratiques décrites dans [notre documentation SSR](/guide/scaling-up/ssr) pour éviter les vulnérabilités.

---

---
url: /api/sfc-css-features.md
---
# SFC CSS Features {#sfc-css-features}

## CSS à portée limitée {#scoped-css}

Lorsqu'une balise `<style>` possède l'attribut `scoped`, son CSS s'appliquera uniquement aux éléments du composant actuel. Cela est comparable à l'encapsulation des styles que l'on trouve dans le Shadow DOM. Il y a cependant quelques mises en gardes, mais cela ne nécessite aucun polyfill. PostCSS est utilisé pour transformer les éléments suivants :

```vue
<style scoped>
.example {
  color: red;
}
</style>

<template>
  <div class="example">hi</div>
</template>
```

En ce qui suit :

```vue
<style>
.example[data-v-f3f3eg9] {
  color: red;
}
</style>

<template>
  <div class="example" data-v-f3f3eg9>hi</div>
</template>
```

### Éléments racines du composant enfant {#child-component-root-elements}

Avec `scoped`, les styles du composant parent ne ruisselleront pas dans les composants enfants. Toutefois, le nœud racine d'un composant enfant sera affecté à la fois par le CSS à portée limitée du parent et par le CSS à portée limitée de l'enfant. Cela a été conçu afin que le parent puisse donner un style à l'élément racine de l'enfant à des fins de mise en page.

### Sélecteurs profonds {#deep-selectors}

Si vous voulez qu'un sélecteur dans les styles `scoped` soit "profond", c'est-à-dire qu'il affecte les composants enfants, vous pouvez utiliser la pseudo-classe `:deep()` :

```vue
<style scoped>
.a :deep(.b) {
  /* ... */
}
</style>
```

Le code ci-dessus sera compilé en :

```css
.a[data-v-f3f3eg9] .b {
  /* ... */
}
```

:::tip
Les contenus du DOM créés avec `v-html` ne sont pas affectés par les styles à portée limitée, mais vous pouvez tout de même les styliser en utilisant des sélecteurs profonds.
:::

### Sélecteurs de slots {#slotted-selectors}

Par défaut, les styles à portée limitée n'affectent pas les contenus rendus par `<slot/>`, car ils sont considérés comme appartenant au composant parent qui les transmet. Pour cibler explicitement le contenu des slots, utilisez la pseudo-classe `:slotted` :

```vue
<style scoped>
:slotted(div) {
  color: red;
}
</style>
```

### Sélecteurs globaux {#global-selectors}

Si vous voulez qu'une seule règle s'applique de manière globale, vous pouvez utiliser la pseudo-classe `:global` plutôt que de créer un autre `<style>` (voir ci-dessous) :

```vue
<style scoped>
:global(.red) {
  color: red;
}
</style>
```

### Mélanger les styles locaux et globaux {#mixing-local-and-global-styles}

Vous pouvez également inclure des styles généraux et d'autres à portée limitée dans le même composant :

```vue
<style>
/* styles globaux */
</style>

<style scoped>
/* styles locaux */
</style>
```

### Conseils concernant les styles à portée limitée {#scoped-style-tips}

* **Les styles à portée limitée ne rendent pas les classes inutiles**. En raison de la façon dont les navigateurs rendent les différents sélecteurs CSS, `p { color : red }` sera bien plus lent lorsqu'il a une portée limitée (c'est-à-dire lorsqu'il est combiné avec un sélecteur d'attribut). Si vous utilisez des classes ou des identifiants à la place, comme dans `.example { color : red }`, vous éliminez en grande partie ce problème de performances.

* **Faites attention aux sélecteurs descendants dans les composants récursifs!** Pour une règle CSS avec le sélecteur `.a .b`, si l'élément qui correspond à `.a` contient un composant enfant récursif, alors tous les `.b` de ce composant enfant seront pris en compte par la règle.

## Modules CSS {#css-modules}

Une balise `<style module>` est compilée en tant que [modules CSS](https://github.com/css-modules/css-modules) et expose les classes CSS résultantes au composant en tant qu'objet via la clé `$style` :

```vue
<template>
  <p :class="$style.red">This should be red</p>
</template>

<style module>
.red {
  color: red;
}
</style>
```

Les classes qui en résultent sont hachées pour éviter les collisions, ce qui permet d'obtenir le même effet que de limiter la portée du CSS au seul composant actuel.

Consultez la [spécification des modules CSS](https://github.com/css-modules/css-modules) pour plus de détails, notamment les parties sur les [exceptions globales](https://github.com/css-modules/css-modules/blob/master/docs/composition.md#exceptions) et la [composition](https://github.com/css-modules/css-modules/blob/master/docs/composition.md#composition).

### Nom d'injection personnalisé {#custom-inject-name}

Vous pouvez personnaliser la clé de propriété de l'objet de classes injectées en donnant une valeur à l'attribut `module` :

```vue
<template>
  <p :class="classes.red">red</p>
</template>

<style module="classes">
.red {
  color: red;
}
</style>
```

### Utilisation avec la Composition API {#usage-with-composition-api}

Les classes injectées sont accessibles dans `setup()` et `<script setup>` via l'API `useCssModule`. Pour les blocs `<style module>` avec des noms d'injection personnalisés, `useCssModule` accepte la valeur de l'attribut `module` correspondant comme premier argument :

```js
import { useCssModule } from 'vue'

// à l'intérieur de setup()...
// par défaut, renvoie les classes pour <style module>
useCssModule()

// nommé, renvoie les classes pour <style module="classes">
useCssModule('classes')
```

* **Exemple**

```vue
<script setup lang="ts">
import { useCssModule } from 'vue'

const classes = useCssModule()
</script>

<template>
  <p :class="classes.red">rouge</p>
</template>

<style module>
.red {
  color: red;
}
</style>
```

## `v-bind()` dans du CSS {#v-bind-in-css}

Les balises `<style>` des composants monopages permettent de lier les valeurs CSS à l'état dynamique des composants à l'aide de la fonction CSS `v-bind` :

```vue
<template>
  <div class="text">hello</div>
</template>

<script>
export default {
  data() {
    return {
      color: 'red'
    }
  }
}
</script>

<style>
.text {
  color: v-bind(color);
}
</style>
```

La syntaxe fonctionne avec [`<script setup>`](./sfc-script-setup), et prend en charge les expressions JavaScript (qui doivent être placées entre guillemets) :

```vue
<script setup>
import { ref } from 'vue'
const theme = ref({
    color: 'red',
})
</script>

<template>
  <p>hello</p>
</template>

<style scoped>
p {
  color: v-bind('theme.color');
}
</style>
```

La valeur réelle sera compilée dans une propriété personnalisée CSS hachée, afin que le CSS reste statique. La propriété personnalisée sera appliquée à l'élément racine du composant via des styles en ligne et mise à jour de manière réactive si la valeur source change.

---

---
url: /guide/components/slots.md
---
# Slots {#slots}

> Cette page suppose que vous avez déjà lu les [bases à propos des composants](/guide/essentials/component-basics). Lisez-les d'abord si vous débutez avec les composants.

## Les contenus de slot {#slot-content-and-outlet}

Nous avons appris que les composants peuvent accepter des props, qui peuvent être des valeurs JavaScript de n'importe quel type. Mais qu'en est-il du contenu du template ? Dans certains cas, nous pouvons vouloir transmettre un fragment de template à un composant enfant et laisser le composant enfant afficher le fragment dans son propre template.

Par exemple, nous pouvons avoir un composant `<FancyButton>` qui prend en charge l'utilisation suivante :

```vue-html{2}
<FancyButton>
  Click me! <!-- contenu du slot -->
</FancyButton>
```

Le template de `<FancyButton>` ressemble à ceci :

```vue-html{2}
<button class="fancy-btn">
  <slot></slot> <!-- emplacement du slot -->
</button>
```

L'élément `<slot>` est un **emplacement du slot** qui indique où le **contenu du slot** fourni par le parent doit être affiché.

![slot diagram](./images/slots.png)

Et le DOM rendu final :

```html
<button class="fancy-btn">Click me!</button>
```

[Essayer en ligne](https://play.vuejs.org/#eNpdUdlqAyEU/ZVbQ0kLMdNsXabTQFvoV8yLcRkkjopLSQj596oTwqRvnuM9y9UT+rR2/hs5qlHjqZM2gOch2m2rZW+NC/BDND1+xRCMBuFMD9N5NeKyeNrqphrUSZdA4L1VJPCEAJrRdCEAvpWke+g5NHcYg1cmADU6cB0A4zzThmYckqimupqiGfpXILe/zdwNhaki3n+0SOR5vAu6ReU++efUajtqYGJQ/FIg5w8Wt9FlOx+OKh/nV1c4ZVNqlHE1TIQQ7xnvCN13zkTNalBSc+Jw5wiTac2H1WLDeDeDyXrJVm9LWG7uE3hev3AhHge1cYwnO200L4QljEnd1bCxB1g82UNhe+I6qQs5kuGcE30NrxeaRudzOWtkemeXuHP5tLIKOv8BN+mw3w==)

[Essayer en ligne](https://play.vuejs.org/#eNpdUdtOwzAM/RUThAbSurIbl1ImARJf0ZesSapoqROlKdo07d9x0jF1SHmIT+xzcY7sw7nZTy9Zwcqu9tqFTYW6ddYH+OZYHz77ECyC8raFySwfYXFsUiFAhXKfBoRUvDcBjhGtLbGgxNAVcLziOlVIp8wvelQE2TrDg6QKoBx1JwDgy+h6B62E8ibLoDM2kAAGoocsiz1VKMfmCCrzCymbsn/GY95rze1grja8694rpmJ/tg1YsfRO/FE134wc2D4YeTYQ9QeKa+mUrgsHE6+zC+vfjoz1Bdwqpd5iveX1rvG2R1GA0Si5zxrPhaaY98v5WshmCrerhVi+LmCxvqPiafUslXoYpq0XkuiQ1p4Ax4XQ2BSwdnuYP7p9QlvuG40JHI1lUaenv3o5w3Xvu2jOWU179oQNn5aisNMvLBvDOg==)

Avec les slots, le `<FancyButton>` est responsable du rendu du `<button>` externe (et de son style), tandis que le contenu interne est fourni par le composant parent.

Une autre façon de comprendre les slots consiste à les comparer aux fonctions JavaScript :

```js
// composant parent passant le contenu du slot
FancyButton('Click me!')

// FancyButton effectue le rendu du contenu du slot dans son propre template
function FancyButton(slotContent) {
  return `<button class="fancy-btn">
      ${slotContent}
    </button>`
}
```

Le contenu du slot ne se limite pas à du texte. Il peut s'agir de n'importe quel contenu de template valide. Par exemple, nous pouvons passer plusieurs éléments, voire d'autres composants :

```vue-html
<FancyButton>
  <span style="color:red">Click me!</span>
  <AwesomeIcon name="plus" />
</FancyButton>
```

[Essayer en ligne](https://play.vuejs.org/#eNp1UmtOwkAQvspQYtCEgrx81EqCJibeoX+W7bRZaHc3+1AI4QyewH8ewvN4Aa/gbgtNIfFf5+vMfI/ZXbCQcvBmMYiCWFPFpAGNxsp5wlkphTLwQjjdPlljBIdMiRJ6g2EL88O9pnnxjlqU+EpbzS3s0BwPaypH4gqDpSyIQVcBxK3VFQDwXDC6hhJdlZi4zf3fRKwl4aDNtsDHJKCiECqiW8KTYH5c1gEnwnUdJ9rCh/XeM6Z42AgN+sFZAj6+Ux/LOjFaEK2diMz3h0vjNfj/zokuhPFU3lTdfcpShVOZcJ+DZgHs/HxtCrpZlj34eknoOlfC8jSCgnEkKswVSRlyczkZzVLM+9CdjtPJ/RjGswtX3ExvMcuu6mmhUnTruOBYAZKkKeN5BDO5gdG13FRoSVTOeAW2xkLPY3UEdweYWqW9OCkYN6gctq9uXllx2Z09CJ9dJwzBascI7nBYihWDldUGMqEgdTVIq6TQqCEMfUpNSD+fX7/fH+3b7P8AdGP6wA==)

[Essayer en ligne](https://play.vuejs.org/#eNptUltu2zAQvMpGQZEWsOzGiftQ1QBpgQK9g35oaikwkUiCj9aGkTPkBPnLIXKeXCBXyJKKBdoIoA/tYGd3doa74tqY+b+ARVXUjltp/FWj5GC09fCHKb79FbzXCoTVA5zNFxkWaWdT8/V/dHrAvzxrzrC3ZoBG4SYRWhQs9B52EeWapihU3lWwyxfPDgbfNYq+ejEppcLjYHrmkSqAOqMmAOB3L/ktDEhV4+v8gMR/l1M7wxQ4v+3xZ1Nw3Wtb8S1TTXG1H3cCJIO69oxc5mLUcrSrXkxSi1lxZGT0//CS9Wg875lzJELE/nLto4bko69dr31cFc8auw+3JHvSEfQ7nwbsHY9HwakQ4kes14zfdlYH1VbQS4XMlp1lraRMPl6cr1rsZnB6uWwvvi9hufpAxZfLryjEp5GtbYs0TlGICTCsbaXqKliZDZx/NpuEDsx2UiUwo5VxT6Dkv73BPFgXxRktlUdL2Jh6OoW8O3pX0buTsoTgaCNQcDjoGwk3wXkQ2tJLGzSYYI126KAso0uTSc8Pjy9P93k2d6+NyRKa)

En utilisant des slots, notre `<FancyButton>` est plus flexible et réutilisable. Nous pouvons maintenant l'utiliser à différents endroits avec un contenu différent, mais tous avec le même style appliqué.

Le mécanisme de slot des composants Vue est inspiré de l'[élément natif Web Component `<slot>`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/slot), mais avec des fonctionnalités supplémentaires que nous verrons plus tard.

## Portée du rendu {#render-scope}

Le contenu du slot a accès à la portée des données du composant parent, car il est défini dans le parent. Par exemple :

```vue-html
<span>{{ message }}</span>
<FancyButton>{{ message }}</FancyButton>
```

Ici, les deux interpolations `{{ message }}` rendront le même contenu.

Le contenu du slot **n'a pas** accès aux données du composant enfant. Les expressions dans les templates Vue ne peuvent accéder qu'à la portée de déclaration dans laquelle elles sont définies, conformément à la portée lexicale de JavaScript. Autrement dit :

> Les expressions présentes dans le template du parent n'ont accès qu'à la portée du parent ; les expressions dans le template de l'enfant n'ont accès qu'à la portée du composant enfant.

## Contenu par défaut {#fallback-content}

Il existe des cas où il est utile de spécifier un contenu par défaut pour un slot, à rendre uniquement lorsqu'aucun contenu n'est fourni. Par exemple, dans un composant `<SubmitButton>` :

```vue-html
<button type="submit">
  <slot></slot>
</button>
```

Nous pourrions souhaiter que le texte "Submit" soit rendu à l'intérieur du `<button>` si le parent n'a fourni aucun contenu pour le slot. Pour faire de "Submit" le contenu par défaut, nous pouvons le placer entre les balises `<slot>` :

```vue-html{3}
<button type="submit">
  <slot>
    Submit <!-- contenu par défaut -->
  </slot>
</button>
```

Maintenant, lorsque nous utilisons `<SubmitButton>` dans un composant parent, en ne fournissant aucun contenu pour le slot :

```vue-html
<SubmitButton />
```

Cela rendra le contenu par défaut, "Submit":

```html
<button type="submit">Submit</button>
```

Mais si nous fournissons le contenu :

```vue-html
<SubmitButton>Save</SubmitButton>
```

Alors, le contenu fourni sera affiché à la place :

```html
<button type="submit">Save</button>
```

[Essayer en ligne](https://play.vuejs.org/#eNp1kMsKwjAQRX9lzMaNbfcSC/oL3WbT1ikU8yKZFEX8d5MGgi2YVeZxZ86dN7taWy8B2ZlxP7rZEnikYFuhZ2WNI+jCoGa6BSKjYXJGwbFufpNJfhSaN1kflTEgVFb2hDEC4IeqguARpl7KoR8fQPgkqKpc3Wxo1lxRWWeW+Y4wBk9x9V9d2/UL8g1XbOJN4WAntodOnrecQ2agl8WLYH7tFyw5olj10iR3EJ+gPCxDFluj0YS6EAqKR8mi9M3Td1ifLxWShcU=)

[Essayer en ligne](https://play.vuejs.org/#eNp1UEEOwiAQ/MrKxYu1d4Mm+gWvXChuk0YKpCyNxvh3lxIb28SEA8zuDDPzEucQ9mNCcRAymqELdFKu64MfCK6p6Tu6JCLvoB18D9t9/Qtm4lY5AOXwMVFu2OpkCV4ZNZ51HDqKhwLAQjIjb+X4yHr+mh+EfbCakF8AclNVkCJCq61ttLkD4YOgqsp0YbGesJkVBj92NwSTIrH3v7zTVY8oF8F4SdazD7ET69S5rqXPpnigZ8CjEnHaVyInIp5G63O6XIGiIlZMzrGMd8RVfR0q4lIKKV+L+srW+wNTTZq3)

## Slots nommés {#named-slots}

Il y a des moments où il est utile d'avoir plusieurs emplacements de slot dans un seul composant. Par exemple, dans un composant `<BaseLayout>` avec le template suivant :

```vue-html
<div class="container">
  <header>
    <!-- Nous voulons le contenu du header ici -->
  </header>
  <main>
    <!-- Nous voulons le contenu principal ici -->
  </main>
  <footer>
    <!-- Nous voulons le contenu du footer ici -->
  </footer>
</div>
```

Dans ces cas, l'élément `<slot>` a un attribut spécial, `name`, qui peut être utilisé pour attribuer un ID unique à différents slots afin que vous puissiez déterminer où le contenu doit être affiché :

```vue-html
<div class="container">
  <header>
    <slot name="header"></slot>
  </header>
  <main>
    <slot></slot>
  </main>
  <footer>
    <slot name="footer"></slot>
  </footer>
</div>
```

Une balise `<slot>` sans attribut `name` porte implicitement le nom "default".

Dans un composant parent utilisant `<BaseLayout>`, nous avons besoin d'un moyen de transmettre plusieurs fragments de contenu de slot, chacun ciblant un emplacement de slot différent. C'est là qu'interviennent les **slots nommés**.

Pour passer un slot nommé, nous devons utiliser un élément `<template>` avec la directive `v-slot`, puis passer le nom du slot comme argument à `v-slot` :

```vue-html
<BaseLayout>
  <template v-slot:header>
    <!-- contenu pour le slot header -->
  </template>
</BaseLayout>
```

`v-slot` a un raccourci dédié `#`, donc `<template v-slot:header>` peut être raccourci en juste `<template #header>`. Pensez-y comme "rendre ce fragment de template dans le slot 'header' du composant enfant".

![named slots diagram](./images/named-slots.png)

Voici le code transmettant le contenu des trois slots à `<BaseLayout>` en utilisant la syntaxe abrégée :

```vue-html
<BaseLayout>
  <template #header>
    <h1>Here might be a page title</h1>
  </template>

  <template #default>
    <p>A paragraph for the main content.</p>
    <p>And another one.</p>
  </template>

  <template #footer>
    <p>Here's some contact info</p>
  </template>
</BaseLayout>
```

Lorsqu'un composant accepte à la fois un emplacement par défaut et des emplacements nommés, tous les nœuds de niveau supérieur non `<template>` sont implicitement traités comme du contenu pour le slot par défaut. Donc ce qui précède peut aussi s'écrire :

```vue-html
<BaseLayout>
  <template #header>
    <h1>Here might be a page title</h1>
  </template>

  <!-- slot par défaut implicite -->
  <p>A paragraph for the main content.</p>
  <p>And another one.</p>

  <template #footer>
    <p>Here's some contact info</p>
  </template>
</BaseLayout>
```

Désormais, tout ce qui se trouve à l'intérieur des éléments `<template>` sera transmis aux slots correspondants. Le rendu HTML final sera :

```html
<div class="container">
  <header>
    <h1>Here might be a page title</h1>
  </header>
  <main>
    <p>A paragraph for the main content.</p>
    <p>And another one.</p>
  </main>
  <footer>
    <p>Here's some contact info</p>
  </footer>
</div>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9UsFuwjAM/RWrHLgMOi5o6jIkdtphn9BLSF0aKU2ixEVjiH+fm8JoQdvRfu/5xS8+ZVvvl4cOsyITUQXtCSJS5zel1a13geBdRvyUR9cR1MG1MF/mt1YvnZdW5IOWVVwQtt5IQq4AxI2cau5ccZg1KCsMlz4jzWrzgQGh1fuGYIcgwcs9AmkyKHKGLyPykcfD1Apr2ZmrHUN+s+U5Qe6D9A3ULgA1bCK1BeUsoaWlyPuVb3xbgbSOaQGcxRH8v3XtHI0X8mmfeYToWkxmUhFoW7s/JvblJLERmj1l0+T7T5tqK30AZWSMb2WW3LTFUGZXp/u8o3EEVrbI9AFjLn8mt38fN9GIPrSp/p4/Yoj7OMZ+A/boN9KInPeZZpAOLNLRDAsPZDgN4p0L/NQFOV/Ayn9x6EZXMFNKvQ4E5YwLBczW6/WlU3NIi6i/sYDn5Qu2qX1OF51MsvMPkrIEHg==)

[Essayer en ligne](https://play.vuejs.org/#eNp9UkFuwjAQ/MoqHLiUpFxQlaZI9NRDn5CLSTbEkmNb9oKgiL934wRwQK3ky87O7njGPicba9PDHpM8KXzlpKV1qWVnjSP4FB6/xcnsCRpnOpin2R3qh+alBig1HgO9xkbsFcG5RyvDOzRq8vkAQLSury+l5lNkN1EuCDurBCFXAMWdH2pGrn2YtShqdCPOnXa5/kKH0MldS7BFEGDFDoEkKSwybo8rskjjaevo4L7Wrje8x4mdE7aFxjiglkWE1GxQE9tLi8xO+LoGoQ3THLD/qP2/dGMMxYZs8DP34E2HQUxUBFI35o+NfTlJLOomL8n04frXns7W8gCVEt5/lElQkxpdmVyVHvP2yhBo0SHThx5z+TEZvl1uMlP0oU3nH/kRo3iMI9Ybes960UyRsZ9pBuGDeTqpwfBAvn7NrXF81QUZm8PSHjl0JWuYVVX1PhAqo4zLYbZarUak4ZAWXv5gDq/pG3YBHn50EEkuv5irGBk=)

Encore une fois, cela peut vous aider à mieux comprendre les slots nommés en utilisant l'analogie avec une fonction JavaScript :

```js
// passage de plusieurs fragments de slot avec des noms différents
BaseLayout({
  header: `...`,
  default: `...`,
  footer: `...`
})

// <BaseLayout> les affiche à différents emplacements
function BaseLayout(slots) {
  return `<div class="container">
      <header>${slots.header}</header>
      <main>${slots.default}</main>
      <footer>${slots.footer}</footer>
    </div>`
}
```

## Slots conditionnels {#conditional-slots}

Il arrive que l'on veuille rendre quelque chose en fonction de la transmission ou non d'un contenu à un slot.

Vous pouvez utiliser la propriété [$slots](/api/component-instance.html#slots) en combinaison avec un [v-if](/guide/essentials/conditional.html#v-if) pour y parvenir.

Dans l'exemple ci-dessous, nous définissons un composant Card avec trois slots conditionnels : `header`, `footer` et `default`.
Lorsque l'en-tête / le pied de page / du texte par défaut est présent, nous voulons l'envelopper pour lui donner un style supplémentaire :

```vue-html
<template>
  <div class="card">
    <div v-if="$slots.header" class="card-header">
      <slot name="header" />
    </div>

    <div v-if="$slots.default" class="card-content">
      <slot />
    </div>

    <div v-if="$slots.footer" class="card-footer">
      <slot name="footer" />
    </div>
  </div>
</template>
```

[Essayer en ligne](https://play.vuejs.org/#eNqVVMtu2zAQ/BWCLZBLIjVoTq4aoA1yaA9t0eaoCy2tJcYUSZCUKyPwv2dJioplOw4C+EDuzM4+ONYT/aZ1tumBLmhhK8O1IxZcr29LyTutjCN3zNRkZVRHLrLcXzz9opRFHvnIxIuDTgvmAG+EFJ4WTnhOCPnQAqvBjHFE2uvbh5Zbgj/XAolwkWN4TM33VI/UalixXvjyo5yeqVVKOpCuyP0ob6utlHL7vUE3U4twkWP4hJq/jiPP4vSSOouNrHiTPVolcclPnl3SSnWaCzC/teNK2pIuSEA8xoRQ/3+GmDM9XKZ41UK1PhF/tIOPlfSPAQtmAyWdMMdMAy7C9/9+wYDnCexU3QtknwH/glWi9z1G2vde1tj2Hi90+yNYhcvmwd4PuHabhvKNeuYu8EuK1rk7M/pLu5+zm5BXyh1uMdnOu3S+95pvSCWYtV9xQcgqaXogj2yu+AqBj1YoZ7NosJLOEq5S9OXtPZtI1gFSppx8engUHs+vVhq9eVhq9ORRrXdpRyseSqfo6SmmnONK6XTw9yis24q448wXSG+0VAb3sSDXeiBoDV6TpWDV+ktENatrdMGCfAoBfL1JYNzzpINJjVFoJ9yKUKho19ul6OFQ6UYPx1rjIpPYeXIc/vXCgjetawzbni0dPnhhJ3T3DMVSruI=)

## Noms de slot dynamiques {#dynamic-slot-names}

[Les arguments de directive dynamique](/guide/essentials/template-syntax.md#dynamic-arguments) fonctionnent également sur `v-slot`, permettant la définition de noms de slots dynamiques :

```vue-html
<base-layout>
  <template v-slot:[dynamicSlotName]>
    ...
  </template>

  <!-- avec syntaxe abrégée -->
  <template #[dynamicSlotName]>
    ...
  </template>
</base-layout>
```

Notez que l'expression est soumise aux [contraintes de syntaxe](/guide/essentials/template-syntax.md#dynamic-argument-syntax-constraints) des arguments de directive dynamiques.

## Scoped Slots {#scoped-slots}

Comme indiqué dans [Portée du rendu](#render-scope), le contenu du slot n'a pas accès à l'état dans le composant enfant.

Cependant, il existe des cas où il peut être utile que le contenu d'un slot puisse utiliser des données provenant à la fois de la portée du parent et de la portée de l'enfant. Pour y parvenir, nous avons besoin d'un moyen pour l'enfant de transmettre des données à un slot pour son affichage.

En fait, nous pouvons faire exactement cela - nous pouvons transmettre des attributs à un emplacement de slot comme on transmettrait des props à un composant :

```vue-html
<!-- template de <MyComponent> -->
<div>
  <slot :text="greetingMessage" :count="1"></slot>
</div>
```

La réception des props de slot est un peu différente lorsque vous utilisez un seul slot par défaut par rapport à l'utilisation de slots nommés. Nous allons d'abord montrer comment recevoir des props en utilisant un seul slot par défaut, en utilisant `v-slot` directement sur la balise du composant enfant :

```vue-html
<MyComponent v-slot="slotProps">
  {{ slotProps.text }} {{ slotProps.count }}
</MyComponent>
```

![scoped slots diagram](./images/scoped-slots.svg)

[Essayer en ligne](https://play.vuejs.org/#eNp9kMEKgzAMhl8l9OJlU3aVOhg7C3uAXsRlTtC2tFE2pO++dA5xMnZqk+b/8/2dxMnadBxQ5EL62rWWwCMN9qh021vjCMrn2fBNoya4OdNDkmarXhQnSstsVrOOC8LedhVhrEiuHca97wwVSsTj4oz1SvAUgKJpgqWZEj4IQoCvZm0Gtgghzss1BDvIbFkqdmID+CNdbbQnaBwitbop0fuqQSgguWPXmX+JePe1HT/QMtJBHnE51MZOCcjfzPx04JxsydPzp2Szxxo7vABY1I/p)

[Essayer en ligne](https://play.vuejs.org/#eNqFkNFqxCAQRX9l8CUttAl9DbZQ+rzQD/AlJLNpwKjoJGwJ/nvHpAnusrAg6FzHO567iE/nynlCUQsZWj84+lBmGJ31BKffL8sng4bg7O0IRVllWnpWKAOgDF7WBx2em0kTLElt975QbwLkhkmIyvCS1TGXC8LR6YYwVSTzH8yvQVt6VyJt3966oAR38XhaFjjEkvBCECNcia2d2CLyOACZQ7CDrI6h4kXcAF7lcg+za6h5et4JPdLkzV4B9B6RBtOfMISmxxqKH9TarrGtATxMgf/bDfM/qExEUCdEDuLGXAmoV06+euNs2JK7tyCrzSNHjX9aurQf)

Les props passés au slot par l'enfant sont disponibles en tant que valeur de la directive `v-slot` correspondante, accessible par les expressions à l'intérieur du slot.

Vous pouvez considérer un "scoped slot" comme une fonction transmise au composant enfant. Le composant enfant l'appelle ensuite, en passant des props comme arguments :

```js
MyComponent({
  // passage du slot par défaut, mais en tant que fonction
  default: (slotProps) => {
    return `${slotProps.text} ${slotProps.count}`
  }
})

function MyComponent(slots) {
  const greetingMessage = 'hello'
  return `<div>${
    // appel de la fonction slot avec les props !
    slots.default({ text: greetingMessage, count: 1 })
  }</div>`
}
```

En fait, c'est très proche de la façon dont les "scoped slots" sont compilés et de la façon dont vous utiliseriez les "scoped slots" dans les [fonctions de rendu](/guide/extras/render-function) manuelles.

Remarquez comment `v-slot="slotProps"` correspond à la signature de la fonction slot. Tout comme avec les arguments de fonction, nous pouvons utiliser la déstructuration dans `v-slot` :

```vue-html
<MyComponent v-slot="{ text, count }">
  {{ text }} {{ count }}
</MyComponent>
```

### Scoped slots nommés {#named-scoped-slots}

Les Scoped slots nommés fonctionnent de la même manière - les props du slot sont accessibles en tant que valeur de la directive `v-slot` : `v-slot:name="slotProps"`. Lorsque vous utilisez le raccourci, cela ressemble à ceci :

```vue-html
<MyComponent>
  <template #header="headerProps">
    {{ headerProps }}
  </template>

  <template #default="defaultProps">
    {{ defaultProps }}
  </template>

  <template #footer="footerProps">
    {{ footerProps }}
  </template>
</MyComponent>
```

Passer des props à un slot nommé :

```vue-html
<slot name="header" message="hello"></slot>
```

Notez que l'attribut `name` d'un slot ne sera pas inclus dans les props car il est réservé - donc le `headerProps` résultant serait `{ message: 'hello' }`.

Si vous mélangez des slots nommés avec des "scoped slots" par défaut, vous devez utiliser une balise `<template>` explicite pour le slot par défaut. Tenter de placer la directive `v-slot` directement sur le composant entraînera une erreur de compilation. Ceci afin d'éviter toute ambiguïté sur la portée des props du slot par défaut. Par exemple :

```vue-html
<!-- <MyComponent> template -->
<div>
  <slot :message="hello"></slot>
  <slot name="footer" />
</div>
```

```vue-html
<!-- Ce template ne compilera pas -->
<MyComponent v-slot="{ message }">
  <p>{{ message }}</p>
  <template #footer>
    <!-- message appartient au slot par défaut, et n'est pas disponible ici -->
    <p>{{ message }}</p>
  </template>
</MyComponent>
```

L'utilisation explicite d'une balise `<template>` pour le slot par défaut aide à indiquer clairement que la prop `message` n'est pas disponible dans l'autre slot :

```vue-html
<MyComponent>
  <!-- Utiliser un slot par défaut explicit -->
  <template #default="{ message }">
    <p>{{ message }}</p>
  </template>

  <template #footer>
    <p>Here's some contact info</p>
  </template>
</MyComponent>
```

### Exemple Fancy List {#fancy-list-example}

Vous vous demandez peut-être quel serait un bon cas d'utilisation pour les scoped slots. Voici un exemple : imaginez un composant `<FancyList>` qui affiche une liste d'éléments - il peut encapsuler la logique de chargement des données distantes, utiliser les données pour afficher une liste, ou même des fonctionnalités avancées comme la pagination ou le défilement infini. Cependant, nous voulons qu'il soit flexible avec l'apparence de chaque élément et laisse la définition du style de chaque élément au composant parent qui le consomme. Ainsi, l'utilisation souhaitée peut ressembler à ceci :

```vue-html
<FancyList :api-url="url" :per-page="10">
  <template #item="{ body, username, likes }">
    <div class="item">
      <p>{{ body }}</p>
      <p>by {{ username }} | {{ likes }} likes</p>
    </div>
  </template>
</FancyList>
```

Dans `<FancyList>`, nous pouvons afficher le même `<slot>` plusieurs fois avec différentes données (notez que nous utilisons `v-bind` pour passer un objet en tant que props du slot) :

```vue-html
<ul>
  <li v-for="item in items">
    <slot name="item" v-bind="item"></slot>
  </li>
</ul>
```

[Essayer en ligne](https://play.vuejs.org/#eNqFU2Fv0zAQ/StHJtROapNuZTBCNwnQQKBpTGxCQss+uMml8+bYlu2UlZL/zjlp0lQa40sU3/nd3Xv3vA7eax0uSwziYGZTw7UDi67Up4nkhVbGwScm09U5tw5yowoYhFEX8cBBImdRgyQMHRwWWjCHdAKYbdFM83FpxEkS0DcJINZoxpotkCIHkySo7xOixcMep19KrmGustUISotGsgJHIPgDWqg6DKEyvoRUMGsJ4HG9HGX16bqpAlU1izy5baqDFegYweYroMttMwLAHx/Y9Kyan36RWUTN2+mjXfpbrei8k6SjdSuBYFOlMaNI6AeAtcflSrqx5b8xhkl4jMU7H0yVUCaGvVeH8+PjKYWqWnpf5DQYBTtb+fc612Awh2qzzGaBiUyVpBVpo7SFE8gw5xIv/Wl4M9gsbjCCQbuywe3+FuXl9iiqO7xpElEEhUofKFQo2mTGiFiOLr3jcpFImuiaF6hKNxzuw8lpw7kuEy6ZKJGK3TR6NluLYXBVqwRXQjkLn0ueIc3TLonyZ0sm4acqKVovKIbDCVQjGsb1qvyg2telU4Yzz6eHv6ARBWdwjVqUNCbbFjqgQn6aW1J8RKfJhDg+5/lStG4QHJZjnpO5XjT0BMqFu+uZ81yxjEQJw7A1kOA76FyZjaWBy0akvu8tCQKeQ+d7wsy5zLpz1FlzU3kW1QP+x40ApWgWAySEJTv6/NitNMkllcTakwCaZZ5ADEf6cROas/RhYVQps5igEpkZLwzRROmG04OjDBcj7+Js+vYQDo9e0uH1qzeY5/s1vtaaqG969+vTTrsmBTMLLv12nuy7l+d5W673SBzxkzlfhPdWSXokdZMkSFWhuUDzTTtOnk6CuG2fBEwI9etrHXOmRLJUE0/vMH14In5vH30sCS4Nkr+WmARdztHQ6Jr02dUFPtJ/lyxUVgq6/UzyO1olSj9jc+0DcaWxe/fqab/UT51Uu7Znjw6lbUn5QWtR6vtJQM//4zPUt+NOw+lGzCqo/gLm1QS8)

[Essayer en ligne](https://play.vuejs.org/#eNqNVNtq20AQ/ZWpQnECujhO0qaqY+hD25fQl4RCifKwllbKktXushcT1/W/d1bSSnYJNCCEZmbPmcuZ1S76olS6cTTKo6UpNVN2VQjWKqktfCOi3N4yY6HWsoVZmo0eD5kVAqAQ9KU7XNGaOG5h572lRAZBhTV574CJzJv7QuCzzMaMaFjaKk4sRQtgOeUmiiVO85siwncRQa6oThRpKHrO50XUnUdEwMMJw08M7mAtq20MzlAtSEtj4OyZGkweMIiq2AZKToxBgMcdxDCqVrueBfb7ZaaOQiOspZYgbL0FPBySIQD+eMeQc99/HJIsM0weqs+O258mjfZREE1jt5yCKaWiFXpSX0A/5loKmxj2m+YwT69p+7kXg0udw8nlYn19fYGufvSeZBXF0ZGmR2vwmrJKS4WiPswGWWYxzIIgs8fYH6mIJadnQXdNrdMiWAB+yJ7gsXdgLfjqcK10wtJqgmYZ+spnpGgl6up5oaa2fGKi6U8Yau9ZS6Wzpwi7WU1p7BMzaZcLbuBh0q2XM4fZXTc+uOPSGvjuWEWxlaAexr9uiIBf0qG3Uy6HxXwo9B+mn47CvbNSM+LHccDxAyvmjMA9Vdxh1WQiO0eywBVGEaN3Pj972wVxPKwOZ7BJWI2b+K5rOOVUNPbpYJNvJalwZmmahm3j7AhdSz3sPzDRS3R4SQwOCXxP4yVBzJqJarSzcY8H5mXWFfif1QVwPGjGcQWTLp7YrcLxCfyDdAuMW0cq30AOV+plcK1J+dxoXJkqR6igRCeNxjbxp3N6cX5V0Sb2K19dfFrA4uo9Gh8uP9K6Puvw3eyx9SH3IT/qPCZpiW6Y8Gq9mvekrutAN96o/V99ALPj)

### Composants sans affichage {#renderless-components}

Le cas d'utilisation `<FancyList>` dont nous avons parlé ci-dessus encapsule à la fois la logique réutilisable (récupération de données, pagination, etc.) et l'affichage, tout en déléguant une partie de l'affichage au composant consommateur via des scoped slots.

Si nous poussons ce concept un peu plus loin, nous pouvons proposer des composants qui encapsulent uniquement la logique et n'affichent rien par eux-mêmes - l'affichage est entièrement délégué au composant consommateur avec des scoped slots. Nous appelons ce type de composant un **Composant sans affichage** (Renderless Component).

Un exemple de composant sans affichage pourrait être un composant qui encapsule la logique de suivi de la position actuelle de la souris :

```vue-html
<MouseTracker v-slot="{ x, y }">
  Mouse is at: {{ x }}, {{ y }}
</MouseTracker>
```

[Essayer en ligne](https://play.vuejs.org/#eNqNUcFqhDAQ/ZUhF12w2rO4Cz301t5aaCEX0dki1SQko6uI/96J7i4qLPQQmHmZ9+Y9ZhQvxsRdiyIVmStsZQgcUmtOUlWN0ZbgXbcOP2xe/KKFs9UNBHGyBj09kCpLFj4zuSFsTJ0T+o6yjUb35GpNRylG6CMYYJKCpwAkzWNQOcgphZG/YZoiX/DQNAttFjMrS+6LRCT2rh6HGsHiOQKtmKIIS19+qmZpYLrmXIKxM1Vo5Yj9HD0vfD7ckGGF3LDWlOyHP/idYPQCfdzldTtjscl/8MuDww78lsqHVHdTYXjwCpdKlfoS52X52qGit8oRKrRhwHYdNrrDILouPbCNVZCtgJ1n/6Xx8JYAmT8epD3fr5cC0oGLQYpkd4zpD27R0vA=)

[Essayer en ligne](https://play.vuejs.org/#eNqVUU1rwzAM/SvCl7SQJTuHdLDDbttthw18MbW6hjW2seU0oeS/T0lounQfUDBGepaenvxO4tG5rIkoClGGra8cPUhT1c56ghcbA756tf1EDztva0iy/Ds4NCbSAEiD7diicafigeA0oFvLPAYNhWICYEE5IL00fMp8Hs0JYe0OinDIqFyIaO7CwdJGihO0KXTcLriK59NYBlUARTyMn6Hv0yHgIp7ARAvl3FXm8yCRiuu1Fv/x23JakVqtz3t5pOjNOQNoC7hPz0nHyRSzEr7Ghxppb/XlZ6JjRlzhTAlA+ypkLWwAM6c+8G2BdzP+/pPbRkOoL/KOldH2mCmtnxr247kKhAb9KuHKgLVtMEkn2knG+sIVzV9sfmy8hfB/swHKwV0oWja4lQKKjoNOivzKrf4L/JPqaQ==)

Bien qu'il s'agisse d'un pattern intéressant, la plupart de ce qui peut être réalisé avec les composants sans affichage peut être réalisé de manière plus efficace avec la Composition API, sans subir les coûts liés à l'imbrication de composants supplémentaires. Plus tard, nous verrons comment nous pouvons implémenter la même fonctionnalité de suivi de la souris mais avec un [Composable](/guide/reusability/composables).

Cela dit, les scoped slots sont toujours utiles dans les cas où nous devons à la fois encapsuler la logique **et** composer un affichage, comme dans l'exemple `<FancyList>`.

---

---
url: /api/sfc-spec.md
---
# Spécifications liées à la syntaxe des composants monofichiers {#sfc-syntax-specification}

## Vue d'ensemble {#overview}

Un composant monopage Vue, ou *Single-File Component* (SFC), utilisant conventionnellement l'extension de fichier `*.vue`, est un format de fichier personnalisé qui utilise une syntaxe de type HTML pour décrire un composant Vue. Un SFC Vue est syntaxiquement compatible avec le HTML.

Chaque fichier `*.vue` se compose de trois types de blocs de langage de haut niveau : `<template>`, `<script>`, et `<style>`, et éventuellement d'autres blocs personnalisés :

```vue
<template>
  <div class="example">{{ msg }}</div>
</template>

<script>
export default {
  data() {
    return {
      msg: 'Hello world!'
    }
  }
}
</script>

<style>
.example {
  color: red;
}
</style>

<custom1>
  This could be e.g. documentation for the component.
</custom1>
```

## Blocs de langage {#language-blocks}

### `<template>` {#template}

* Chaque fichier `*.vue` peut contenir au maximum un bloc de haut niveau `<template>` à la fois.

* Le contenu sera extrait et transmis à `@vue/compiler-dom`, pré-compilé en fonctions de rendu JavaScript, et attaché au composant exporté en tant que son option `render`.

### `<script>` {#script}

* Chaque fichier `*.vue` peut contenir au maximum un bloc `<script>` à la fois (sauf [`<script setup>`](/api/sfc-script-setup)).

* Le script est exécuté comme un module ES.

* L'**export par défaut** doit être un objet composé d'options de composant Vue, soit en tant qu'objet simple, soit en tant que valeur de retour de [defineComponent](/api/general#definecomponent).

### `<script setup>` {#script-setup}

* Chaque fichier `*.vue` peut contenir au maximum un bloc `<script setup>` à la fois (à l'exclusion des `<script>` normaux).

* Le script est pré-traité et utilisé comme fonction `setup()` du composant, ce qui signifie qu'il sera exécuté **pour chaque instance du composant**. Les liaisons de haut niveau dans `<script setup>` sont automatiquement exposées au template. Pour plus de détails, voir la [documentation dédiée à `<script setup>`](/api/sfc-script-setup).

### `<style>` {#style}

* Un seul fichier `*.vue` peut contenir plusieurs balises `<style>`.

* Une balise `<style>` peut avoir des attributs `scoped` ou `module` (voir [les fonctionnalités de style pour les composants monofichiers](/api/sfc-css-features) pour plus de détails) pour aider à encapsuler les styles dans le composant actuel. Plusieurs balises `<style>` avec différents modes d'encapsulation peuvent coexister dans le même composant.

### Blocs personnalisés {#custom-blocks}

Des blocs personnalisés supplémentaires peuvent être inclus dans un fichier `*.vue` pour tout besoin spécifique au projet, par exemple un bloc `<docs>`. Voici quelques exemples concrets de blocs personnalisés :

* [Gridsome: `<page-query>`](https://gridsome.org/docs/querying-data/)
* [vite-plugin-vue-gql: `<gql>`](https://github.com/wheatjs/vite-plugin-vue-gql)
* [vue-i18n: `<i18n>`](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n#i18n-custom-block)

La gestion des blocs personnalisés dépendra des outils utilisés - si vous souhaitez créer vos propres intégrations de blocs personnalisés, consultez [la section dédiée aux outils](/guide/scaling-up/tooling#sfc-custom-block-integrations) pour plus de détails.

## Inférence automatique à parti des noms {#automatic-name-inference}

Un SFC déduit automatiquement le nom du composant à partir de son **nom de fichier** dans les cas suivants :

* Formatage des avertissements de développement
* Inspection via les DevTools
* Autoréférence récursive. Par exemple, un fichier nommé `FooBar.vue` peut se référer à lui-même comme `<FooBar/>` dans son template. Cela est toutefois moins prioritaire que les composants explicitement enregistrés / importés.

## Pré-processeurs {#pre-processors}

Les blocs peuvent déclarer des langages de pré-processeur en utilisant l'attribut `lang`. Le cas le plus courant est l'utilisation de TypeScript pour le bloc `<script>` :

```vue-html
<script lang="ts">
  // use TypeScript
</script>
```

`lang` peut être appliqué à n'importe quel bloc - par exemple, nous pouvons utiliser `<style>` avec [Sass](https://sass-lang.com/) et `<template>` avec [Pug](https://pugjs.org/api/getting-started.html) :

```vue-html
<template lang="pug">
p {{ msg }}
</template>

<style lang="scss">
  $primary-color: #333;
  body {
    color: $primary-color;
  }
</style>
```

Notez que l'intégration avec divers pré-processeurs peut différer selon les outils utilisés. Consultez la documentation correspondante pour des exemples :

* [Vite](https://vite.dev/guide/features.html#css-pre-processors)
* [Vue CLI](https://cli.vuejs.org/guide/css.html#pre-processors)
* [webpack + vue-loader](https://vue-loader.vuejs.org/guide/pre-processors.html#using-pre-processors)

## Imports src {#src-imports}

Si vous préférez séparer vos composants `*.vue` en plusieurs fichiers, vous pouvez utiliser l'attribut `src` pour importer un fichier externe pour un bloc de langage :

```vue
<template src="./template.html"></template>
<style src="./style.css"></style>
<script src="./script.js"></script>
```

Attention, les importations `src` suivent les mêmes règles de résolution de chemin que les requêtes de modules de webpack, ce qui signifie que :

* Les chemins relatifs doivent commencer par `./`.
* Vous pouvez importer des ressources à partir des dépendances npm :

```vue
<!-- importe un fichier depuis le paquet npm installé "todomvc-app-css" -->
<style src="todomvc-app-css/index.css" />
```

Les importations `src` fonctionnent également avec des blocs personnalisés, par exemple :

```vue
<unit-test src="./unit-test.js">
</unit-test>
```

:::warning Note
Lorsque vous utilisez des alias dans `src`, ne commencez pas par `~`, tout ce qui suit est interprété comme une requête de module. Cela signifie que vous pouvez référencer des assets à l'intérieur de node modules :

```vue
<img src="~some-npm-package/foo.png">
```

:::

## Commentaires {#comments}

À l'intérieur de chaque bloc, vous devez utiliser la syntaxe de commentaires du langage utilisé (HTML, CSS, JavaScript, Pug, etc.). Pour les commentaires de haut niveau, utilisez la syntaxe de commentaire HTML : `<!-- contenu du commentaire ici -->`

---

---
url: /guide/built-ins/suspense.md
---

# Suspense {#suspense}

:::warning Fonctionnalité expérimentale
`<Suspense>` est une fonctionnalité expérimentale. Il n'est pas garanti qu'elle atteigne un statut stable et l'API peut changer avant ce stade.
:::

`<Suspense>` est un composant natif pour orchestrer les dépendances asynchrones dans un arbre de composants. Il peut assurer le rendu d'un état de chargement en attendant que les multiples dépendances asynchrones imbriquées dans l'arbre de composants soient résolues.

## Dépendances asynchrones {#async-dependencies}

Pour expliquer le problème que `<Suspense>` essaie de résoudre et comment il interagit avec ces dépendances asynchrones, imaginons une hiérarchie de composants comme celle qui suit :

```
<Suspense>
└─ <Dashboard>
   ├─ <Profile>
   │  └─ <FriendStatus> (composant avec un setup() asynchrone)
   └─ <Content>
      ├─ <ActivityFeed> (composant asynchrone)
      └─ <Stats> (composant asynchrone)
```

Dans l'arbre des composants, il y a plusieurs composants imbriqués dont le rendu dépend d'une ressource asynchrone qui doit d'abord être résolue. Sans `<Suspense>`, chacun d'entre eux devra gérer son propre chargement, ses erreurs, et ses états de chargement. Dans le pire des cas, nous pourrions voir trois roues de chargement sur la page, avec un contenu qui s'affiche à des moments différents.

Le composant `<Suspense>` nous donne la possibilité d'afficher des états de chargement/erreur de haut niveau pendant que nous attendons que ces dépendances asynchrones imbriquées soient résolues.

Il existe deux types de dépendances asynchrones pour lesquelles `<Suspense>` peut attendre :

1. Les composants avec un hook `setup()` asynchrone. Cela inclut les composants utilisant `<script setup>` avec des expressions `await` de haut niveau.

2. [Les composants asynchrones](/guide/components/async).

### `async setup()` {#async-setup}

Le hook `setup()` d'un composant utilisé avec la Composition API peut être asynchrone :

```js
export default {
  async setup() {
    const res = await fetch(...)
    const posts = await res.json()
    return {
      posts
    }
  }
}
```

Si vous utilisez `<script setup>`, la présence d'expressions `await` de haut niveau fait automatiquement du composant une dépendance asynchrone :

```vue
<script setup>
const res = await fetch(...)
const posts = await res.json()
</script>

<template>
  {{ posts }}
</template>
```

### Composants asynchrones {#async-components}

Les composants asynchrones sont, par défaut,  **"suspensibles "**. Cela signifie que s'il a un `<Suspense>` dans la chaîne parentale, un composant asynchrone sera traité comme une dépendance asynchrone de ce `<Suspense>`. Dans ce cas, l'état de chargement sera contrôlé par le `<Suspense>`, et les options de chargement, d'erreur, de délai et de temporisation propres au composant seront ignorées.

Le composant asynchrone peut désactiver le contrôle de `Suspense` et laisser le composant contrôler son propre état de chargement en spécifiant `suspensible : false` dans ses options.

## État de chargement {#loading-state}

Le composant `<Suspense>` possède deux slots : `#default` et `#fallback`. Les deux slots n'acceptent qu'un seul nœud comme enfant direct. Le nœud dans le slot par défaut est affiché si cela est possible. Sinon, le nœud dans le slot de secours sera affiché.

```vue-html
<Suspense>
  <!-- composant avec des dépendances asynchrones imbriquées -->
  <Dashboard />

  <!-- état de chargement via le slot #fallback -->
  <template #fallback>
    Loading...
  </template>
</Suspense>
```

Lors du rendu initial, `<Suspense>` rendra le contenu de son slot par défaut en mémoire. Si des dépendances asynchrones sont rencontrées pendant le processus, il entrera dans un état d'**attente**. Pendant l'état d'attente, le contenu de secours sera affiché. Lorsque toutes les dépendances asynchrones rencontrées sont résolues, `<Suspense>` entre dans un état **résolu** et le contenu résolu du slot par défaut est affiché.

Si aucune dépendance asynchrone n'a été rencontrée lors du rendu initial, `<Suspense>` passera directement dans un état résolu.

Une fois dans un état résolu, `<Suspense>` ne reviendra à un état d'attente que si le nœud racine du slot `#default` est remplacé. Les nouvelles dépendances asynchrones imbriquées plus profondément dans l'arbre ne feront **pas** repasser le `<Suspense>` à l'état d'attente.

Lorsqu'il y a un retour en arrière, le contenu de secours ne sera pas immédiatement affiché. À la place, `<Suspense>` affichera le contenu `#default` précédent en attendant que le nouveau contenu et ses dépendances asynchrones soient résolus. Ce comportement peut être configuré avec la prop `timeout` : `<Suspense>` basculera vers un contenu de secours si le rendu du nouveau contenu par défaut prend plus de temps que la valeur de `timeout`  en millisecondes. Une valeur de `timeout` de `0` fera que le contenu de secours sera affiché immédiatement lorsque le contenu par défaut sera remplacé.

## Événements {#events}

Le composant `<Suspense>` émet trois événements : `pending`, `resolve` et `fallback`. L'événement `pending` est émis lorsqu'on entre dans un état d'attente. L'événement `resolve` est émis lorsqu'un nouveau contenu a fini d'être résolu dans le slot `default`. L'événement `fallback` est émis lorsque le contenu du slot `fallback` est affiché.

Les événements peuvent être utilisés, par exemple, pour afficher un indicateur de chargement au niveau de l'ancien DOM pendant le chargement des nouveaux composants.

## Gestion des erreurs {#error-handling}

Il n'y a actuellement pas de gestion des erreurs fournie par `<Suspense>` lui même - cependant, vous pouvez utiliser l'option [`errorCaptured`](/api/options-lifecycle#errorcaptured) ou le hook [`onErrorCaptured()`](/api/composition-api-lifecycle#onerrorcaptured) pour intercepter et gérer les erreurs asynchrones dans le composant parent de `<Suspense>`.

## Combinaison avec d'autres composants {#combining-with-other-components}

Il est courant de vouloir utiliser `<Suspense>` en combinaison avec les composants [`<Transition>`](./transition) et [`<KeepAlive>`](./keep-alive). L'ordre d'imbrication de ces composants est important pour qu'ils fonctionnent tous correctement.

De plus, ces composants sont souvent utilisés en association avec le composant `<RouterView>` de [Vue Router](https://router.vuejs.org/).

L'exemple suivant montre comment imbriquer ces composants afin qu'ils se comportent tous comme prévu. Pour des combinaisons plus simples, vous pouvez supprimer les composants dont vous n'avez pas besoin :

```vue-html
<RouterView v-slot="{ Component }">
  <template v-if="Component">
    <Transition mode="out-in">
      <KeepAlive>
        <Suspense>
          <!-- contenu principal -->
          <component :is="Component"></component>

          <!-- état de chargement -->
          <template #fallback>
            Loading...
          </template>
        </Suspense>
      </KeepAlive>
    </Transition>
  </template>
</RouterView>
```

Vue Router supporte nativement les [composants chargés de manière paresseuse](https://router.vuejs.org/guide/advanced/lazy-loading.html) via l'utilisation des importations dynamiques. Ceux-ci sont distincts des composants asynchrones et, actuellement, ils ne déclenchent pas `<Suspense>`. Cependant, ils peuvent toujours avoir des composants asynchrones comme descendants et ceux-ci peuvent déclencher `<Suspense>` normalement.

## Suspense imbriqué {#nested-suspense}

* Supporté à partir de la version 3.3

Lorsque nous avons plusieurs composants asynchrones (ce qui est courant pour les routes imbriquées ou basées sur la mise en page) comme ceci :

```vue-html
<Suspense>
  <component :is="DynamicAsyncOuter">
    <component :is="DynamicAsyncInner" />
  </component>
</Suspense>
```

`<Suspense>` crée une frontière qui résoudra tous les composants asynchrones en bas de l'arbre, comme prévu. Cependant, lorsque nous modifions `DynamicAsyncOuter`, `<Suspense>` l'attend correctement, mais lorsque nous modifions `DynamicAsyncInner`, `DynamicAsyncInner` imbriqué rend un noeud vide jusqu'à ce qu'il soit résolu (au lieu du noeud précédent ou du slot de repli).

Pour résoudre ce problème, nous pourrions avoir un suspense imbriqué pour gérer le correctif pour le composant imbriqué, comme par exemple :

```vue-html
<Suspense>
  <component :is="DynamicAsyncOuter">
    <Suspense suspensible> <!-- this -->
      <component :is="DynamicAsyncInner" />
    </Suspense>
  </component>
</Suspense>
```

Si vous ne définissez pas la prop `suspensible`, le `<Suspense>` interne sera traité comme un composant sync par le parent `<Suspense>`. Cela signifie qu'il a son propre slot de repli et que si les deux composants `Dynamic` changent en même temps, il pourrait y avoir des noeuds vides et de multiples cycles de correction pendant que l'enfant `<Suspense>` charge son propre arbre de dépendance, ce qui n'est pas forcément souhaitable. Quand il est défini, toute la gestion asynchrone des dépendances est donnée au parent `<Suspense>` (y compris les événements émis) et le `<Suspense>` intérieur sert uniquement de frontière pour la résolution des dépendances et le patching.

***

**Référence**

* [Référence de l'API `<Suspense>`](/api/built-in-components#suspense)

---

---
url: /guide/essentials/template-syntax.md
---
# Syntaxe de template {#template-syntax}

Vue utilise une syntaxe de template basée sur HTML pour permettre de lier de manière déclarative le DOM rendu aux données de l'instance du composant sous-jacent. Tous les templates Vue sont du HTML syntaxiquement valide qui peut être analysé par des navigateurs et des analyseurs HTML conformes aux spécifications.

Sous le capot, Vue compile les templates en code JavaScript hautement optimisé. Combiné avec le système de réactivité, Vue est capable de déterminer intelligemment le nombre minimal de composants à restituer et d'appliquer la quantité minimale de manipulations DOM lorsque l'état de l'application change.

Si vous connaissez les concepts de DOM virtuel et préférez la puissance brute de JavaScript, vous pouvez également [écrire directement des fonctions de rendu](/guide/extras/render-function) au lieu des templates, avec en option la prise en charge de JSX. Cependant, notez qu'elles ne bénéficient pas du même niveau d'optimisation au moment de la compilation que les templates.

## Interpolation de texte {#text-interpolation}

La forme la plus élémentaire de liaison de données est l'interpolation de texte à l'aide de la syntaxe "Moustache" (doubles accolades) :

```vue-html
<span>Message : {{ msg }}</span>
```

La balise moustache sera remplacée par la valeur de la propriété `msg` de [l'instance du composant correspondant](/guide/essentials/reactivity-fundamentals#declaring-reactive-state). Elle sera également mise à jour chaque fois que la propriété `msg` changera.

## HTML brut {#raw-html}

Les doubles moustaches interprètent les données comme du texte brut et non comme du HTML. Afin de produire du vrai HTML, vous devrez utiliser la directive [`v-html`](/api/built-in-directives#v-html) :

```vue-html
<p>Using text interpolation: {{ rawHtml }}</p>
<p>Using v-html directive: <span v-html="rawHtml"></span></p>
```

Ici, nous rencontrons quelque chose de nouveau. L'attribut `v-html` que vous voyez s'appelle une **directive**. Les directives sont préfixées par `v-` pour indiquer qu'il s'agit d'attributs spéciaux fournis par Vue et, comme vous l'avez peut-être deviné, elles appliquent un comportement réactif spécial au DOM rendu. Ici, nous disons essentiellement "maintenir à jour le code HTML interne de cet élément avec la propriété `rawHtml` sur l'instance active actuelle".

Le contenu de `span` sera remplacé par la valeur de la propriété `rawHtml`, interprétée comme du HTML simple - les liaisons de données sont ignorées. Notez que vous ne pouvez pas utiliser `v-html` pour composer des templates partiels, car Vue n'est pas un moteur de template basé sur des chaînes de caractères. Au lieu de cela, les composants sont préférés comme unité fondamentale pour la réutilisation et la composition de l'interface utilisateur.

:::warning Avertissement de sécurité
L'affichage dynamique de code HTML arbitraire sur votre site Web peut être très dangereux, car il peut facilement entraîner des [vulnérabilités XSS](https://en.wikipedia.org/wiki/Cross-site_scripting). N'utilisez `v-html` que sur le contenu de confiance et **jamais** sur le contenu fourni par l'utilisateur.
:::

## Liaisons d'attributs {#attribute-bindings}

Les moustaches ne peuvent pas être utilisées dans les attributs HTML. À la place, utilisez une directive [`v-bind`](/api/built-in-directives#v-bind) :

```vue-html
<div v-bind:id="dynamicId"></div>
```

La directive `v-bind` demande à Vue de garder l'attribut `id` de l'élément synchronisé avec la propriété `dynamicId` du composant. Si la valeur liée est `null` ou `undefined`, alors l'attribut sera supprimé de l'élément rendu.

### Raccourci {#shorthand}

Parce que `v-bind` est si couramment utilisée, elle a une syntaxe raccourcie :

```vue-html
<div :id="dynamicId"></div>
```

Les attributs commençant par `:` peuvent sembler un peu différents du HTML normal, mais il s'agit en fait d'un caractère valide pour les noms d'attributs et tous les navigateurs pris en charge par Vue peuvent l'analyser correctement. De plus, ils n'apparaissent pas dans le rendu final. La syntaxe abrégée est facultative, mais vous l'apprécierez probablement lorsque vous en apprendrez plus sur son utilisation plus tard.

> Pour le reste du guide, nous utiliserons la syntaxe abrégée dans les exemples de code, car c'est l'utilisation la plus courante pour les développeurs Vue.

### Raccourci de même nom  {#same-name-shorthand}

* Supporté à partir de la version 3.4

Si l'attribut porte le même nom que le nom de la variable de la valeur JavaScript à lier, la syntaxe peut encore être raccourcie pour omettre la valeur de l'attribut :

```vue-html
<!-- pareil que :id="id" -->
<div :id></div>

<!-- ceci fonctionne également -->
<div v-bind:id></div>
```

C'est similaire au raccourci pour déclarer un objet en JavaScript. Notez que cette fonctionnalité n'est disponible que pour les versions 3.4 et suivantes de Vue.

### Attributs booléens {#boolean-attributes}

[Les attributs booléens](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes) sont des attributs qui peuvent indiquer des valeurs vrai/faux par leur présence sur un élément. Par exemple, [`disabled`](https://developer.mozilla.org/fr/docs/Web/HTML/Attributes/disabled) est l'un des attributs booléens les plus couramment utilisés.

`v-bind` fonctionne un peu différemment dans ce cas :

```vue-html
<button :disabled="isButtonDisabled">Button</button>
```

L'attribut `disabled` sera inclus si `isButtonDisabled` a une [valeur évaluée à vrai](https://developer.mozilla.org/fr/docs/Glossary/Truthy). Il sera également inclus si la valeur est une chaîne vide, en maintenant la cohérence avec `<button disabled="">`. Pour les [valeurs évaluées à faux](https://developer.mozilla.org/fr/docs/Glossary/Falsy), l'attribut sera omis.

### Liaison dynamique de plusieurs attributs {#dynamically-binding-multiple-attributes}

Si vous avez un objet JavaScript représentant plusieurs attributs qui ressemble à ceci :

```js
const objectOfAttrs = {
  id: 'container',
  class: 'wrapper',
  style: 'background-color:green'
}
```

```js
data() {
  return {
    objectOfAttrs: {
      id: 'container',
      class: 'wrapper'
    }
  }
}
```

Vous pouvez les lier à un seul élément en utilisant `v-bind` sans argument :

```vue-html
<div v-bind="objectOfAttrs"></div>
```

## Utilisation d'expressions JavaScript {#using-javascript-expressions}

Jusqu'à présent, nous n'avons lié que des clés de propriété simples dans nos templates. Mais Vue prend en charge toute la puissance des expressions JavaScript dans toutes les liaisons de données :

```html
{{ number + 1 }} {{ ok ? 'YES' : 'NO' }} {{
message.split('').reverse().join('') }}

<div :id="`list-${id}`"></div>
```

Ces expressions seront évaluées comme du JavaScript dans la portée des données de l'instance de composant actuelle.

Dans les templates Vue, les expressions JavaScript peuvent être utilisées dans les positions suivantes :

* Dans une interpolation de texte (moustaches)
* Dans la valeur d'attribut de toutes les directives Vue (attributs spéciaux qui commencent par `v-`)

### Expressions uniquement {#expressions-only}

Chaque liaison ne peut contenir qu'**une seule expression**. Une expression est un morceau de code qui peut donner une valeur. Une simple vérification est de savoir si elle peut être utilisée après un `return`.

Par conséquent, ce qui suit ne fonctionnera **PAS** :

```html
<!-- ceci est une déclaration, pas une expression : -->
{{ var a = 1 }}

<!-- le contrôle de flux ne fonctionnera pas non plus, utilisez des expressions ternaires -->
{{ if (ok) { return message } }}
```

### Appel de fonctions {#calling-functions}

Il est possible d'appeler une méthode exposée au composant dans une expression de liaison :

```html
<time :title="toTitleDate(date)" :datetime="date">
  {{ formatDate(date) }}
</time>
```

:::tip
Les fonctions appelées à l'intérieur des expressions de liaison seront appelées à chaque mise à jour du composant, elles ne doivent donc **pas** avoir d'effets de bord, tels que la modification de données ou le déclenchement d'opérations asynchrones.
:::

### Accès global restreint {#restricted-globals-access}

Les expressions de template sont en bac à sable et n'ont accès qu'à une [liste restreinte de variables globales](https://github.com/vuejs/core/blob/main/packages/shared/src/globalsAllowList.ts#L3). La liste expose les variables globales intégrées couramment utilisées telles que `Math` et `Date`.

Les variables globales non explicitement incluses dans la liste, par exemple les propriétés jointes par l'utilisateur sur `window`, ne seront pas accessibles dans les expressions du template. Vous pouvez cependant définir explicitement des variables globales supplémentaires pour toutes les expressions Vue en les ajoutant à [`app.config.globalProperties`](/api/application#app-config-globalproperties).

## Directives {#directives}

Les directives sont des attributs spéciaux avec pour préfixe `v-`. Vue propose un certain nombre de [directives natives](/api/built-in-directives), dont `v-html` et `v-bind` que nous venons d'introduire précédemment.

Les valeurs attendues dans les directives sont une seule expression JavaScript (à l'exception de `v-for`, `v-on` et `v-slot`, que l'on présentera dans leur section respective). Le travail d'une directive est d'appliquer les changements au DOM en réaction aux changements de la valeur de son expression. Prenez [`v-if`](/api/built-in-directives#v-if) comme exemple :

```vue-html
<p v-if="seen">Now you see me</p>
```

Ici, la directive `v-if` va supprimer ou insérer l'élément `<p>` selon la valeur booléenne de l'expression `seen`.

### Arguments {#arguments}

Certaines directives peuvent prendre un "argument", distingué par un double-point après le nom de la directive. Par exemple, la directive `v-bind` est utilisée pour mettre à jour par réaction un attribut HTML :

```vue-html
<a v-bind:href="url"> ... </a>

<!-- raccourci -->
<a :href="url"> ... </a>
```

Ici `href` est l'argument, qui suggère à la directive `v-bind` de lier l'attribut `href` de l'élément à l'expression `url`. Par un raccourci, tout ce qui se trouve avant l'argument (pour `v-bind:`) est condensé au simple caractère `:`.

Autre exemple avec la directive `v-on`, qui écoute les événements du DOM :

```vue-html
<a v-on:click="doSomething"> ... </a>

<!-- raccourci -->
<a @click="doSomething"> ... </a>
```

Ici l'argument est le nom de l'événement à écouter : `click`. `v-on` a un raccourci dédié, le caractère `@`. Nous en parlerons également en détail sur la gestion de événements.

### Arguments dynamiques {#dynamic-arguments}

Il est également possible d'utiliser une expression JavaScript dans l'argument d'une directive en l'entourant de crochets :

```vue-html
<!--
Notez qu'il y a quelques contraintes sur l'expression de l'argument,
comme expliqué dans les sections "Contraintes de valeur des arguments dynamiques" et "Contraintes de syntaxe des arguments dynamiques" ci-dessous.
-->
<a v-bind:[attributeName]="url"> ... </a>

<!-- raccourci -->
<a :[attributeName]="url"> ... </a>
```

Ici `attributeName` sera dynamiquement évalué comme une expression JavaScript, et sa valeur évaluée sera utilisée comme valeur finale pour l'argument. Par exemple, si l'instance du composant a une propriété, `attributeName`, et que sa valeur est `"href"`, alors la liaison sera équivalent à `v-bind:href`.

De manière similaire, vous pouvez utiliser des arguments dynamiques pour lier un gestionnaire à un nom d'événement dynamique :

```vue-html
<a v-on:[eventName]="doSomething"> ... </a>

<!-- raccourci -->
<a @[eventName]="doSomething"> ... </a>
```

Dans cet exemple, quand la valeur de `eventName` est `"focus"`, `v-on:[eventName]` sera équivalent à `v-on:focus`.

#### Contraintes de valeur des arguments dynamiques {#dynamic-argument-value-constraints}

Les arguments dynamiques sont prévus pour être évalués en une chaîne de caractères, avec `null` pour exception. La valeur spéciale `null` peut être utilisée pour supprimer explicitement la liaison. Toute autre valeur non-chaînée déclenchera un avertissement.

#### Contraintes de syntaxe des arguments dynamiques {#dynamic-argument-syntax-constraints}

Les expressions d'argument dynamique ont quelques contraintes syntaxique à cause de certains caractères, comme les espaces et les guillemets, qui sont invalides pour des noms d'attributs HTML :

```vue-html
<!-- Ceci va déclencher un avertissement du compilateur. -->
<a :['foo' + bar]="value"> ... </a>
```

Si vous devez passer un argument dynamique complexe, il est probablement préférable d'utiliser une [propriété calculée](./computed), que nous aborderons sous peu.

Lorsque vous utilisez des templates dans le DOM (templates directement écrits dans un fichier HTML), vous devez également éviter de nommer les clés avec des caractères majuscules, car les navigateurs contraindront les noms d'attributs en minuscules :

```vue-html
<a :[someAttr]="value"> ... </a>
```

Ci-dessus sera converti en `:[someattr]` dans les templates dans le DOM. Si votre composant a une propriété `someAttr` au lieu de `someattr`, votre code ne fonctionnera pas. Les templates à l'intérieur des composants à fichier unique **ne sont pas** soumis à cette contrainte.

### Modificateurs {#modifiers}

Les modificateurs sont des suffixes spéciaux désignés par un point, qui indiquent qu'une directive doit être liée d'une manière spéciale. Par exemple, le modificateur `.prevent` indique à la directive `v-on` d'appeler `event.preventDefault()` sur l'événement déclenché :

```vue-html
<form @submit.prevent="onSubmit">...</form>
```

Vous verrez d'autres exemples de modificateurs plus tard, [pour `v-on`](./event-handling#event-modifiers) et [pour `v-model`](./forms#modifiers), lorsque nous explorerons ces fonctionnalités.

Et enfin, voici la syntaxe complète de la directive visualisée :

![graphique de syntaxe de directive](./images/directive.png)

---

---
url: /guide/extras/animation.md
---
# Techniques d'animation {#animation-techniques}

Vue fournit les composants [`<Transition>`](/guide/built-ins/transition) et [`<TransitionGroup>`](/guide/built-ins/transition-group) pour gérer les transitions d'entrée / sortie et de liste. Cependant, il existe de nombreuses autres manières d'utiliser des animations sur le web, même dans une application Vue. Ici, nous allons discuter de quelques techniques supplémentaires.

## Animations basées sur des classes {#class-based-animations}

Pour les éléments qui n'entrent pas / ne quittent pas le DOM, nous pouvons déclencher des animations en ajoutant dynamiquement une classe CSS :

```js
const disabled = ref(false)

function warnDisabled() {
  disabled.value = true
  setTimeout(() => {
    disabled.value = false
  }, 1500)
}
```

```js
export default {
  data() {
    return {
      disabled: false
    }
  },
  methods: {
    warnDisabled() {
      this.disabled = true
      setTimeout(() => {
        this.disabled = false
      }, 1500)
    }
  }
}
```

```vue-html
<div :class="{ shake: disabled }">
  <button @click="warnDisabled">Click me</button>
  <span v-if="disabled">This feature is disabled!</span>
</div>
```

```css
.shake {
  animation: shake 0.82s cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
  transform: translate3d(0, 0, 0);
}

@keyframes shake {
  10%,
  90% {
    transform: translate3d(-1px, 0, 0);
  }

  20%,
  80% {
    transform: translate3d(2px, 0, 0);
  }

  30%,
  50%,
  70% {
    transform: translate3d(-4px, 0, 0);
  }

  40%,
  60% {
    transform: translate3d(4px, 0, 0);
  }
}
```

## Animations pilotées par l'état {#state-driven-animations}

Certaines transitions peuvent être appliquées en interpolant des valeurs, par exemple en liant un style à un élément pendant qu'une interaction se produit. Prenons cet exemple :

```js
const x = ref(0)

function onMousemove(e) {
  x.value = e.clientX
}
```

```js
export default {
  data() {
    return {
      x: 0
    }
  },
  methods: {
    onMousemove(e) {
      this.x = e.clientX
    }
  }
}
```

```vue-html
<div
  @mousemove="onMousemove"
  :style="{ backgroundColor: `hsl(${x}, 80%, 50%)` }"
  class="movearea"
>
  <p>Move your mouse across this div...</p>
  <p>x: {{ x }}</p>
</div>
```

```css
.movearea {
  transition: 0.3s background-color ease;
}
```

En plus de la couleur, vous pouvez également utiliser des liaisons de style pour animer la transformation, la largeur ou la hauteur. Vous pouvez même animer des chemins SVG en utilisant la physique de ressort - après tout, ce sont toutes des liaisons de données d'attributs :

## Animer avec des observateurs {#animating-with-watchers}

Avec un peu de créativité, nous pouvons utiliser des observateurs pour animer n'importe quoi en fonction d'un état numérique. Par exemple, nous pouvons animer le nombre lui-même :

```js
import { ref, reactive, watch } from 'vue'
import gsap from 'gsap'

const number = ref(0)
const tweened = reactive({
  number: 0
})

// Note: Pour les entrées plus supérieures que Number.MAX_SAFE_INTEGER (9007199254740991),
// le résultat peut être incohérent en raison des limitations sur la précision des nombres en JavaScript.
watch(number, (n) => {
  gsap.to(tweened, { duration: 0.5, number: Number(n) || 0 })
})
```

```vue-html
Type a number: <input v-model.number="number" />
<p>{{ tweened.number.toFixed(0) }}</p>
```

```js
import gsap from 'gsap'

export default {
  data() {
    return {
      number: 0,
      tweened: 0
    }
  },
  // Note: Pour les entrées plus supérieures que Number.MAX_SAFE_INTEGER (9007199254740991),
  // le résultat peut être incohérent en raison des limitations sur la précision des nombres en JavaScript.
  watch: {
    number(n) {
      gsap.to(this, { duration: 0.5, tweened: Number(n) || 0 })
    }
  }
}
```

```vue-html
Type a number: <input v-model.number="number" />
<p>{{ tweened.toFixed(0) }}</p>
```

[Essayer en ligne](https://play.vuejs.org/#eNpNUstygzAM/BWNLyEzBDKd6YWSdHrpsacefSGgJG7xY7BImhL+vTKv9ILllXYlr+jEm3PJpUWRidyXjXIEHql1e2mUdrYh6KDBY8yfoiR1wRiuBZVn6OHYWA0r5q6W2pMv3ISHkBPSlNZ4AtPqAzawC2LRdj3DdEU0WA34qB910sBUnsFWmp6LpRmaRo9UHMLIrGG3h4EBQ/OEbDRpxjx51TYFKWtYKHmOF9WP4Qzs+x22EDoA9NLwmaejC/x+vhBqVxeEfAPIK3WBsi6830lRobZSDDjA580hFIt8roxrCS4bbSuskxFmzhhIAenEy92id1CnzZzfd91szETmZ72rH6zYOej7PA3rYXrKE3GUp//m5KunWx3C5CE6enS0hjZXVKczZXCwdfWyoF79YgZPqBliJ9iGSUTEYlzuRrO9X94a/lUGNTklvBTZvAMpwhYCIMWZyPksTVvjvk9JaXUacq9sSlujFJPnvej/AElH3FQ=)

[Essayer en ligne](https://play.vuejs.org/#eNpNUctugzAQ/JWVLyESj6hSL5Sm6qXHnnr0xYENuAXbwus8Svj3GlxIJEvendHMvgb2bkx6cshyVtiyl4b2XMnO6J6gtsLAsdcdbKZwwxVXeJmpCo/CtQQDVwCVIBFtQwzQI7leLRmAct0B+xx28YLQGVFh5aGAjNM3zvRZUNnkizhII7V6w9xTSjqiRtoYBqhcL0hq5c3S5/hu/blKbzfYwbh9LMWVf0W2zusTws60gnDK6OtqEMTaeSGVcQSnpNMVtmmAXzkLAWeQzarCQNkKaz1zkHWysPthWNryjX/IC1bRbgvjWGTG64rssbQqLF3bKUzvHmH6o1aUnFHWDeVw0G31sqJW/mIOT9h5KEw2m7CYhUsmnV/at9XKX3n24v+E5WxdNmfTbieAs4bI2DzLnDI/dVrqLpu4Nz+/a5GzZYls/AM3dcFx)

---

---
url: /guide/built-ins/teleport.md
---
# Teleport {#teleport}

`<Teleport>` est un composant natif qui nous permet de "téléporter" une partie du template d'un composant dans un nœud du DOM qui existe en dehors de la hiérarchie du DOM de ce composant.

## Utilisation basique {#basic-usage}

Parfois, nous pouvons être confrontés au scénario suivant : une partie du template d'un composant lui appartient logiquement, mais d'un point de vue visuel, elle devrait être affichée ailleurs dans le DOM, peut-être même en dehors de l'application Vue.

L'exemple le plus courant est la création d'une modale plein écran. Idéalement, nous souhaitons que le code du bouton de la modale et la modale elle-même soient écrits dans le même composant à fichier unique, puisqu'ils sont tous les deux liés à l'état d'ouverture / fermeture de la modale. Mais cela signifie que la modale sera rendue à côté du bouton, profondément imbriquée dans la hiérarchie du DOM de l'application. Cela peut causer des problèmes délicats lors du positionnement de la modale via CSS.

Considérez la structure HTML suivante.

```vue-html
<div class="outer">
  <h3>Vue Teleport Example</h3>
  <div>
    <MyModal />
  </div>
</div>
```

Et voici une implémentation de `<MyModal>`:

```vue
<script setup>
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <button @click="open = true">Open Modal</button>

  <div v-if="open" class="modal">
    <p>Hello from the modal!</p>
    <button @click="open = false">Close</button>
  </div>
</template>

<style scoped>
.modal {
  position: fixed;
  z-index: 999;
  top: 20%;
  left: 50%;
  width: 300px;
  margin-left: -150px;
}
</style>
```

```vue
<script>
export default {
  data() {
    return {
      open: false
    }
  }
}
</script>

<template>
  <button @click="open = true">Open Modal</button>

  <div v-if="open" class="modal">
    <p>Hello from the modal!</p>
    <button @click="open = false">Close</button>
  </div>
</template>

<style scoped>
.modal {
  position: fixed;
  z-index: 999;
  top: 20%;
  left: 50%;
  width: 300px;
  margin-left: -150px;
}
</style>
```

Le composant comporte un `<button>` pour déclencher l'ouverture de la modale, ainsi qu'une `<div>` avec une classe `.modal`, qui va contenir le contenu de la modale et un bouton pour se fermer.

Lorsque nous utilisons ce composant à l'intérieur de la structure HTML initiale, il y a un certain nombre de problèmes potentiels :

* `position : fixed` ne place l'élément relativement à la fenêtre d'affichage que si aucun élément ancêtre n'a la propriété `transform`, `perspective` ou `filter` définie. Si, par exemple, nous voulons animer l'ancêtre `<div class="outer">` avec une transformation CSS, cela casserait la disposition de la modale !

* Le `z-index` de la modale est restreint par les éléments dans lesquels elle est imbriquée. S'il y a un autre élément qui chevauche `<div class="outer">` et a un `z-index` plus élevé, il couvrira notre modale.

`<Teleport>` fournit une manière propre de résoudre ces problèmes, en nous permettant de sortir de la structure imbriquée du DOM. Modifions `<MyModal>` pour utiliser `<Teleport>` :

```vue-html{3,8}
<button @click="open = true">Open Modal</button>

<Teleport to="body">
  <div v-if="open" class="modal">
    <p>Hello from the modal!</p>
    <button @click="open = false">Close</button>
  </div>
</Teleport>
```

La cible `to` de `<Teleport>` attend une chaîne de sélecteur CSS ou un nœud du DOM actif. Ici, nous disons essentiellement à Vue de "**téléporter** ce fragment de template **vers** la balise **`body`**".

Vous pouvez cliquer sur le bouton ci-dessous et inspecter la balise `body` via la console de votre navigateur :

Vous pouvez combiner `<Teleport>` avec [`<Transition>`](./transition) pour créer des modales animées - voir l'[exemple ici](/examples/#modal).

:::tip
La cible de téléportation `to` doit déjà figurer dans le DOM au moment où le composant `<Teleport>` est monté. Idéalement, il devrait s'agir d'un élément situé en dehors de l'application Vue. Si vous ciblez un autre élément rendu par Vue, vous devez vous assurer que cet élément est monté avant le `<Teleport>`. Si vous utilisez le SSR, consultez [Gestion des téléportations en SSR](/guide/scaling-up/ssr#teleports).
:::

## Utilisation avec les composants {#using-with-components}

`<Teleport>` ne modifie que la structure DOM rendue - il n'affecte pas la hiérarchie logique des composants. En d'autres termes, si `<Teleport>` contient un composant, ce composant restera un enfant logique du composant parent contenant le `<Teleport>`. Le passage des props et l'émission d'événements continueront de fonctionner de la même manière.

Cela signifie également que les injections à partir d'un composant parent fonctionnent comme prévu, et que le composant enfant sera imbriqué sous le composant parent dans les Devtools Vue, au lieu d'être placé là où le contenu réel a été déplacé.

## Désactiver Teleport {#disabling-teleport}

Dans certains cas, nous pouvons vouloir désactiver `<Teleport>` de manière conditionnelle. Par exemple, nous pouvons vouloir rendre un composant en overlay sur les périphériques desktop, mais inline sur la version mobile. `<Teleport>` prend en charge l'option `disabled` qui peut être activée dynamiquement :

```vue-html
<Teleport :disabled="isMobile">
  ...
</Teleport>
```

Nous pourrions alors mettre à jour dynamiquement `isMobile`.

## Plusieurs Teleports sur la même cible {#multiple-teleports-on-the-same-target}

Un cas d'utilisation courant serait un composant `<Modal>` réutilisable, avec la possibilité que plusieurs instances soient actives en même temps. Pour ce type de scénario, plusieurs composants `<Teleport>` peuvent monter leur contenu sur le même élément cible. L'ordre sera le même qu'avec un simple ajout avec les derniers montages seront situés après les précédents, mais tous à l'intérieur de l'élément cible.

Étant donné l'utilisation suivante :

```vue-html
<Teleport to="#modals">
  <div>A</div>
</Teleport>
<Teleport to="#modals">
  <div>B</div>
</Teleport>
```

Le résultat rendu serait :

```html
<div id="modals">
  <div>A</div>
  <div>B</div>
</div>
```

## Deferred Teleport  {#deferred-teleport}

In Vue 3.5 and above, we can use the `defer` prop to defer the target resolving of a Teleport until other parts of the application have mounted. This allows the Teleport to target a container element that is rendered by Vue, but in a later part of the component tree:

```vue-html
<Teleport defer to="#late-div">...</Teleport>

<!-- somewhere later in the template -->
<div id="late-div"></div>
```

Note that the target element must be rendered in the same mount / update tick with the Teleport - i.e. if the `<div>` is only mounted a second later, the Teleport will still report an error. The defer works similarly to the `mounted` lifecycle hook.

***

**Référence**

* [Référence de l'API `<Teleport>`](/api/built-in-components#teleport)
* [Gérer les Teleports en SSR](/guide/scaling-up/ssr#teleports)

---

---
url: /guide/scaling-up/testing.md
---
# Tester {#testing}

## Pourquoi tester ? {#why-test}

Les tests automatisés vous aident ainsi que votre équipe à construire des applications Vue complexes rapidement et avec confiance en prévenant les régressions et en vous encourageant à décomposer votre application en fonctions, modules, classes et composants testables. Comme toute autre application, votre nouvelle application Vue peut dysfonctionner de différentes manières, et il est important que vous puissiez détecter ces problèmes avant de livrer.

Dans ce guide, nous allons couvrir la terminologie basique et donner des recommandations d'outils à choisir pour votre application Vue 3.

Une section dédiée à Vue couvre les composables. Voir [Tester les composables](#testing-composables) ci-dessous pour plus de détails.

## Quand tester ? {#when-to-test}

Commencez tôt ! Nous recommandons de commencer à écrire des tests dès que vous le pouvez. Plus vous attendrez avant d'ajouter des tests à votre application, plus votre application aura des dépendances, et il sera plus difficile de commencer.

## Types de tests {#testing-types}

Quand vous concevez la stratégie de test de votre application Vue, vous devriez mettre en place les types de tests suivants :

* **Unitaire** : Vérifie que les entrées d'une fonction, classe, ou composable donné produisent les sorties ou effets de bord attendus.
* **Composant** : Vérifie que le montage, le rendu, les interactions et le comportement d'un composant ont lieu comme prévu. Ces tests exercent plus de code que des tests unitaires, sont plus complexes et requièrent plus de temps pour s'exécuter.
* **End-to-end** : Vérifie des fonctionnalités qui traversent plusieurs pages et émettent des vraies requêtes réseau sur votre application Vue construite pour la production. Ces tests impliquent souvent la mise en place d'une base de données ou d'un autre backend.

Chaque type de test joue un rôle dans la stratégie de test de votre application, et vous protégera de différents problèmes.

## Aperçu {#overview}

Nous allons brièvement discuter de ce que chacun de ces tests sont, de comment ils peuvent être implémentés pour des applications Vue et donner quelques recommendations générales.

## Tester unitairement {#unit-testing}

Les tests unitaires sont écrits pour vérifier que des petites unités de code isolées fonctionnent comme prévu. Un test unitaire couvre généralement une seule fonction, classe, composable ou module. Les tests unitaires se concentrent sur l'exactitude logique et ne concernent qu'une petite partie des fonctionnalités globales de l'application. Ils peuvent simuler de grandes parties de l'environnement de votre application (par exemple, l'état initial, les classes complexes, les modules tierce partie et les requêtes réseau).

En général, les tests unitaires vont détecter des problèmes concernant la logique métier d'une fonction et son exactitude logique.

Prenons par exemple cette fonction `increment` :

```js [helpers.js]
export function increment(current, max = 10) {
  if (current < max) {
    return current + 1
  }
  return current
}
```

Comme cette fonction est très autonome, il sera facile de l'appeler et de vérifier qu'elle retourne ce qu'elle est supposée faire, nous allons donc écrire un test unitaire.

Si l'une de ces assertions échoue, il est clair que le problème est contenu dans la fonction `increment`.

```js{3-15} [helpers.spec.js]
import { increment } from './helpers'

describe('increment', () => {
  test('increments the current number by 1', () => {
    expect(increment(0, 10)).toBe(1)
  })

  test('does not increment the current number over the max', () => {
    expect(increment(10, 10)).toBe(10)
  })

  test('has a default max of 10', () => {
    expect(increment(10)).toBe(10)
  })
})
```

Comme mentionné précédemment, les tests unitaires sont généralement exercés sur de la logique métier, des composants, classes, modules, ou fonctions qui ne nécessitent pas de rendu visuel, de requêtes réseau, ou d'autres problématiques d'environnement.

Il s'agit généralement de modules écrits en JavaScript / TypeScript simple sans rapport avec Vue. En général, écrire des tests unitaires pour de la logique métier dans des applications Vue ne diffère pas de manière significative des applications utilisant d'autres frameworks.

Il existe deux cas où vous testez unitairement des fonctionnalités spécifiques à Vue :

1. Composables
2. Composants

### Composables {#composables}

[Les composables](/guide/reusability/composables) sont une catégorie de fonctions spécifiques aux applications Vue qui peut nécessiter un traitement spécial pendant les tests.
Voir la section [Tester les composables](#testing-composables) ci-dessous pour plus de détails.

### Tester unitairement des composants {#unit-testing-components}

Un composant peut être testé de deux façons :

1. Boîte blanche : Test unitaire

   Les tests "Boîte blanche" ont "conscience" des détails d'implémentation et des dépendances d'un composant. Ils se concentrent sur l'**isolation** du composant testé. Ces tests impliquent en général de simuler certains sinon tous les enfants de votre composant ainsi que d'initialiser l'état de plugins et dépendances (ex. Pinia).

2. Boîte noire : Test de composant

   Les tests "Boîte noire" n'ont pas "conscience" des détails d'implémentation d'un composant. Ces tests simulent le moins possible afin de tester l'intégration de vos composants et le système entier. Ils font généralement le rendu HTML de l'ensemble des sous-composants et sont considérés plus comme un "test d'intégration". Voir les [recommendations de test de composant](#component-testing) ci-dessous.

### Recommandation {#recommendation-1}

* [Vitest](https://vitest.dev/)

  Étant donné que la configuration officielle créée par `create-vue` est basée sur [Vite](https://vite.dev/), nous vous recommandons d'utiliser un framework de test unitaire pour tirer parti de la même configuration et pipeline de transformation directement à partir de Vite. [Vitest](https://vitest.dev/) est un framework de test unitaire conçu spécifiquement à cet effet, créé et maintenu par les membres de l'équipe Vue / Vite. Il s'intègre aux projets basés sur Vite avec un minimum d'effort et est ultrarapide.

### Autres options {#other-options}

* [Jest](https://jestjs.io/) est un framework de test unitaire populaire. Cependant, nous ne recommandons Jest que si vous avez une suite de tests Jest existante qui doit être migrée vers un projet basé sur Vite, car Vitest offre une intégration plus transparente et de meilleures performances.

## Test de composant {#component-testing}

Dans les applications Vue, les composants sont les principaux blocs de construction de l'interface utilisateur. Les composants sont donc l'unité naturelle d'isolement lorsqu'il s'agit de valider le comportement de votre application. Du point de vue de la granularité, les tests de composants se situent quelque part au-dessus des tests unitaires et peuvent être considérés comme une forme de test d'intégration. Une grande partie de votre application Vue doit être couverte par un test de composant et nous vous recommandons que chaque composant Vue ait son propre fichier de spécifications.

Les tests de composant doivent détecter les problèmes liés aux props, aux événements, aux slots qu'un composant fournit, aux styles, aux classes, aux hooks de cycle de vie de votre composant, etc.

Les tests de composant ne doivent pas simuler des composants enfants, mais plutôt tester les interactions entre votre composant et ses enfants en interagissant avec les composants comme le ferait un utilisateur. Par exemple, un test de composant doit cliquer sur un élément comme le ferait un utilisateur au lieu d'interagir programmatiquement avec le composant.

Les tests de composant doivent se concentrer sur les interfaces publiques du composant plutôt que sur les détails internes d'implémentation. Pour la plupart des composants, l'interface publique est limitée aux événements émis, aux props et aux slots. Lors du test, n'oubliez pas de **tester ce que fait un composant, pas comment il le fait**.

**FAITES**

* Pour la logique **visuelle** : vérifiez que le rendu en sortie est correct en fonction des props et des slots saisis.
* Pour la logique **comportementale** : vérifiez que les mises à jour de rendu ou les événements émis en réponse aux événements d'entrée de l'utilisateur sont corrects.

  Dans l'exemple ci-dessous, nous démontrons un composant Stepper qui a un élément DOM intitulé "increment" et sur lequel vous pouvez cliquer. Nous passons une prop appelée `max` qui empêche le Stepper d'être incrémenté au-delà de `2`, donc si nous cliquons sur le bouton 3 fois, l'interface utilisateur devrait toujours dire `2`.

  Nous ne savons rien de l'implémentation de Stepper, seulement que l'"entrée" est la prop `max` et que la "sortie" est l'état du DOM tel que l'utilisateur le verra.

::: code-group

```js [Vue Test Utils]
const valueSelector = '[data-testid=stepper-value]'
const buttonSelector = '[data-testid=increment]'

const wrapper = mount(Stepper, {
  props: {
    max: 1
  }
})

expect(wrapper.find(valueSelector).text()).toContain('0')

await wrapper.find(buttonSelector).trigger('click')

expect(wrapper.find(valueSelector).text()).toContain('1')
```

```js [Cypress]
const valueSelector = '[data-testid=stepper-value]'
const buttonSelector = '[data-testid=increment]'

mount(Stepper, {
  props: {
    max: 1
  }
})

cy.get(valueSelector)
  .should('be.visible')
  .and('contain.text', '0')
  .get(buttonSelector)
  .click()
  .get(valueSelector)
  .should('contain.text', '1')
```

```js [Testing Library]
const { getByText } = render(Stepper, {
  props: {
    max: 1
  }
})

getByText('0') // Vérification implicite que "0" se trouve dans le composant

const button = getByRole('button', { name: /increment/i })

// Envoi d'un événement click sur notre bouton d'incrémentation.
await fireEvent.click(button)

getByText('1')

await fireEvent.click(button)
```

:::

**NE FAITES PAS**

* Ne vérifiez pas l'état privé d'une instance de composant et ne testez pas les méthodes privées d'un composant. Tester les détails de l'implémentation rend les tests fragiles, car ils sont plus susceptibles de se rompre et nécessitent des mises à jour lorsque l'implémentation change.

  Le travail ultime du composant est un rendu DOM en sortie correct, de sorte que les tests axés sur la sortie DOM fournissent le même niveau d'assurance d'exactitude (sinon plus) tout en étant plus robustes et résilients au changement.

  Ne vous fiez pas exclusivement aux tests snapshots. Vérifier des chaînes HTML ne décrit pas l'exactitude. Rédigez des tests avec intention.

  Si une méthode doit être testée de manière approfondie, envisagez de l'extraire dans une fonction utilitaire autonome et d'écrire un test unitaire dédié à celle-ci. S'il ne peut pas être extrait proprement, il peut être testé dans le cadre d'un test de composant, d'intégration ou bout-en-bout qui le couvre.

### Recommendation {#recommandation}

* [Vitest](https://vitest.dev/) pour les composants ou composables qui ont un rendu headless (ex. la fonction [`useFavicon`](https://vueuse.org/core/useFavicon/#usefavicon) dans VueUse). Les composants et le DOM peuvent être testés à l'aide de [`@vue/test-utils`](https://github.com/vuejs/test-utils).

* [Les tests de composants Cypress](https://on.cypress.io/component) pour les composants dont le comportement attendu dépend du rendu correct des styles ou du déclenchement d'événements DOM natifs. Peut être utilisé avec Testing Library via [`@testing-library/cypress`](https://testing-library.com/docs/cypress-testing-library/intro).

Les principales différences entre Vitest et les runners basés sur un navigateur sont la rapidité et le contexte d'exécution. En bref, les runners basés sur un navigateur, comme Cypress, peuvent détecter des problèmes que les runners basés sur node, comme Vitest, ne peuvent pas détecter (par exemple, les problèmes de style, les événements DOM natifs réels, les cookies, le local storage et les défaillances réseau), mais les runners basés sur un navigateur sont *bien plus lents que Vitest* parce qu'ils ouvrent un navigateur, compilent vos feuilles de style, etc. Cypress est un runner basé sur un navigateur qui prend en charge les tests de composants. Veuillez lire [la page de comparaison de Vitest](https://vitest.dev/guide/comparisons.html#cypress) pour obtenir les dernières informations comparant Vitest et Cypress.

### Bibliothèques de montage {#mounting-libraries}

Le test de composant implique souvent le montage du composant testé isolément, le déclenchement d'événements d'entrée utilisateur simulés et la vérification du rendu DOM en sortie. Il existe des bibliothèques d'utilitaires dédiées qui simplifient ces tâches.

* [`@vue/test-utils`](https://github.com/vuejs/test-utils) est la bibliothèque officielle de test de composants de bas niveau qui a été écrite pour permettre aux utilisateurs d'accéder à des API spécifiques à Vue. C'est aussi la bibliothèque de bas niveau sur laquelle `@testing-library/vue` est construite.

* [`@testing-library/vue`](https://github.com/testing-library/vue-testing-library) est une bibliothèque de test Vue axée sur le test de composants sans s'appuyer sur les détails de l'implémentation. Construit avec l'accessibilité à l'esprit, son approche rend également la refactorisation un jeu d'enfant. Son principe directeur est que plus les tests ressemblent à la façon dont les logiciels sont utilisés, plus on peut leur faire confiance.

Nous vous recommandons d'utiliser `@vue/test-utils` pour tester les composants dans les applications. `@testing-library/vue` a des problèmes avec le test du composant asynchrone avec Suspense, il doit donc être utilisé avec prudence.

* [Nightwatch](https://nightwatchjs.org/) est un testeur E2E avec prise en charge de Vue Component Testing. ([Projet d'exemple](https://github.com/nightwatchjs-community/todo-vue))

* [WebdriverIO](https://webdriver.io/docs/component-testing/vue) pour les tests de composants inter-navigateurs qui reposent sur une interaction utilisateur native basée sur une automatisation standardisée. Peut également être utilisé avec la bibliothèque de tests.

## Tests E2E {#e2e-testing}

Alors que les tests unitaires offrent aux développeurs un certain degré de confiance, les tests unitaires et les tests de composants sont limités dans leur capacité à fournir une couverture holistique d'une application lorsqu'ils sont déployés en production. En conséquence, les tests End-to-end (E2E) offrent une couverture sur ce qui est sans doute l'aspect le plus important d'une application : ce qui se passe lorsque les utilisateurs utilisent réellement vos applications.

Les tests End-to-end se concentrent sur le comportement des applications multipages qui effectuent des requêtes réseau par rapport à votre application Vue de production. Ils impliquent souvent la mise en place d'une base de données ou d'un autre backend et peuvent même être exécutés dans un environnement de staging déployé.

Les tests End-to-end détectent souvent des problèmes avec votre routeur, votre bibliothèque de gestion d'état, vos composants de niveau supérieur (par exemple, une application ou une mise en page), vos ressources publiques ou toute autre gestion de requêtes. Comme indiqué ci-dessus, ils détectent des problèmes critiques qui peuvent être impossibles à détecter avec des tests unitaires ou des tests de composants.

Les tests End-to-end n'importent pas le code de votre application Vue, mais reposent entièrement sur le test de votre application en naviguant dans des pages entières dans un navigateur réel.

Les tests End-to-end valident de nombreuses couches de votre application. Ils peuvent soit cibler votre application localement soit même un environnement de staging déployé. Les tests exercés sur votre environnement de staging incluent non seulement votre code frontend et votre serveur statique mais également tous les services et infrastructures backend associés.

> Plus vos tests ressemblent à la manière dont votre application est utilisée, plus ils vous donneront confiance. [Kent C. Dodds](https://x.com/kentcdodds/status/977018512689455106), auteur de la bibliothèque de tests

En testant l'impact des actions des utilisateurs sur votre application, les tests E2E sont souvent la clé d'une plus grande confiance dans le bon fonctionnement ou non d'une application.

### Choisir une solution de test E2E {#choosing-an-e2e-testing-solution}

Alors que les tests End-to-end (E2E) sur le Web ont acquis une réputation négative pour les tests peu fiables ("flaky") et le ralentissement des processus de développement, les outils E2E modernes ont fait des progrès pour créer des tests plus fiables, interactifs et utiles. Lorsque vous choisissez une infrastructure de test E2E, les sections suivantes fournissent des conseils sur les éléments à garder à l'esprit lors du choix d'une infrastructure de test pour votre application.

#### Tester avec plusieurs navigateurs {#cross-browser-testing}

L'un des principaux avantages pour lesquels les tests End-to-end (E2E) sont connus est sa capacité à tester votre application sur plusieurs navigateurs. Bien qu'il puisse sembler souhaitable d'avoir une couverture inter-navigateurs à 100%, il est important de noter que les tests inter-navigateurs ont des rendements décroissants sur les ressources d'une équipe en raison du temps supplémentaire et de la puissance de la machine nécessaire pour les exécuter de manière cohérente. Par conséquent, il est important d'être conscient de ce compromis lorsque vous choisissez la quantité de tests inter-navigateurs dont votre application a besoin.

#### Des boucles de feedback plus rapides {#faster-feedback-loops}

L'un des principaux problèmes liés aux tests et au développement End-to-end (E2E) est que l'exécution de l'ensemble de la suite prend beaucoup de temps. En règle générale, cela n'est fait que dans les pipelines d'intégration et de déploiement continus (CI/CD). Les frameworks de test E2E modernes ont aidé à résoudre ce problème en ajoutant des fonctionnalités telles que la parallélisation, ce qui permet aux pipelines CI / CD d'exécuter souvent des magnitudes plus rapidement qu'auparavant. En outre, lors du développement local, la possibilité d'exécuter de manière sélective un seul test pour la page sur laquelle vous travaillez tout en fournissant un rechargement à chaud des tests peut aider à améliorer le flux de travail et la productivité d'un développeur.

#### First-class debugging experience {#first-class-debugging-experience}

Alors que les développeurs s'appuyaient traditionnellement sur l'analyse des logs dans une fenêtre de terminal pour aider à déterminer ce qui n'allait pas dans un test, les frameworks de test modernes End-to-end (E2E) permettent aux développeurs de tirer parti d'outils qu'ils connaissent déjà, par exemple les outils de développement de navigateur.

#### Visibilité en mode headless {#visibility-in-headless-mode}

Lorsque les tests End-to-end (E2E) sont exécutés dans des pipelines d'intégration/déploiement continus, ils sont souvent exécutés dans des navigateurs headless (c'est-à-dire qu'aucun navigateur visible n'est ouvert pour que l'utilisateur puisse le regarder). Une caractéristique essentielle des frameworks de test E2E modernes est la possibilité de voir des snapshots et / ou des vidéos de l'application pendant les tests, fournissant un aperçu des raisons pour lesquelles des erreurs se produisent. Historiquement, il était fastidieux de maintenir ces intégrations.

### Recommandation {#recommentation-2}

* [Playwright](https://playwright.dev/) est une excellente solution de test E2E qui prend en charge Chromium, WebKit et Firefox. Testez sur Windows, Linux et macOS, localement ou sur CI, headless ou non avec l'émulation mobile native de Google Chrome pour Android et Mobile Safari. Il dispose d'une interface utilisateur informative, d'une excellente débogabilité, d'assertions intégrées, d'une parallélisation, de traces et est conçu pour éliminer les tests défectueux. La prise en charge des [tests de composants](https://playwright.dev/docs/test-components) est disponible, mais est considérée comme expérimentale. Playwright est open source et maintenu par Microsoft.

* [Cypress](https://www.cypress.io/) dispose d'une interface graphique informative, une excellente déboguabilité, des assertions et des stubs intégrés, une résistance à la "flakiness" des tests, une parallélisation et des instantanés. Comme mentionné ci-dessus, il offre également un support pour [les tests de composants](https://docs.cypress.io/guides/component-testing/introduction). Il prend en charge les navigateurs basés sur Chromium, Firefox et Electron. Le support de WebKit est disponible, mais marqué comme expérimental. Cypress est sous licence MIT, mais certaines fonctionnalités comme la parallélisation nécessitent un abonnement à Cypress Cloud.

### Autres options {#other-options-2}

* [Nightwatch](https://nightwatchjs.org/) est une solution de test E2E basée sur [Selenium WebDriver](https://www.npmjs.com/package/selenium-webdriver). Cela lui permet de prendre en charge le plus grand nombre de navigateurs, y compris les tests mobiles natifs. Les solutions basées sur Selenium seront plus lentes que Playwright ou Cypress.

* [WebdriverIO](https://webdriver.io/) est un framework d'automatisation des tests pour les tests Web et mobiles basé sur le protocole WebDriver.

## Recettes {#recipes}

### Ajouter Vitest a un projet {#adding-vitest-to-a-project}

Dans un projet Vue basé sur Vite, lancez :

```sh
> npm install -D vitest happy-dom @testing-library/vue
```

Ensuite, modifiez la configuration Vite pour ajouter le bloc d'option `test` :

```js{6-12} [vite.config.js]
import { defineConfig } from 'vite'

export default defineConfig({
  // ...
  test: {
    // active les API compatibles avec jest globalement
    globals: true,
    // simule le DOM avec happy-dom
    // (requiert l'installation de happy-dom en dépendance additionnelle)
    environment: 'happy-dom'
  }
})
```

:::tip
Si vous utilisez TypeScript, ajoutez, add `vitest/globals` dans le champ `types` de votre `tsconfig.json`.

```json [tsconfig.json]
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}
```

:::

Créez ensuite un fichier se terminant par `*.test.js` dans votre projet. Vous pouvez placer tous les fichiers de test dans un répertoire de test à la racine du projet ou dans des répertoires de test à côté de vos fichiers sources. Vitest les recherchera automatiquement à l'aide de la convention de nommage.

```js [MyComponent.test.js]
import { render } from '@testing-library/vue'
import MyComponent from './MyComponent.vue'

test('it should work', () => {
  const { getByText } = render(MyComponent, {
    props: {
      /* ... */
    }
  })

  // assert output
  getByText('...')
})
```

Enfin, mettez à jour `package.json` pour ajouter le script de test et lancez-le :

```json{4} [package.json]
{
  // ...
  "scripts": {
    "test": "vitest"
  }
}
```

```sh
> npm test
```

### Tester les Composables {#testing-composables}

> Cette section suppose que vous avez lu la section [Composables](/guide/reusability/composables).

Lorsqu'il est question de tester des composables, nous pouvons diviser en deux catégories : les composables qui ne dépendent pas d'une instance de composant hôte et ceux qui en dépendent.

Un composable dépend d'une instance de composant hôte quand il utilise une des API suivantes :

* Hooks du cycle de vie
* Provide / Inject

Si un composable utilise uniquement les API de réactivité, alors il peut être testé directement en l'invoquant et en vérifiant l'état et les méthodes qu'il retourne :

```js [counter.js]
import { ref } from 'vue'

export function useCounter() {
  const count = ref(0)
  const increment = () => count.value++

  return {
    count,
    increment
  }
}
```

```js [counter.test.js]
import { useCounter } from './counter.js'

test('useCounter', () => {
  const { count, increment } = useCounter()
  expect(count.value).toBe(0)

  increment()
  expect(count.value).toBe(1)
})
```

Un composable qui s'appuie sur des hooks de cycle de vie ou Provide / Inject doit être contenu dans un composant enveloppe pour être testé. Nous pouvons créer une fonction utilitaire comme ci-dessous :

```js [test-utils.js]
import { createApp } from 'vue'

export function withSetup(composable) {
  let result
  const app = createApp({
    setup() {
      result = composable()
      // supprime l'avertissement du template manquant
      return () => {}
    }
  })
  app.mount(document.createElement('div'))
  // renvoie le résultat et l'instance de l'application
  // pour les tests, provide/unmount
  return [result, app]
}
```

```js [foo.test.js]
import { withSetup } from './test-utils'
import { useFoo } from './foo'

test('useFoo', () => {
  const [result, app] = withSetup(() => useFoo(123))
  // simule provide pour tester les injections
  app.provide(...)
  // exécute les assertions
  expect(result.foo.value).toBe(1)
  // déclenche le hook onUnmounted si nécessaire
  app.unmount()
})
```

Il peut également être plus facile de tester des composables plus complexes en écrivant des tests contre le composant enveloppe en utilisant les techniques de [Test de Composant](#component-testing).

---

---
url: /translations.md
---

# Traductions {#translations}

## Langues disponibles {#available-languages}

* [English](https://vuejs.org/) \[[source](https://github.com/vuejs/docs)]
* [简体中文 / Simplified Chinese](https://cn.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-zh-cn)]
* [日本語 / Japanese](https://ja.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-ja)]
* [Українська / Ukrainian](https://ua.vuejs.org) \[[source](https://github.com/vuejs-translations/docs-ua)]
* [Français / French](https://fr.vuejs.org) \[[source](https://github.com/vuejs-translations/docs-fr)]
* [한국어 / Korean](https://ko.vuejs.org) \[[source](https://github.com/vuejs-translations/docs-ko)]
* [Português / Portuguese](https://pt.vuejs.org) \[[source](https://github.com/vuejs-translations/docs-pt)]
* [বাংলা / Bengali](https://bn.vuejs.org) \[[source](https://github.com/vuejs-translations/docs-bn)]
* [Italiano / Italian](https://it.vuejs.org) \[[source](https://github.com/vuejs-translations/docs-it)]
* [فارسی / Persian](https://fa.vuejs.org) \[[source](https://github.com/vuejs-translations/docs-fa)]
* [Русский / Russian](https://ru.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-ru)]
* [Čeština / Czech](https://cs.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-cs)]
* [繁體中文 / Traditional Chinese](https://zh-hk.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-zh-hk)]
* [Polski / Polonais](https://pl.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-pl)]

## Work in Progress Languages {#work-in-progress-languages}

* [العربية / Arabic](https://ar.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-ar)]
* [Español / Spanish](https://vue3-spanish-docs.netlify.app/) \[[source](https://github.com/icarusgk/vuejs-spanish-docs)]
* [Deutsch / Allemand](https://de.vuejs.org/) \[[source](https://github.com/vuejs-translations/docs-de)]

## Commencer une nouvelle traduction {#starting-a-new-translation}

La documentation de Vue a récemment subi une révision majeure, ainsi les traductions dans d'autres langues sont toujours manquantes ou en cours de développement.

Nous saluons les efforts de la communauté pour fournir plus de traductions. Les efforts de traduction sont gérés dans l'organisation GitHub [vuejs-translations](https://github.com/vuejs-translations/). Si vous souhaitez contribuer, veuillez consulter les [Directives de traduction](https://github.com/vuejs-translations/guidelines/blob/main/README.md) pour commencer.

---

---
url: /guide/built-ins/transition.md
---
# Transition {#transition}

Vue propose deux composants natifs qui peuvent aider à travailler avec des transitions et des animations en réponse à un changement d'état :

* `<Transition>`pour appliquer des animations lorsqu'un élément ou un composant entre et sort du DOM. Ceci est couvert sur cette page.

* `<TransitionGroup>` pour appliquer des animations lorsqu'un élément ou un composant est inséré, supprimé ou déplacé dans une liste `v-for`. Ceci est couvert dans [le chapitre suivant](/guide/built-ins/transition-group).

Outre ces deux composants, nous pouvons également appliquer des animations dans Vue en utilisant d'autres techniques telles que le basculement des classes CSS ou des animations basées sur l'état via des liaisons de style. Ces techniques supplémentaires sont traitées dans le chapitre [Techniques d'animation](/guide/extras/animation).

## Le composant `<Transition>` {#the-transition-component}

`<Transition>` est un composant intégré : cela signifie qu'il est disponible dans n'importe quel template de composant sans avoir à l'enregistrer. Il peut être utilisé pour appliquer des animations d'entrée et de sortie sur des éléments ou des composants qui lui sont transmis via son slot par défaut. L'entrée ou la sortie peut être déclenchée par l'une des actions suivantes :

* Rendu conditionnel via `v-if`
* Affichage conditionnel via `v-show`
* Basculement des composants dynamiques via l'élément spécial `<component>`
* Changer l'attribut spécial `key`

Voici un exemple de l'utilisation la plus basique :

```vue-html
<button @click="show = !show">Toggle</button>
<Transition>
  <p v-if="show">hello</p>
</Transition>
```

```css
/* nous vous expliquerons ensuite ce que font ces classes ! */
.v-enter-active,
.v-leave-active {
  transition: opacity 0.5s ease;
}

.v-enter-from,
.v-leave-to {
  opacity: 0;
}
```

[Essayer en ligne](https://play.vuejs.org/#eNpVkEFuwyAQRa8yZZNWqu1sunFJ1N4hSzYUjRNUDAjGVJHluxcCipIV/OG/pxEr+/a+TwuykfGogvYEEWnxR2H17F0gWCHgBBtMwc2wy9WdsMIqZ2OuXtwfHErhlcKCb8LyoVoynwPh7I0kzAmA/yxEzsKXMlr9HgRr9Es5BTue3PlskA+1VpFTkDZq0i3niYfU6anRmbqgMY4PZeH8OjwBfHhYIMdIV1OuferQEoZOKtIJ328TgzJhm8BabHR3jeC8VJqusO8/IqCM+CnsVqR3V/mfRxO5amnkCPuK5B+6rcG2fydshks=)

[Essayer en ligne](https://play.vuejs.org/#eNpVkMFuAiEQhl9lyqlNuouXXrZo2nfwuBeKs0qKQGBAjfHdZZfVrAmB+f/M/2WGK/v1vs0JWcdEVEF72vQWz94Fgh0OMhmCa28BdpLk+0etAQJSCvahAOLBnTqgkLA6t/EpVzmCP7lFEB69kYRFAYi/ROQs/Cij1f+6ZyMG1vA2vj3bbN1+b1Dw2lYj2yBt1KRnXRwPudHDnC6pAxrjBPe1n78EBF8MUGSkixnLNjdoCUMjFemMn5NjUGacnboqPVkdOC+Vpgus2q8IKCN+T+suWENwxyWJXKXMyQ5WNVJ+aBqD3e6VSYoi)

:::tip
`<Transition>` ne prend en charge qu'un seul élément ou composant comme contenu du slot. Si le contenu est un composant, le composant doit également avoir un seul élément racine.
:::

Lorsqu'un élément d'un composant `<Transition>` est inséré ou supprimé, voici ce qui se passe :

1. Vue détectera automatiquement si l'élément cible a des transitions CSS ou des animations appliquées. Si c'est le cas, un certain nombre de [classes de transition CSS](#transition-classes) seront ajoutées / supprimées aux moments appropriés.

2. S'il existe des écouteurs pour les [hooks JavaScript](#javascript-hooks), ces hooks seront appelés aux moments appropriés.

3. Si aucune transition / animation CSS n'est détectée et qu'aucun hook JavaScript n'est fourni, les opérations DOM d'insertion et / ou de suppression seront exécutées lors du prochain rafraîchissement d'animation du navigateur.

## Transitions basées sur le CSS {#css-based-transitions}

### Classes de transition {#transition-classes}

Six classes sont appliquées pour les transitions entrée / sortie.

![Diagramme de transition](./images/transition-classes.png)

1. `v-enter-from` : état de départ pour l'entrée. Ajoutée avant l'insertion de l'élément, supprimée une frame après l'insertion de l'élément.

2. `v-enter-active` : état actif pour l'entrée. Appliquée pendant toute la phase d'entrée. Ajoutée avant l'insertion de l'élément, supprimée à la fin de la transition / animation. Cette classe peut être utilisée pour définir la durée, le retard et la courbe d'accélération de la transition entrante.

3. `v-enter-to` : état de fin pour l'entrée. Ajoutée une frame après l'insertion de l'élément (en même temps `v-enter-from` est supprimée), supprimée lorsque la transition / animation se termine.

4. `v-leave-from` : état de départ pour la sortie. Ajoutée immédiatement lorsqu'une transition de sortie est déclenchée, supprimée après une frame.

5. `v-leave-active` : état actif pour la sortie. Appliquée pendant toute la phase de sortie. Ajoutée immédiatement lorsqu'une transition de sortie est déclenchée, supprimée lorsque la transition/animation se termine. Cette classe peut être utilisée pour définir la durée, le retard et la courbe d'accélération de la transition de sortie.

6. `v-leave-to` : état de fin pour la sortie. Ajoutée une frame après le déclenchement d'une transition de sortie (en même temps `v-leave-from` est supprimée), supprimée lorsque la transition/animation se termine.

`v-enter-active` et `v-leave-active` nous donnent la possibilité de spécifier différentes courbes d'accélération pour les transitions entrée/sortie, dont nous verrons un exemple dans les sections suivantes.

### Transitions nommées {#named-transitions}

Une transition peut être nommée via la prop `name` :

```vue-html
<Transition name="fade">
  ...
</Transition>
```

Pour une transition nommée, ses classes de transition seront préfixées par son nom au lieu de `v`. Par exemple, la classe appliquée pour la transition ci-dessus sera `fade-enter-active` au lieu de `v-enter-active`. Le CSS pour la transition de fondu devrait ressembler à ceci :

```css
.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.5s ease;
}

.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}
```

### Transitions CSS {#css-transitions}

`<Transition>` est le plus souvent utilisé en combinaison avec [les transitions CSS natives](https://developer.mozilla.org/fr/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions), comme on le voit dans l'exemple basique ci-dessus. La propriété CSS `transition` est un raccourci qui nous permet de spécifier plusieurs aspects d'une transition, y compris les propriétés qui doivent être animées, la durée de la transition et les [courbes d'accélération](https://developer.mozilla.org/fr/docs/Web/CSS/easing-function).

Voici un exemple plus avancé qui effectue la transition de plusieurs propriétés, avec différentes durées et courbes d'accélération pour l'entrée et la sortie :

```vue-html
<Transition name="slide-fade">
  <p v-if="show">hello</p>
</Transition>
```

```css
/*
  Les animations d'entrée et de sortie peuvent utiliser différentes
  durées et fonctions de temporisation.
*/
.slide-fade-enter-active {
  transition: all 0.3s ease-out;
}

.slide-fade-leave-active {
  transition: all 0.8s cubic-bezier(1, 0.5, 0.8, 1);
}

.slide-fade-enter-from,
.slide-fade-leave-to {
  transform: translateX(20px);
  opacity: 0;
}
```

[Essayer en ligne](https://play.vuejs.org/#eNqFkc9uwjAMxl/F6wXQKIVNk1AX0HbZC4zDDr2E4EK0NIkStxtDvPviFQ0OSFzyx/m+n+34kL16P+lazMpMRBW0J4hIrV9WVjfeBYIDBKzhCHVwDQySdFDZyipnY5Lu3BcsWDCk0OKosqLoKcmfLoSNN5KQbyTWLZGz8KKMVp+LKju573ivsuXKbbcG4d3oDcI9vMkNiqL3JD+AWAVpoyadGFY2yATW5nVSJj9rkspDl+v6hE/hHRrjRMEdpdfiDEkBUVxWaEWkveHj5AzO0RKGXCrSHcKBIfSPKEEaA9PJYwSUEXPX0nNlj8y6RBiUHd5AzCOodq1VvsYfjWE4G6fgEy/zMcxG17B9ZTyX8bV85C5y1S40ZX/kdj+GD1P/zVQA56XStC9h2idJI/z7huz4CxoVvE4=)

[Essayer en ligne](https://play.vuejs.org/#eNqFkc1uwjAMgF/F6wk0SmHTJNQFtF32AuOwQy+hdSFamkSJ08EQ776EbMAkJKTIf7I/O/Y+ezVm3HvMyoy52gpDi0rh1mhL0GDLvSTYVwqg4cQHw2QDWCRv1Z8H4Db6qwSyHlPkEFUQ4bHixA0OYWckJ4wesZUn0gpeainqz3mVRQzM4S7qKlss9XotEd6laBDu4Y03yIpUE+oB2NJy5QSJwFC8w0iIuXkbMkN9moUZ6HPR/uJDeINSalaYxCjOkBBgxeWEijnayWiOz+AcFaHNeU2ix7QCOiFK4FLCZPzoALnDXHt6Pq7hP0Ii7/EGYuag9itR5yv8FmgH01EIPkUxG8F0eA2bJmut7kbX+pG+6NVq28WTBTN+92PwMDHbSAXQhteCdiVMUpNwwuMassMP8kfAJQ==)

### Animations CSS {#css-animations}

[Les animations CSS natives](https://developer.mozilla.org/fr/docs/Web/CSS/CSS_Animations/Using_CSS_animations) sont appliquées de la même manière que les transitions CSS, à la différence que `*-enter-from` n'est pas supprimée immédiatement après l'insertion de l'élément, mais lors d'un événement `animationend`.

Pour la plupart des animations CSS, nous pouvons simplement les déclarer sous les classes `*-enter-active` et `*-leave-active`. Voici un exemple :

```vue-html
<Transition name="bounce">
  <p v-if="show" style="text-align: center;">
    Hello here is some bouncy text!
  </p>
</Transition>
```

```css
.bounce-enter-active {
  animation: bounce-in 0.5s;
}
.bounce-leave-active {
  animation: bounce-in 0.5s reverse;
}
@keyframes bounce-in {
  0% {
    transform: scale(0);
  }
  50% {
    transform: scale(1.25);
  }
  100% {
    transform: scale(1);
  }
}
```

[Essayer en ligne](https://play.vuejs.org/#eNqNksGOgjAQhl9lJNmoBwRNvCAa97YP4JFLbQZsLG3TDqzG+O47BaOezCYkpfB9/0wHbsm3c4u+w6RIyiC9cgQBqXO7yqjWWU9wA4813KH2toUpo9PKVEZaExg92V/YRmBGvsN5ZcpsTGGfN4St04Iw7qg8dkTWwF5qJc/bKnnYk7hWye5gm0ZjmY0YKwDlwQsTFCnWjGiRpaPtjETG43smHPSpqh9pVQKBrjpyrfCNMilZV8Aqd5cNEF4oFVo1pgCJhtBvnjEAP6i1hRN6BBUg2BZhKHUdvMmjWhYHE9dXY/ygzN4PasqhB75djM2mQ7FUSFI9wi0GCJ6uiHYxVsFUGcgX67CpzP0lahQ9/k/kj9CjDzgG7M94rT1PLLxhQ0D+Na4AFI9QW98WEKTQOMvnLAOwDrD+wC0Xq/Ubusw/sU+QL/45hskk9z8Bddbn)

[Essayer en ligne](https://play.vuejs.org/#eNqNUs2OwiAQfpWxySZ66I8mXioa97YP4LEXrNNKpEBg2tUY330pqOvJmBBgyPczP1yTb2OyocekTJirrTC0qRSejbYEB2x4LwmulQI4cOLTWbwDWKTeqkcE4I76twSyPcaX23j4zS+WP3V9QNgZyQnHiNi+J9IKtrUU9WldJaMMrGEynlWy2em2lcjyCPMUALazXDlBwtMU79CT9rpXNXp4tGYGhlQ0d7UqAUcXOeI6bluhUtKmhEVhzisgPFPKpWhVCTUqQrt6ygD8oJQajmgRhAOnO4RgdQm8yd0tNzGv/D8x/8Dy10IVCzn4axaTTYNZymsSA8YuciU6PrLL6IKpUFBkS7cKXXwQJfIBPyP6IQ1oHUaB7QkvjfUdcy+wIFB8PeZIYwmNtl0JruYSp8XMk+/TXL7BzbPF8gU6L95hn8D4OUJnktsfM1vavg==)

### Classes de transition personnalisées {#custom-transition-classes}

Vous pouvez également spécifier des classes de transition personnalisées en transmettant les props suivantes à `<Transition>` :

* `enter-from-class`
* `enter-active-class`
* `enter-to-class`
* `leave-from-class`
* `leave-active-class`
* `leave-to-class`

Celles-ci remplaceront les noms de classes conventionnels. Ceci est particulièrement utile lorsque vous souhaitez combiner le système de transition de Vue avec une bibliothèque d'animation CSS existante, telle que [Animate.css](https://daneden.github.io/animate.css/) :

```vue-html
<!-- en supposant que Animate.css est inclus sur la page -->
<Transition
  name="custom-classes"
  enter-active-class="animate__animated animate__tada"
  leave-active-class="animate__animated animate__bounceOutRight"
>
  <p v-if="show">hello</p>
</Transition>
```

[Essayer en ligne](https://play.vuejs.org/#eNqNUctuwjAQ/BXXF9oDsZB6ogbRL6hUcbSEjLMhpn7JXtNWiH/vhqS0R3zxPmbWM+szf02pOVXgSy6LyTYhK4A1rVWwPsWM7MwydOzCuhw9mxF0poIKJoZC0D5+stUAeMRc4UkFKcYpxKcEwSenEYYM5b4ixsA2xlnzsVJ8Yj8Mt+LrbTwcHEgxwojCmNxmHYpFG2kaoxO0B2KaWjD6uXG6FCiKj00ICHmuDdoTjD2CavJBCna7KWjZrYK61b9cB5pI93P3sQYDbxXf7aHHccpVMolO7DS33WSQjPXgXJRi2Cl1xZ8nKkjxf0dBFvx2Q7iZtq94j5jKUgjThmNpjIu17ZzO0JjohT7qL+HsvohJWWNKEc/NolncKt6Goar4y/V7rg/wyw9zrLOy)

[Essayer en ligne](https://play.vuejs.org/#eNqNUcFuwjAM/RUvp+1Ao0k7sYDYF0yaOFZCJjU0LE2ixGFMiH9f2gDbcVKU2M9+tl98Fm8hNMdMYi5U0tEEXraOTsFHho52mC3DuXUAHTI+PlUbIBLn6G4eQOr91xw4ZqrIZXzKVY6S97rFYRqCRabRY7XNzN7BSlujPxetGMvAAh7GtxXLtd/vLSlZ0woFQK0jumTY+FJt7ORwoMLUObEfZtpiSpRaUYPkmOIMNZsj1VhJRWeGMsFmczU6uCOMHd64lrCQ/s/d+uw0vWf+MPuea5Vp5DJ0gOPM7K4Ci7CerPVKhipJ/moqgJJ//8ipxN92NFdmmLbSip45pLmUunOH1Gjrc7ezGKnRfpB4wJO0ZpvkdbJGpyRfmufm+Y4Mxo1oK16n9UwNxOUHwaK3iQ==)

### Utiliser les transitions et les animations ensemble {#using-transitions-and-animations-together}

Vue doit attacher des écouteurs d'événements afin de savoir quand une transition est terminée. Cela peut être `transitionend` ou `animationend`, selon le type de règles CSS appliquées. Si vous n'utilisez que l'un ou l'autre, Vue peut automatiquement détecter le bon type.

Cependant, dans certains cas, vous voudrez peut-être avoir les deux sur le même élément, par exemple avoir une animation CSS déclenchée par Vue, ainsi qu'un effet de transition CSS au survol. Dans ces cas, vous devrez déclarer explicitement le type dont vous voulez que Vue se soucie en passant la prop `type`, avec une valeur de `animation` ou `transition` :

```vue-html
<Transition type="animation">...</Transition>
```

### Transitions imbriquées et durées de transition explicites {#nested-transitions-and-explicit-transition-durations}

Bien que les classes de transition ne soient appliquées qu'à l'élément enfant direct dans `<Transition>`, nous pouvons effectuer la transition d'éléments imbriqués à l'aide de sélecteurs CSS imbriqués :

```vue-html
<Transition name="nested">
  <div v-if="show" class="outer">
    <div class="inner">
      Hello
    </div>
  </div>
</Transition>
```

```css
/* règles qui ciblent les éléments imbriqués */
.nested-enter-active .inner,
.nested-leave-active .inner {
  transition: all 0.3s ease-in-out;
}

.nested-enter-from .inner,
.nested-leave-to .inner {
  transform: translateX(30px);
  opacity: 0;
}

/* ... autre CSS nécessaire omis */
```

Nous pouvons même ajouter un délai de transition à l'élément imbriqué lors de l'entrée, ce qui crée une séquence d'animation d'entrée décalée :

```css{3}
/* retarde l'entrée de l'élément imbriqué pour un effet décalé */
.nested-enter-active .inner {
  transition-delay: 0.25s;
}
```

Cependant, cela crée un petit problème. Par défaut, le composant `<Transition>` tente de déterminer automatiquement quand la transition est terminée en écoutant le **premier** événement `transitionend` ou `animationend` sur l'élément de transition racine. Avec une transition imbriquée, le comportement souhaité doit attendre que les transitions de tous les éléments internes soient terminées.

Dans de tels cas, vous pouvez spécifier une durée de transition explicite (en millisecondes) à l'aide de la prop `duration` sur le composant `<Transition>`. La durée totale doit correspondre au délai plus la durée de transition de l'élément interne :

```vue-html
<Transition :duration="550">...</Transition>
```

[Essayer en ligne](https://play.vuejs.org/#eNqVVd9v0zAQ/leO8LAfrE3HNKSFbgKmSYMHQNAHkPLiOtfEm2NHttN2mvq/c7bTNi1jgFop9t13d9995ziPyfumGc5bTLJkbLkRjQOLrm2uciXqRhsHj2BwBiuYGV3DAUEPcpUrrpUlaKUXcOkBh860eJSrcRqzUDxtHNaNZA5pBzCets5pBe+4FPz+Mk+66Bf+mSdXE12WEsdphMWQiWHKCicoLCtaw/yKIs/PR3kCitVIG4XWYUEJfATFFGIO84GYdRUIyCWzlra6dWg2wA66dgqlts7c+d8tSqk34JTQ6xqb9TjdUiTDOO21TFvrHqRfDkPpExiGKvBITjdl/L40ulVFBi8R8a3P17CiEKrM4GzULIOlFmpQoSgrl8HpKFpX3kFZu2y0BNhJxznvwaJCA1TEYcC4E3MkKp1VIptjZ43E3KajDJiUMBqeWUBmcUBUqJGYOT2GAiV7gJAA9Iy4GyoBKLH2z+N0W3q/CMC2yCCkyajM63Mbc+9z9mfvZD+b071MM23qLC69+j8PvX5HQUDdMC6cL7BOTtQXCJwpas/qHhWIBdYtWGgtDWNttWTmThu701pf1W6+v1Hd8Xbz+k+VQxmv8i7Fv1HZn+g/iv2nRkjzbd6npf/Rkz49DifQ3dLZBBYOJzC4rqgCwsUbmLYlCAUVU4XsCd1NrCeRHcYXb1IJC/RX2hEYCwJTvHYVMZoavbBI09FmU+LiFSzIh0AIXy1mqZiFKaKCmVhiEVJ7GftHZTganUZ56EYLL3FykjhL195MlMM7qxXdmEGDPOG6boRE86UJVPMki+p4H01WLz4Fm78hSdBo5xXy+yfsd3bpbXny1SA1M8c82fgcMyW66L75/hmXtN44a120ktDPOL+h1bL1HCPsA42DaPdwge3HcO/TOCb2ZumQJtA15Yl65Crg84S+BdfPtL6lezY8C3GkZ7L6Bc1zNR0=)

Si nécessaire, vous pouvez également spécifier des valeurs distinctes pour les durées d'entrée et de sortie à l'aide d'un objet :

```vue-html
<Transition :duration="{ enter: 500, leave: 800 }">...</Transition>
```

### Considérations relatives aux performances {#performance-considerations}

Vous remarquerez peut-être que les animations présentées ci-dessus utilisent principalement des propriétés telles que "transform" et "opacity". Ces propriétés sont efficaces pour animer car :

1. Elles n'affectent pas la mise en page du document pendant l'animation, elles ne déclenchent donc pas de calculs de mise en page CSS coûteux sur chaque image d'animation.

2. La plupart des navigateurs modernes peuvent tirer parti de l'accélération matérielle GPU lors de l'animation de `transform`.

En comparaison, des propriétés telles que `height` ou `margin` déclencheront la mise en page CSS, elles sont donc beaucoup plus coûteuses à animer et doivent être utilisées avec prudence.

## Hooks JavaScript {#javascript-hooks}

Vous pouvez vous connecter au processus de transition avec JavaScript en écoutant les événements sur le composant `<Transition>` :

```vue-html
<Transition
  @before-enter="onBeforeEnter"
  @enter="onEnter"
  @after-enter="onAfterEnter"
  @enter-cancelled="onEnterCancelled"
  @before-leave="onBeforeLeave"
  @leave="onLeave"
  @after-leave="onAfterLeave"
  @leave-cancelled="onLeaveCancelled"
>
  <!-- ... -->
</Transition>
```

```js
// appelée avant que l'élément ne soit inséré dans le DOM.
// utilisez ceci pour définir l'état "enter-from" de l'élément.
function onBeforeEnter(el) {}

// appelée une frame après l'insertion de l'élément.
// utilisez ceci pour démarrer l'animation d'entrée.
function onEnter(el, done) {
  // appelle la fonction de rappel done pour indiquer la fin de la transition
  // facultative si utilisée en combinaison avec CSS
  done()
}

// appelée lorsque la transition enter est terminée.
function onAfterEnter(el) {}

// appelée lorsque la transition enter est annulée avant la fin.
function onEnterCancelled(el) {}

// appelée avant le hook de sortie.
// la plupart du temps, vous devez simplement utiliser le hook de sortie.
function onBeforeLeave(el) {}

// appelée lorsque la transition de sortie démarre.
// utilisez ceci pour démarrer l'animation de sortie.
function onLeave(el, done) {
  // appelle la fonction de rappel done pour indiquer la fin de la transition
  // facultative si utilisée en combinaison avec CSS
  done()
}

// appelée lorsque la transition de sortie est terminée et que
// l'élément a été supprimé du DOM.
function onAfterLeave(el) {}

// uniquement disponible avec les transitions v-show
function onLeaveCancelled(el) {}
```

```js
export default {
  // ...
  methods: {
    // appelée avant que l'élément ne soit inséré dans le DOM.
    // utilisez ceci pour définir l'état "enter-from" de l'élément
    onBeforeEnter(el) {},

    // appelée une frame après l'insertion de l'élément.
    // utilisez ceci pour démarrer l'animation d'entrée.
    onEnter(el, done) {
      // appelle la fonction de rappel done pour indiquer la fin de la transition.
      // facultative si utilisée en combinaison avec CSS
      done()
    },

    // appelée lorsque la transition enter est terminée.
    onAfterEnter(el) {},

    // appelée lorsque la transition d'entrée est annulée avant d'être achevée.
    onEnterCancelled(el) {},

    // appelée avant le hook de sortie.
    // la plupart du temps, vous devez simplement utiliser le hook de sortie.
    onBeforeLeave(el) {},

    // appelée lorsque la transition de sortie démarre.
    // utilisez ceci pour démarrer l'animation de sortie.
    onLeave(el, done) {
      // appelle la fonction de rappel done pour indiquer la fin de la transition
      // facultative si utilisée en combinaison avec CSS
      done()
    },

    // appelée lorsque la transition de sortie est terminée et que
    // l'élément a été supprimé du DOM.
    onAfterLeave(el) {},

    // uniquement disponible avec les transitions v-show
    onLeaveCancelled(el) {}
  }
}
```

Ces hooks peuvent être utilisés en combinaison avec des transitions / animations CSS ou seuls.

Lors de l'utilisation de transitions JavaScript uniquement, il est généralement judicieux d'ajouter la prop `:css="false"`. Cela indique explicitement à Vue d'ignorer la détection automatique des transitions CSS. En plus d'être légèrement plus performant, cela empêche également les règles CSS d'interférer accidentellement avec la transition :

```vue-html{3}
<Transition
  ...
  :css="false"
>
  ...
</Transition>
```

Avec `:css="false"`, nous sommes également entièrement responsables du contrôle de la fin de la transition. Dans ce cas, les rappels `done` sont requis pour les hooks `@enter` et `@leave`. Sinon, les hooks seront appelés de manière synchrone et la transition se terminera immédiatement.

Voici une démo utilisant la [bibliothèque GSAP](https://gsap.com/) pour réaliser les animations. Vous pouvez bien sûr utiliser toute autre bibliothèque d'animation de votre choix, par exemple [Anime.js](https://animejs.com/) ou [Motion One](https://motion.dev/) :

[Essayer en ligne](https://play.vuejs.org/#eNqNVMtu2zAQ/JUti8I2YD3i1GigKmnaorcCveTQArpQFCWzlkiCpBwHhv+9Sz1qKYckJ3FnlzvD2YVO5KvW4aHlJCGpZUZoB5a7Vt9lUjRaGQcnMLyEM5RGNbDA0sX/VGWpHnB/xEQmmZIWe+zUI9z6m0tnWr7ymbKVzAklQclvvFSG/5COmyWvV3DKJHTdQiRHZN0jAJbRmv9OIA432/UE+jODlKZMuKcErnx8RrazP8woR7I1FEryKaVTU8aiNdRfwWZTQtQwi1HAGF/YB4BTyxNY8JpaJ1go5K/WLTfhdg1Xq8V4SX5Xja65w0ovaCJ8Jvsnpwc+l525F2XH4ac3Cj8mcB3HbxE9qnvFMRzJ0K3APuhIjPefmTTyvWBAGvWbiDuIgeNYRh3HCCDNW+fQmHtWC7a/zciwaO/8NyN3D6qqap5GfVnXAC89GCqt8Bp77vu827+A+53AJrOFzMhQdMnO8dqPpMO74Yx4wqxFtKS1HbBOMdIX4gAMffVp71+Qq2NG4BCIcngBKk8jLOvfGF30IpBGEwcwtO6p9sdwbNXPIadsXxnVyiKB9x83+c3N9WePN9RUQgZO6QQ2sT524KMo3M5Pf4h3XFQ7NwFyZQpuAkML0doEtvEHhPvRDPRkTfq/QNDgRvy1SuIvpFOSDQmbkWTckf7hHsjIzjltkyhqpd5XIVNN5HNfGlW09eAcMp3J+R+pEn7L)

[Essayer en ligne](https://play.vuejs.org/#eNqNVFFvmzAQ/is3pimNlABNF61iaddt2tukvfRhk/xiwIAXsJF9pKmq/PedDTSwh7ZSFLjvzvd9/nz4KfjatuGhE0ES7GxmZIu3TMmm1QahtLyFwugGFu51wRQAU+Lok7koeFcjPDk058gvlv07gBHYGTVGALbSDwmg6USPnNzjtHL/jcBK5zZxxQwZavVNFNqIHwqF8RUAWs2jn4IffCfqQz+mik5lKLWi3GT1hagHRU58aAUSshpV2YzX4ncCcbjZDp099GcG6ZZnEh8TuPR8S0/oTJhQjmQryLUSU0rUU8a8M9wtoWZTQtIwi0nAGJ/ZB0BwKxJYiJpblFko1a8OLzbhdgWXy8WzP99109YCqdIJmgifyfYuzmUzfFF2HH56o/BjAldx/BbRo7pXHKMjGbrl1IcciWn9fyaNfC8YsIueR5wCFFTGUVAEsEs7pOmDu6yW2f6GBW5o4QbeuScLbu91WdZiF/VlvgEtujdcWek09tx3qZ+/tXAzQU1mA8mCoeicneO1OxKP9yM+4ElmLaEFr+2AecVEn8sDZOSrSzv/1qk+sgAOa1kMOyDlu4jK+j1GZ70E7KKJAxRafKzdazi26s8h5dm+NLpTeQLvP27S6+urz/7T5aaUao26TWATt0cPPsgcK3f6Q1wJWVY4AVJtcmHWhueyo89+G38guD+agT5YBf39s25oIv5arehu8krYkLAs8BeG86DfuANYUCG2NomiTrX7Msx0E7ncl0bnXT04566M4PQPykWaWw==)

## Réutiliser les transitions {#reusable-transitions}

Les transitions peuvent être réutilisées via le système de composants de Vue. Pour créer une transition réutilisable, nous pouvons créer un composant qui encapsule le composant `<Transition>` et transmet le contenu de l'emplacement :

```vue{6} [MyTransition.vue]
<script>
// Logique du hook JavaScript...
</script>

<template>
  <!-- envelopper le composant de transition natif -->
  <Transition
    name="my-transition"
    @enter="onEnter"
    @leave="onLeave">
    <slot></slot> <!-- passer le contenu du slot -->
  </Transition>
</template>

<style>
/*
  CSS nécessaire...
  Remarque : évitez d'utiliser <style scoped> ici car il
  ne s'applique pas au contenu des slots.
*/
</style>
```

Désormais, `MyTransition` peut être importé et utilisé comme la version native :

```vue-html
<MyTransition>
  <div v-if="show">Hello</div>
</MyTransition>
```

## Transition à l'apparition {#transition-on-appear}

Si vous souhaitez également appliquer une transition sur le rendu initial d'un nœud, vous pouvez ajouter la prop `appear` :

```vue-html
<Transition appear>
  ...
</Transition>
```

## Transition entre élements {#transition-between-elements}

En plus de basculer un élément avec `v-if` /`v-show`, nous pouvons également faire la transition entre deux éléments en utilisant `v-if` /`v-else` /`v-else-if`, tant que nous nous assurons qu'un seul élément est affiché à tout moment :

```vue-html
<Transition>
  <button v-if="docState === 'saved'">Edit</button>
  <button v-else-if="docState === 'edited'">Save</button>
  <button v-else-if="docState === 'editing'">Cancel</button>
</Transition>
```

[Essayer en ligne](https://play.vuejs.org/#eNqdk8tu2zAQRX9loI0SoLLcFN2ostEi6BekmwLa0NTYJkKRBDkSYhj+9wxJO3ZegBGu+Lhz7syQ3Bd/nJtNIxZN0QbplSMISKNbdkYNznqCPXhcwwHW3g5QsrTsTGekNYGgt/KBBCEsouimDGLCvrztTFtnGGN4QTg4zbK4ojY4YSDQTuOiKwbhN8pUXm221MDd3D11xfJeK/kIZEHupEagrbfjZssxzAgNs5nALIC2VxNILUJg1IpMxWmRUAY9U6IZ2/3zwgRFyhowYoieQaseq9ElDaTRrkYiVkyVWrPiXNdiAcequuIkPo3fMub5Sg4l9oqSevmXZ22dwR8YoQ74kdsL4Go7ZTbR74HT/KJfJlxleGrG8l4YifqNYVuf251vqOYr4llbXz4C06b75+ns1a3BPsb0KrBy14Aymnerlbby8Vc8cTajG35uzFITpu0t5ufzHQdeH6LBsezEO0eJVbB6pBiVVLPTU6jQEPpKyMj8dnmgkQs+HmQcvVTIQK1hPrv7GQAFt9eO9Bk6fZ8Ub52Qiri8eUo+4dbWD02exh79v/nBP+H2PStnwz/jelJ1geKvk/peHJ4BoRZYow==)

## Modes des transitions {#transition-modes}

Dans l'exemple précédent, les éléments d'entrée et de sortie sont animés en même temps, et nous avons dû les appliquer `position: absolute` pour éviter le problème de mise en page lorsque les deux éléments sont présents dans le DOM.

Cependant, dans certains cas, ce n'est pas une option, ou ce n'est tout simplement pas le comportement souhaité. Nous pouvons vouloir que l'élément sortant soit animé en premier, et que l'élément entrant ne soit inséré **qu'après** que l'animation de départ soit terminée. Orchestrer manuellement de telles animations serait très compliqué - heureusement, nous pouvons activer ce comportement en passant à `<Transition>` la prop `mode` :

```vue-html
<Transition mode="out-in">
  ...
</Transition>
```

Voici la démo précédente avec `mode="out-in"` :

`<Transition>` prend également en charge `mode="in-out"`, bien qu'il soit beaucoup moins fréquemment utilisé.

## Transition entre composants {#transition-between-components}

`<Transition>` peut également être utilisé autour des [composants dynamiques](/guide/essentials/component-basics#dynamic-components) :

```vue-html
<Transition name="fade" mode="out-in">
  <component :is="activeComponent"></component>
</Transition>
```

[Essayer en ligne](https://play.vuejs.org/#eNqtksFugzAMhl/F4tJNKtDLLoxWKnuDacdcUnC3SCGJiMmEqr77EkgLbXfYYZyI8/v77dinZG9M5npMiqS0dScMgUXqzY4p0RrdEZzAfnEp9fc7HuEMx063sPIZq6viTbdmHy+yfDwF5K2guhFUUcBUnkNvcelBGrjTooHaC7VCRXBAoT6hQTRyAH2w2DlsmKq1sgS8JuEwUCfxdgF7Gqt5ZqrMp+58X/5A2BrJCcOJSskPKP0v+K8UyvQENBjcsqTjjdAsAZe2ukHpI3dm/q5wXPZBPFqxZAf7gCrzGfufDlVwqB4cPjqurCChFSjeBvGRN+iTA9afdE+pUD43FjG/bSHsb667Mr9qJot89vCBMl8+oiotDTL8ZsE39UnYpRN0fQlK5A5jEE6BSVdiAdrwWtAAm+zFAnKLr0ydA3pJDDt0x/PrMrJifgGbKdFPfCwpWU+TuWz5omzfVCNcfJJ5geL8pqtFn5E07u7fSHFOj6TzDyUDNEM=)

[Essayer en ligne](https://play.vuejs.org/#eNqtks9ugzAMxl/F4tJNamGXXVhWqewVduSSgStFCkkUDFpV9d0XJyn9t8MOkxBg5/Pvi+Mci51z5TxhURdi7LxytG2NGpz1BB92cDvYezvAqqxixNLVjaC5ETRZ0Br8jpIe93LSBMfWAHRBYQ0aGms4Jvw6Q05rFvSS5NNzEgN4pMmbcwQgO1Izsj5CalhFRLDj1RN/wis8olpaCQHh4LQk5IiEll+owy+XCGXcREAHh+9t4WWvbFvAvBlsjzpk7gx5TeqJtdG4LbawY5KoLtR/NGjYoHkw+PTSjIqUNWDkwOK97DHUMjVEdqKNMqE272E5dajV+JvpVlSLJllUF4+QENX1ERox0kHzb8m+m1CEfpOgYYgpqVHOmJNpgLQQa7BOdooO8FK+joByxLc4tlsiX6s7HtnEyvU1vKTCMO+4pWKdBnO+0FfbDk31as5HsvR+Hl9auuozk+J1/hspz+mRdPoBYtonzg==)

## Transitions dynamiques {#dynamic-transitions}

Les props de `<Transition>` comme `name` peuvent aussi être dynamiques ! Il nous permet d'appliquer dynamiquement différentes transitions en fonction du changement d'état :

```vue-html
<Transition :name="transitionName">
  <!-- ... -->
</Transition>
```

Cela peut être utile lorsque vous avez défini des transitions/animations CSS à l'aide des conventions de classes de transition de Vue et que vous souhaitez basculer entre elles.

Vous pouvez également appliquer un comportement différent avec les hooks de transition JavaScript en fonction de l'état actuel de votre composant. Enfin, le moyen ultime de créer des transitions dynamiques consiste à utiliser des [composants de transition réutilisables](#reusable-transitions) qui acceptent des props pour modifier la nature de la ou des transitions à utiliser. Cela peut sembler ringard, mais la seule limite est vraiment votre imagination.

## Transitions avec l'attribut key {#transitions-with-the-key-attribute}

Parfois, vous devez forcer le nouveau rendu d'un élément DOM pour qu'une transition se produise.

Prenons par exemple ce composant de compteur :

```vue
<script setup>
import { ref } from 'vue'
const count = ref(0)

setInterval(() => count.value++, 1000)
</script>

<template>
  <Transition>
    <span :key="count">{{ count }}</span>
  </Transition>
</template>
```

```vue
<script>
export default {
  data() {
    return {
      count: 1,
      interval: null
    }
  },
  mounted() {
    this.interval = setInterval(() => {
      this.count++
    }, 1000)
  },
  beforeDestroy() {
    clearInterval(this.interval)
  }
}
</script>
<template>
  <Transition>
    <span :key="count">{{ count }}</span>
  </Transition>
</template>
```

Si nous avions exclu l'attribut `key`, seul le nœud de texte serait mis à jour et donc aucune transition ne serait produit. Cependant, avec l'attribut `key`, Vue sait créer un nouvel élément `span` chaque fois que `count` change et donc le composant `Transition` a 2 éléments différents entre lesquels faire la transition.

[Essayer en ligne](https://play.vuejs.org/#eNp9UsFu2zAM/RVCl6Zo4nhYd/GcAtvQQ3fYhq1HXTSFydTKkiDJbjLD/z5KMrKgLXoTHx/5+CiO7JNz1dAja1gbpFcuQsDYuxtuVOesjzCCxx1MsPO2gwuiXnzkhhtpTYggbW8ibBJlUV/mBJXfmYh+EHqxuITNDYzcQGFWBPZ4dUXEaQnv6jrXtOuiTJoUROycFhEpAmi3agCpRQgbzp68cA49ZyV174UJKiprckxIcMJA84hHImc9oo7jPOQ0kQ4RSvH6WXW7JiV6teszfQpDPGqEIK3DLSGpQbazsyaugvqLDVx77JIhbqp5wsxwtrRvPFI7NWDhEGtYYVrQSsgELzOiUQw4I2Vh8TRgA9YJqeIR6upDABQh9TpTAPE7WN3HlxLp084Foi3N54YN1KWEVpOMkkO2ZJHsmp3aVw/BGjqMXJE22jml0X93STRw1pReKSe0tk9fMxZ9nzwVXP5B+fgK/hAOCePsh8dAt4KcnXJR+D3S16X07a9veKD3KdnZba+J/UbyJ+Zl0IyF9rk3Wxr7jJenvcvnrcz+PtweItKuZ1Np0MScMp8zOvkvb1j/P+776jrX0UbZ9A+fYSTP)

[Essayer en ligne](https://play.vuejs.org/#eNp9U8tu2zAQ/JUFTwkSyw6aXlQ7QB85pIe2aHPUhZHWDhOKJMiVYtfwv3dJSpbbBgEMWJydndkdUXvx0bmi71CUYhlqrxzdVAa3znqCBtey0wT7ygA0kuTZeX4G8EidN+MJoLadoRKuLkdAGULfS12C6bSGDB/i3yFx2tiAzaRIjyoUYxesICDdDaczZq1uJrNETY4XFx8G5Uu4WiwW55PBA66txy8YyNvdZFNrlP4o/Jdpbq4M/5bzYxZ8IGydloR8Alg2qmcVGcKqEi9eOoe+EqnExXsvTVCkrBkQxoKTBspn3HFDmprp+32ODA4H9mLCKDD/R2E5Zz9+Ws5PpuBjoJ1GCLV12DASJdKGa2toFtRvLOHaY8vx8DrFMGdiOJvlS48sp3rMHGb1M4xRzGQdYU6REY6rxwHJGdJxwBKsk7WiHSyK9wFQhqh14gDyIVjd0f8Wa2/bUwOyWXwQLGGRWzicuChvKC4F8bpmrTbFU7CGL2zqiJm2Tmn03100DZUox5ddCam1ffmaMPJd3Cnj9SPWz6/gT2EbsUr88Bj4VmAljjWSfoP88mL59tc33PLzsdjaptPMfqP4E1MYPGOmfepMw2Of8NK0d238+JTZ3IfbLSFnPSwVB53udyX4q/38xurTuO+K6/Fqi8MffqhR/A==)

***

**Référence**

* [`<Transition>` API](/api/built-in-components#transition)

---

---
url: /guide/built-ins/transition-group.md
---
# TransitionGroup {#transitiongroup}

`<TransitionGroup>` est un composant natif conçu pour animer l'insertion, la suppression et le changement d'ordre des éléments ou des composants qui sont rendus dans une liste.

## Différences avec `<Transition>` {#differences-from-transition}

`<TransitionGroup>` prend en charge les mêmes props, classes de transition CSS et écouteurs de hooks JavaScript que `<Transition>`, avec les différences suivantes :

* Par défaut, il ne rend pas d'élément en contenant d'autres. Mais vous pouvez spécifier un élément à rendre avec la prop `tag`.

* [Les modes de transition](./transition#transition-modes) ne sont pas disponibles, car nous n'alternons plus entre des éléments qui s'excluent mutuellement.

* Les éléments à l'intérieur sont **contraints de toujours** avoir un attribut unique `key`.

* Les classes de transition CSS seront appliquées aux éléments individuels de la liste, **pas** au groupe/conteneur lui-même.

:::tip
Lorsqu'il est utilisé dans les [templates du DOM](/guide/essentials/component-basics#in-dom-template-parsing-caveats), il doit être référencé comme `<transition-group>`.
:::

## Transitions d'Entrée / Sortie {#enter-leave-transitions}

Voici un exemple d'application des transitions d'entrée / sortie dans une liste `v-for` en utilisant `<TransitionGroup>` :

```vue-html
<TransitionGroup name="list" tag="ul">
  <li v-for="item in items" :key="item">
    {{ item }}
  </li>
</TransitionGroup>
```

```css
.list-enter-active,
.list-leave-active {
  transition: all 0.5s ease;
}
.list-enter-from,
.list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}
```

## Transitions de mouvements {#move-transitions}

La démonstration ci-dessus présente des défauts évidents : lorsqu'un élément est inséré ou retiré, les éléments qui l'entourent "sautent" instantanément au lieu de se déplacer en douceur. Nous pouvons corriger ce problème en ajoutant quelques règles CSS supplémentaires :

```css{1,13-17}
.list-move, /* appliquer la transition aux éléments mobiles */
.list-enter-active,
.list-leave-active {
  transition: all 0.5s ease;
}

.list-enter-from,
.list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}

/* s'assure que les éléments sortants sont retirés du flux de la mise en page afin que le déplacement
   des animations soit calculé correctement. */
.list-leave-active {
  position: absolute;
}
```

Maintenant, c'est beaucoup mieux - elle s'anime même en douceur lorsque la liste entière est mélangée :

[Exemple complet](/examples/#list-transition)

### Classes de TransitionGroup personnalisées {#custom-transitiongroup-classes}

Vous pouvez également spécifier des classes de transition personnalisées pour l'élément mobile en passant la propriété `moveClass` à `<TransitionGroup>`, comme dans l'exemple suivant [Classes de transition personnalisées](/guide/built-ins/transition.html#custom-transition-classes).

## Échelonner des transitions de liste {#staggering-list-transitions}

En communiquant avec les transitions JavaScript par le biais d'attributs de données, il est également possible d'échelonner les transitions dans une liste. Tout d'abord, nous rendons l'index d'un élément comme un attribut de données sur l'élément du DOM :

```vue-html{11}
<TransitionGroup
  tag="ul"
  :css="false"
  @before-enter="onBeforeEnter"
  @enter="onEnter"
  @leave="onLeave"
>
  <li
    v-for="(item, index) in computedList"
    :key="item.msg"
    :data-index="index"
  >
    {{ item.msg }}
  </li>
</TransitionGroup>
```

Ensuite, dans les hooks JavaScript, nous animons l'élément avec un délai basé sur l'attribut de données. Cet exemple utilise la [bibliothèque GSAP](https://gsap.com/) pour réaliser l'animation :

```js{5}
function onEnter(el, done) {
  gsap.to(el, {
    opacity: 1,
    height: '1.6em',
    delay: el.dataset.index * 0.15,
    onComplete: done
  })
}
```

[Essayez l'exemple complet en ligne](https://play.vuejs.org/#eNqlVMuu0zAQ/ZVRNklRm7QLWETtBW4FSFCxYkdYmGSSmjp28KNQVfl3xk7SFyvEponPGc+cOTPNOXrbdenRYZRHa1Nq3lkwaF33VEjedkpbOIPGeg6lajtnsYIeaq1aiOlSfAlqDOtG3L8SUchSSWNBcPrZwNdCAqVqTZND/KxdibBDjKGf3xIfWXngCNs9k4/Udu/KA3xWWnPz1zW0sOOP6CcnG3jv9ImIQn67SvrpUJ9IE/WVxPHsSkw97gbN0zFJZrB5grNPrskcLUNXac2FRZ0k3GIbIvxLSsVTq3bqF+otM5jMUi5L4So0SSicHplwOKOyfShdO1lariQo+Yy10vhO+qwoZkNFFKmxJ4Gp6ljJrRe+vMP3yJu910swNXqXcco1h0pJHDP6CZHEAAcAYMydwypYCDAkJRdX6Sts4xGtUDAKotIVs9Scpd4q/A0vYJmuXo5BSm7JOIEW81DVo77VR207ZEf8F23LB23T+X9VrbNh82nn6UAz7ASzSCeANZe0AnBctIqqbIoojLCIIBvoL5pJw31DH7Ry3VDKsoYinSii4ZyXxhBQM2Fwwt58D7NeoB8QkXfDvwRd2XtceOsCHkwc8KCINAk+vADJppQUFjZ0DsGVGT3uFn1KSjoPeKLoaYtvCO/rIlz3vH9O5FiU/nXny/pDT6YGKZngg0/Zg1GErrMbp6N5NHxJFi3N/4dRkj5IYf5ULxCmiPJpI4rIr4kHimhvbWfyLHOyOzQpNZZ57jXNy4nRGFLTR/0fWBqe7w==)

[Essayez l'exemple complet en ligne](https://play.vuejs.org/#eNqtVE2P0zAQ/SujXNqgNmkPcIjaBbYCJKg4cSMcTDJNTB07+KNsVfW/M3aabNpyQltViT1vPPP8Zian6H3bJgeHURatTKF5ax9yyZtWaQuVYS3stGpg4peTXOayUNJYEJwea/ieS4ATNKbKYPKoXYGwRZzAeTYGPrNizxE2NZO30KZ2xR6+Kq25uTuGFrb81vrFyQo+On0kIJc/PCV8CmxL3DEnLJy8e8ksm8bdGkCjdVr2O4DfDvWRgtGN/JYC0SOkKVTTOotl1jv3hi3d+DngENILkey4sKinU26xiWH9AH6REN/Eqq36g3rDDE7jhMtCuBLN1NbcJIFEHN9RaNDWqjQDAyUfcac0fpA+CYoRCRSJsUeBiWpZwe2RSrK4w2rkVe2rdYG6LD5uH3EGpZI4iuurTdwDNBjpRJclg+UlhP914UnMZfIGm8kIKVEwciYivhoGLQlQ4hO8gkWyfD1yVHJDKgu0mAUmPXLuxRkYb5Ed8H8YL/7BeGx7Oa6hkLmk/yodBoo21BKtYBZpB7DikroKDvNGUeZ1HoVmyCNIO/ibZtJwy5X8pJVru9CWVeTpRB51+6wwhgw7Jgz2tnc/Q6/M0ZeWwKvmGZye0Wu78PIGexC6swdGxEnw/q6HOYUkt9DwMwhKxfS6GpY+KPHc45G8+6EYAV7reTjucf/uwUtSmvvTME1wDuISlVTwTqf0RiiyrtKR0tEs6r5l84b645dRkr5zoT8oXwBMHg2Tlke+jbwhj2prW5OlqZPtvkroYqnH3lK9nLgI46scnf8Cn22kBA==)

***

**Référence**

* [Référence de l'API `<TransitionGroup>`](/api/built-in-components#transitiongroup)

---

---
url: /tutorial.md
---


---

---
url: /api/utility-types.md
---
# Types utilitaires {#utility-types}

:::info
Cette page ne liste que quelques types d'utilitaires couramment utilisés et dont l'utilisation peut nécessiter une explication. Pour une liste complète des types exportés, consultez le [code source](https://github.com/vuejs/core/blob/main/packages/runtime-core/src/index.ts#L131).
:::

## PropType\<T> {#proptype-t}

Utilisé pour annoter une prop avec des types plus avancés lors de l'utilisation de déclarations de props à l'exécution.

* **Exemple**

  ```ts
  import type { PropType } from 'vue'

  interface Book {
    title: string
    author: string
    year: number
  }

  export default {
    props: {
      book: {
        // fournit un type plus spécifique à `Object`.
        type: Object as PropType<Book>,
        required: true
      }
    }
  }
  ```

* **Voir aussi** [Guide - Typer les props des composants](/guide/typescript/options-api#typing-component-props)

## MaybeRef\<T> {#mayberef}

* Supporté à partir de la version 3.3

Alias pour `T | Ref<T>`. Utile pour annoter les arguments des [Composables](/guide/reusability/composables.html).

## MaybeRefOrGetter\<T> {#maybereforgetter}

* Supporté à partir de la version 3.3

Alias pour `T | Ref<T> | (() => T)`. Utile pour annoter les arguments des [Composables](/guide/reusability/composables.html).

## ExtractPropTypes\<T> {#extractproptypes}

Extrait les types de props à partir d'un objet d'options de props au moment de l'exécution. Les types extraits sont destinés à un usage interne, c'est-à-dire les props résolues reçues par le composant. Cela signifie que les props booléennes et les props avec des valeurs par défaut sont toujours définies, même si elles ne sont pas obligatoires.

Pour extraire les props destinées à être utilisées publiquement, c'est-à-dire les props que le composant parent est autorisé à transmettre, utilisez [`ExtractPublicPropTypes`](#extractpublicproptypes).

* **Exemple**

  ```ts
  const propsOptions = {
    foo: String,
    bar: Boolean,
    baz: {
      type: Number,
      required: true
    },
    qux: {
      type: Number,
      default: 1
    }
  } as const

  type Props = ExtractPropTypes<typeof propsOptions>
  // {
  //   foo?: string,
  //   bar: boolean,
  //   baz: number,
  //   qux: number
  // }
  ```

## ExtractPublicPropTypes\<T> {#extractpublicproptypes}

* Supporté à partir de la version 3.3

Extrait les types de props à partir d'un objet d'options de props. Les types extraits sont destinés à un usage public, c'est-à-dire les props que le parent est autorisé à transmettre.

* **Exemple**

  ```ts
  const propsOptions = {
    foo: String,
    bar: Boolean,
    baz: {
      type: Number,
      required: true
    },
    qux: {
      type: Number,
      default: 1
    }
  } as const

  type Props = ExtractPublicPropTypes<typeof propsOptions>
  // {
  //   foo?: string,
  //   bar?: boolean,
  //   baz: number,
  //   qux?: number
  // }
  ```

## ComponentCustomProperties {#componentcustomproperties}

Utilisé pour augmenter le type de l'instance du composant afin de prendre en charge les propriétés globales personnalisées.

* **Exemple**

  ```ts
  import axios from 'axios'

  declare module 'vue' {
    interface ComponentCustomProperties {
      $http: typeof axios
      $translate: (key: string) => string
    }
  }
  ```

  :::tip
  Les augmentations doivent être placées dans un fichier module `.ts` ou `.d.ts`. Consultez le [placement des annotations de types](/guide/typescript/options-api#augmenting-global-properties) pour plus de détails.
  :::

* **Voir aussi** [Guide - Augmenter les propriétés globales](/guide/typescript/options-api#augmenting-global-properties)

## ComponentCustomOptions {#componentcustomoptions}

Utilisé pour augmenter le type des options du composant afin de prendre en charge les options personnalisées.

* **Exemple**

  ```ts
  import { Route } from 'vue-router'

  declare module 'vue' {
    interface ComponentCustomOptions {
      beforeRouteEnter?(to: any, from: any, next: () => void): void
    }
  }
  ```

  :::tip
  Les augmentations doivent être placées dans un fichier module `.ts` ou `.d.ts`. Consultez le [placement des annotations de types](/guide/typescript/options-api#augmenting-global-properties) pour plus de détails.
  :::

* **Voir aussi** [Guide - Augmenter les options personnalisées](/guide/typescript/options-api#augmenting-custom-options)

## ComponentCustomProps {#componentcustomprops}

Utilisé pour augmenter les props TSX autorisées afin d'utiliser des props non déclarées sur des éléments TSX.

* **Exemple**

  ```ts
  declare module 'vue' {
    interface ComponentCustomProps {
      hello?: string
    }
  }

  export {}
  ```

  ```tsx
  // fonctionne maintenant même si hello n'est pas une prop déclarée
  <MyComponent hello="world" />
  ```

  :::tip
  Les augmentations doivent être placées dans un fichier module `.ts` ou `.d.ts`. Consultez le [placement des annotations de types](/guide/typescript/options-api#augmenting-global-properties) pour plus de détails.
  :::

## CSSProperties {#cssproperties}

Utilisé pour augmenter les valeurs autorisées dans les liaisons de propriétés de style.

* **Exemple**

  Permet l'utilisation de n'importe quelle propriété CSS personnalisée

  ```ts
  declare module 'vue' {
    interface CSSProperties {
      [key: `--${string}`]: string
    }
  }
  ```

  ```tsx
  <div style={ { '--bg-color': 'blue' } }>
  ```

  ```html
  <div :style="{ '--bg-color': 'blue' }"></div>
  ```

:::tip
Les augmentations doivent être placées dans un fichier module `.ts` ou `.d.ts`. Consultez le [placement des annotations de types](/guide/typescript/options-api#augmenting-global-properties) pour plus de détails.
:::

:::info Voir aussi
Les balises `<style>` des composants monofichiers permettent de lier les valeurs CSS à l'état dynamique des composants via la fonction CSS `v-bind`. Cela permet d'obtenir des propriétés personnalisées sans augmentation de type.

* [v-bind() dans du CSS](/api/sfc-css-features#v-bind-in-css)
  :::

---

---
url: /guide/typescript/options-api.md
---
# TypeScript avec l'Options API {#typescript-with-options-api}

> Cette page suppose que vous avez déjà pris connaissance de [l'utilisation de Vue avec TypeScript](./overview).

:::tip
Bien que Vue prenne en charge l'utilisation de TypeScript avec l'Options API, il est recommandé d'utiliser Vue avec TypeScript via la Composition API car elle offre une inférence de type plus simple, plus efficace et plus robuste.
:::

## Typer les props d'un composant {#typing-component-props}

L'inférence de type pour les props dans l'Options API nécessite d'envelopper le composant avec `defineComponent()`. Grâce à ce dernier, Vue est capable de déduire les types des props en fonction de l'option `props`, en prenant en compte des options supplémentaires telles que `required : true` et `default` :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  // inférence de type activée
  props: {
    name: String,
    id: [Number, String],
    msg: { type: String, required: true },
    metadata: null
  },
  mounted() {
    this.name // type : string | undefined
    this.id // type : number | string | undefined
    this.msg // type : string
    this.metadata // type : any
  }
})
```

Cependant, les options `props` du runtime ne prennent en charge que l'utilisation des fonctions de constructeur comme type de prop - il n'y a aucun moyen de spécifier des types complexes tels que des objets avec des propriétés imbriquées ou des signatures d'appel de fonction.

Pour annoter des types de props complexes, nous pouvons utiliser le type utilitaire `PropType` :

```ts
import { defineComponent } from 'vue'
import type { PropType } from 'vue'

interface Book {
  title: string
  author: string
  year: number
}

export default defineComponent({
  props: {
    book: {
      // fournit un type plus spécifique à `Object`
      type: Object as PropType<Book>,
      required: true
    },
    // permet aussi d'annoter les fonctions
    callback: Function as PropType<(id: number) => void>
  },
  mounted() {
    this.book.title // string
    this.book.year // number

    // TS Error: argument of type 'string' is not
    // assignable to parameter of type 'number'
    this.callback?.('123')
  }
})
```

### Avertissements {#caveats}

Si votre version de TypeScript est inférieure à `4.7`, vous devez faire attention lorsque vous utilisez des valeurs de fonction pour les options `validator` et `default` d'une prop - assurez-vous d'utiliser des fonctions fléchées :

```ts
import { defineComponent } from 'vue'
import type { PropType } from 'vue'

interface Book {
  title: string
  year?: number
}

export default defineComponent({
  props: {
    bookA: {
      type: Object as PropType<Book>,
      // assurez-vous d'utiliser des fonctions fléchées si votre version de TypeScript est inférieure à 4.7
      default: () => ({
        title: 'Arrow Function Expression'
      }),
      validator: (book: Book) => !!book.title
    }
  }
})
```

Cela évite à TypeScript de devoir déduire le type de `this` à l'intérieur de ces fonctions, ce qui, malheureusement, peut faire échouer l'inférence de type. C'était une [limitation de conception](https://github.com/microsoft/TypeScript/issues/38845), et elle a été corrigé dans [TypeScript 4.7](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html#improved-function-inference-in-objects-and-methods).

## Typer les événements d'un composant {#typing-component-emits}

Nous pouvons déclarer les données d'un événement émis en utilisant la syntaxe objet de l'option `emits`. De plus, tous les événements émis non déclarés produiront une erreur de type lorsqu'ils seront appelés :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  emits: {
    addBook(payload: { bookName: string }) {
      // performe une validation durant le runtime
      return payload.bookName.length > 0
    }
  },
  methods: {
    onSubmit() {
      this.$emit('addBook', {
        bookName: 123 // Erreur de type !
      })

      this.$emit('non-declared-event') // Erreur de type !
    }
  }
})
```

## Typer les propriétés calculées {#typing-computed-properties}

Une propriété calculée déduit son type à partir de sa valeur de retour :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      message: 'Hello!'
    }
  },
  computed: {
    greeting() {
      return this.message + '!'
    }
  },
  mounted() {
    this.greeting // type : string
  }
})
```

Dans certains cas, vous pouvez vouloir annoter explicitement le type d'une propriété calculée pour vous assurer que son implémentation est correcte :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      message: 'Hello!'
    }
  },
  computed: {
    // annote explicitement le type retourné
    greeting(): string {
      return this.message + '!'
    },

    // annote une propriété calculée accessible en écriture
    greetingUppercased: {
      get(): string {
        return this.greeting.toUpperCase()
      },
      set(newValue: string) {
        this.message = newValue.toUpperCase()
      }
    }
  }
})
```

Des annotations explicites peuvent également être nécessaires dans de rares cas où TypeScript ne parvient pas à déduire le type d'une propriété calculée en raison de boucles d'inférence circulaires.

## Typer les gestionnaires d'événements {#typing-event-handlers}

Lorsque vous traitez des événements natifs du DOM, il peut être utile de typer correctement l'argument que vous passez au gestionnaire. Jetons un coup d'œil à cet exemple :

```vue
<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    handleChange(event) {
      // `event` a implicitement un type `any`
      console.log(event.target.value)
    }
  }
})
</script>

<template>
  <input type="text" @change="handleChange" />
</template>
```

Sans annotation de type, l'argument `event` aura implicitement un type `any`. Cela entraînera également une erreur TS si `"strict" : true` ou `"noImplicitAny" : true` sont utilisés dans `tsconfig.json`. Il est donc recommandé d'annoter explicitement l'argument des gestionnaires d'événements. De plus, vous pouvez avoir besoin de caster explicitement des propriétés sur `event` :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    handleChange(event: Event) {
      console.log((event.target as HTMLInputElement).value)
    }
  }
})
```

## Augmenter les propriétés globales {#augmenting-global-properties}

Certains plugins installent des propriétés disponibles globalement dans toutes les instances de composants via [`app.config.globalProperties`](/api/application#app-config-globalproperties). Par exemple, nous pouvons installer `this.$http` pour la récupération des données ou `this.$translate` pour l'internationalisation. Pour que cela fonctionne bien avec TypeScript, Vue expose une interface `ComponentCustomProperties` conçue pour être augmentée via [l'augmentation de module TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-merging#module-augmentation) :

```ts
import axios from 'axios'

declare module 'vue' {
  interface ComponentCustomProperties {
    $http: typeof axios
    $translate: (key: string) => string
  }
}
```

Voir aussi :

* [Tests TypeScript sur les extensions des types de composant](https://github.com/vuejs/core/blob/main/packages-private/dts-test/componentTypeExtensions.test-d.tsx)

### Placement des augmentations de type {#type-augmentation-placement}

Nous pouvons placer cette augmentation de type dans un fichier `.ts`, ou dans un fichier `*.d.ts` à l'échelle du projet. Dans les deux cas, assurez-vous qu'il est inclus dans `tsconfig.json`. Pour les auteurs de bibliothèques / plugins, ce fichier doit être spécifié dans la propriété `types` du `package.json`.

Pour profiter de l'augmentation de module, vous devez vous assurer que l'augmentation est placée dans un [module TypeScript](https://www.typescriptlang.org/docs/handbook/modules.html). En d'autres termes, le fichier doit contenir au moins un `import` ou un `export` de premier niveau, même s'il s'agit juste d'un `export {}`. Si l'augmentation est placée en dehors d'un module, elle écrasera les types originaux au lieu de les augmenter !

```ts
// Ne fonctionne pas, écrase les types d'origine.
declare module 'vue' {
  interface ComponentCustomProperties {
    $translate: (key: string) => string
  }
}
```

```ts
// Fonctionne correctement
export {}

declare module 'vue' {
  interface ComponentCustomProperties {
    $translate: (key: string) => string
  }
}
```

## Augmenter des options personnalisées {#augmenting-custom-options}

Certains plugins, par exemple `vue-router`, fournissent un support pour les options de composants personnalisées telles que `beforeRouteEnter` :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  beforeRouteEnter(to, from, next) {
    // ...
  }
})
```

Sans augmentation de type appropriée, les arguments de ce hook auront implicitement le type `any`. Nous pouvons augmenter l'interface `ComponentCustomOptions` pour supporter ces options personnalisées :

```ts
import { Route } from 'vue-router'

declare module 'vue' {
  interface ComponentCustomOptions {
    beforeRouteEnter?(to: Route, from: Route, next: () => void): void
  }
}
```

Maintenant l'option `beforeRouteEnter` sera correctement typée. Il est à noter que que c'est juste un exemple - les bibliothèques bien typées comme `vue-router` devraient effectuer automatiquement ces augmentations dans leurs propres définitions de type.

Le placement de cette augmentation est soumis aux [mêmes restrictions](#type-augmentation-placement) que les augmentations de propriétés globales.

Voir aussi :

* [Tests TypeScript sur les extensions des types de composant](https://github.com/vuejs/core/blob/main/packages-private/dts-test/componentTypeExtensions.test-d.tsx)

---

---
url: /guide/typescript/composition-api.md
---
# TypeScript avec la Composition API {#typescript-with-composition-api}

> Cette page part du principe que vous avez déjà pris connaissance de comment [utiliser Vue avec TypeScript](./overview).

## Typer les props des composants {#typing-component-props}

### Utiliser `<script setup>` {#using-script-setup}

Lorsque vous utilisez `<script setup>`, la macro `defineProps()` permet de déduire les types des props en fonction de l'argument qu'elle reçoit :

```vue
<script setup lang="ts">
const props = defineProps({
  foo: { type: String, required: true },
  bar: Number
})

props.foo // string
props.bar // number | undefined
</script>
```

Ceci est appelé "déclaration à l'exécution" de fait que l'argument passé à `defineProps()` sera utilisé comme l'option `props` lors de l'exécution.

Cependant, il est généralement plus simple de définir des props avec des types purs via un argument de type générique :

```vue
<script setup lang="ts">
const props = defineProps<{
  foo: string
  bar?: number
}>()
</script>
```

C'est ce qu'on appelle la "déclaration basée sur le type". Le compilateur fera de son mieux pour déduire les options à l'exécution équivalentes en fonction de l'argument de type. Dans ce cas, notre deuxième exemple compile avec exactement les mêmes options à l'exécution que le premier exemple.

Vous pouvez utiliser la déclaration basée sur les types OU la déclaration à l'exécution, mais vous ne pouvez pas utiliser les deux en même temps.

Nous pouvons également déplacer les types des props dans une interface séparée :

```vue
<script setup lang="ts">
interface Props {
  foo: string
  bar?: number
}

const props = defineProps<Props>()
</script>
```

Cela fonctionne également si `Props` est importé depuis un autre fichier, tel qu'une importation relative, un alias de chemin (par exemple, `@/types`) ou une dépendance externe (par exemple, `node_modules`). Cette fonctionnalité nécessite que TypeScript soit une dépendance de même niveau que Vue.

```vue
<script setup lang="ts">
import type { Props } from './foo'

const props = defineProps<Props>()
</script>
```

#### Limitations de syntaxe {#syntax-limitations}

Dans la version 3.2 et les versions antérieures, le paramètre de type générique pour `defineProps()` était limité à un littéral de type ou à une référence à une interface locale.

Cette limitation a été résolue en 3.3. La dernière version de Vue prend en charge le référencement importé et un ensemble limité de types complexes dans la position du paramètre de type. Cependant, étant donné que la conversion de type à l'exécution est toujours basée sur AST, certains types complexes qui nécessitent une analyse de type réelle, par exemple les types conditionnels ne sont pas pris en charge. Vous pouvez utiliser des types conditionnels pour le type d'une props, mais pas pour l'ensemble de l'objet props.

### Valeurs par défaut des props {#props-default-values}

En utilisant la déclaration basée sur le type, nous perdons la possibilité de déclarer des valeurs par défaut pour les props. Ceci peut être résolu par la [destructuration réactive des props](/guide/components/props#reactive-props-destructure)  :

```ts
interface Props {
  msg?: string
  labels?: string[]
}

const { msg = 'hello', labels = ['one', 'two'] } = defineProps<Props>()
```

Dans la version 3.4 et les versions antérieures, la destructuration réactive des props n'est pas activé par défaut. Une alternative est d'utiliser la macro de compilation `withDefaults` :

```ts
interface Props {
  msg?: string
  labels?: string[]
}

const props = withDefaults(defineProps<Props>(), {
  msg: 'hello',
  labels: () => ['one', 'two']
})
```

Ceci sera compilé en options à l'exécution `default` équivalentes aux props. De plus, `withDefaults` fournit des vérifications de type pour les valeurs par défaut, et assure que le type `props` retourné n'a pas les options facultatives pour les propriétés qui ont des valeurs déclarées par défaut.

:::info
Notez que les valeurs par défaut de référence mutables (comme les tableaux ou les objets) doivent être enveloppées dans des fonctions lors de l'utilisation de `withDefaults` afin d'éviter toute modification accidentelle et tout effet de bord externe. Cela permet de s'assurer que chaque instance de composant reçoit sa propre copie de la valeur par défaut. Ceci n'est **pas** nécessaire lors de l'utilisation de valeurs par défaut avec destructuration.
:::

### Sans `<script setup>` {#without-script-setup}

Si vous n'utilisez pas `<script setup>`, il est nécessaire d'utiliser `defineComponent()` pour activer l'inférence de type des props. Le type de l'objet props passé à `setup()` est déduit de l'option `props`.

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  props: {
    message: String
  },
  setup(props) {
    props.message // <-- type : string
  }
})
```

### Types complexes de props {#complex-prop-types}

Avec la déclaration basée sur le type, une prop peut utiliser un type complexe comme n'importe quel autre type :

```vue
<script setup lang="ts">
interface Book {
  title: string
  author: string
  year: number
}

const props = defineProps<{
  book: Book
}>()
</script>
```

Pour la déclaration à l'exécution, nous pouvons utiliser le type utilitaire `PropType` :

```ts
import type { PropType } from 'vue'

const props = defineProps({
  book: Object as PropType<Book>
})
```

Cela fonctionne de la même manière si nous spécifions directement l'option `props` :

```ts
import { defineComponent } from 'vue'
import type { PropType } from 'vue'

export default defineComponent({
  props: {
    book: Object as PropType<Book>
  }
})
```

L'option `props` est plus couramment utilisée avec l'Options API, vous trouverez donc des exemples plus détaillés dans le guide de [TypeScript avec l'Options API](/guide/typescript/options-api#typing-component-props). Les techniques présentées dans ces exemples s'appliquent également aux déclarations à l'exécution utilisant `defineProps()`.

## Typer les événements d'un composant {#typing-component-emits}

Dans `<script setup>`, la fonction `emit` peut également être typée en utilisant la déclaration à l'exécution OU la déclaration de type :

```vue
<script setup lang="ts">
// à l'exécution
const emit = defineEmits(['change', 'update'])

// basée sur la déclaration d'options
const emit = defineEmits({
  change: (id: number) => {
    // retourner `true` ou `false`
    // selon si validation ou échec
  },
  update: (value: string) => {
    // retourner `true` ou `false`
    // selon si validation ou échec
  }
})

// basée sur les types
const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()

// 3.3+ : syntaxe alternative, plus succincte
const emit = defineEmits<{
  change: [id: number]
  update: [value: string]
}>()
</script>
```

L'argument du type peut être l'un des suivants :

1. Un type de fonction, mais écrit comme un littéral de type avec les [*Call Signatures*](https://www.typescriptlang.org/docs/handbook/2/functions.html#call-signatures). Il sera utilisé comme type de la fonction `emit` renvoyée.
2. Un littéral de type où les clés sont les noms d'événement et les valeurs sont des tableaux ou des tuples représentant les paramètres supplémentaires acceptés pour l'événement. L'exemple ci-dessus utilise des tuples nommés afin que chaque argument puisse avoir un nom explicite.

Comme nous pouvons le constater, la déclaration de type nous permet d'exercer un contrôle beaucoup plus fin sur les contraintes de type des événements émis.

Lorsque l'on n'utilise pas `<script setup>`, `defineComponent()` est capable de déduire les événements autorisés pour la fonction `emit` exposée sur le contexte setup :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  emits: ['change'],
  setup(props, { emit }) {
    emit('change') // <-- vérification du type / auto-complétion
  }
})
```

## Typer `ref()` {#typing-ref}

Le type des refs est déduit à partir de leur valeur initiale :

```ts
import { ref } from 'vue'

// type déduit : Ref<number>
const year = ref(2020)

// => TS Error: Type 'string' is not assignable to type 'number'.
year.value = '2020'
```

Parfois, nous pouvons avoir besoin de spécifier des types complexes pour la valeur d'une ref. Nous pouvons le faire en utilisant le type `Ref` :

```ts
import { ref } from 'vue'
import type { Ref } from 'vue'

const year: Ref<string | number> = ref('2020')

year.value = 2020 // ok!
```

Ou, en passant un argument générique lors de l'appel de `ref()` pour remplacer l'inférence par défaut :

```ts
// type résultant : Ref<string | number>
const year = ref<string | number>('2020')

year.value = 2020 // ok!
```

Si vous spécifiez un argument de type générique mais omettez la valeur initiale, le type résultant sera un type d'union qui inclut `undefined` :

```ts
// type déduit : Ref<number | undefined>
const n = ref<number>()
```

## Typer `reactive()` {#typing-reactive}

`reactive()` déduit également de manière implicite le type à partir de son argument :

```ts
import { reactive } from 'vue'

// type déduit : { title: string }
const book = reactive({ title: 'Vue 3 Guide' })
```

Pour typer explicitement une propriété `reactive`, nous pouvons utiliser des interfaces :

```ts
import { reactive } from 'vue'

interface Book {
  title: string
  year?: number
}

const book: Book = reactive({ title: 'Vue 3 Guide' })
```

:::tip
Il n'est pas recommandé d'utiliser l'argument générique de `reactive()` car le type retourné, qui gère le déballage des refs imbriquées, est différent du type de l'argument générique.
:::

## Typer `computed()` {#typing-computed}

`computed()` déduit son type en fonction de la valeur de retour de l'accesseur :

```ts
import { ref, computed } from 'vue'

const count = ref(0)

// type déduit : ComputedRef<number>
const double = computed(() => count.value * 2)

// => TS Error: Property 'split' does not exist on type 'number'
const result = double.value.split('')
```

Vous pouvez également spécifier un type explicite via un argument générique :

```ts
const double = computed<number>(() => {
  // erreur de type si un nombre n'est pas retourné
})
```

## Typer les gestionnaires d'événements {#typing-event-handlers}

Lorsque vous traitez des événements natifs du DOM, il peut être utile de typer correctement l'argument que nous passons au gestionnaire. Jetons un coup d'œil à cet exemple :

```vue
<script setup lang="ts">
function handleChange(event) {
  // `event` a implicitement un type `any`
  console.log(event.target.value)
}
</script>

<template>
  <input type="text" @change="handleChange" />
</template>
```

Sans annotation de type, l'argument `event` aura implicitement un type `any`. Cela entraînera également une erreur TS si `"strict" : true` ou `"noImplicitAny" : true` sont utilisés dans `tsconfig.json`. Il est donc recommandé d'annoter explicitement l'argument des gestionnaires d'événements. De plus, vous pouvez avoir besoin de caster explicitement des propriétés sur `event` :

```ts
function handleChange(event: Event) {
  console.log((event.target as HTMLInputElement).value)
}
```

## Typer Provide / Inject {#typing-provide-inject}

Provide et Inject sont généralement utilisés dans des composants séparés. Pour typer correctement les valeurs injectées, Vue fournit une interface `InjectionKey`, qui est un type générique qui étend `Symbol`. Elle peut être utilisée pour synchroniser le type de la valeur injectée entre le fournisseur et le consommateur :

```ts
import { provide, inject } from 'vue'
import type { InjectionKey } from 'vue'

const key = Symbol() as InjectionKey<string>

provide(key, 'foo') // fournir une valeur qui n'est pas une chaîne de caractères va entraîner une erreur

const foo = inject(key) // type de foo : string | undefined
```

Il est recommandé de placer la clé d'injection dans un fichier séparé afin qu'elle puisse être importée dans plusieurs composants.

Lors de l'utilisation de clés d'injection sous la forme de chaînes de caractères, le type de la valeur injectée sera `unknown`, et devra être déclaré explicitement via un argument de type générique :

```ts
const foo = inject<string>('foo') // type : string | undefined
```

Notez que la valeur injectée peut toujours être `undefined`, car il n'y a aucune garantie qu'un fournisseur fournira cette valeur au moment de l'exécution.

Le type `undefined` peut être supprimé en fournissant une valeur par défaut :

```ts
const foo = inject<string>('foo', 'bar') // type : string
```

Si vous êtes sûr que la valeur est toujours fournie, vous pouvez également forcer le casting de la valeur :

```ts
const foo = inject('foo') as string
```

## Typer les refs de template {#typing-template-refs}

Avec Vue 3.5 et `@vue/language-tools` 2.1 (qui alimente à la fois le service linguistique de l'IDE et `vue-tsc`), le typage des refs créées par `useTemplateRef()` dans les SFC peut être **automatiquement déduit** pour les refs statiques en fonction de l'élément sur lequel l'attribut `ref` correspondant est utilisé.

Dans les cas où l'auto-inférence n'est pas possible, vous pouvez toujours convertir le template ref en un type explicite via l'argument générique :

```ts
const el = useTemplateRef<HTMLInputElement>('el')
```

Les références du template doivent être créées avec un argument de type générique explicite et une valeur initiale de `null` :

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue'

const el = ref<HTMLInputElement | null>(null)

onMounted(() => {
  el.value?.focus()
})
</script>

<template>
  <input ref="el" />
</template>
```

Pour obtenir la bonne interface du DOM, vous pouvez consulter les pages comme [MDN](https://developer.mozilla.org/fr/docs/Web/HTML/Element/input#technical_summary).

Notez que pour une sécurité de type stricte, il est nécessaire d'utiliser un chaînage optionnel ou des gardes de type lors de l'accès à `el.value`. Ceci s'explique par le fait que la valeur initiale d'une ref est `null` jusqu'à ce que le composant soit monté, et elle peut aussi être mise à `null` si l'élément référencé est démonté via un `v-if`.

## Typer les refs du template d'un composant {#typing-component-template-refs}

Avec Vue 3.5 et `@vue/language-tools` 2.1 (qui alimente à la fois le service linguistique de l'IDE et `vue-tsc`), le typage de refs créées par `useTemplateRef()` dans les SFC peut être **automatiquement déduit** pour les refs statiques en fonction de l'élément ou du composant sur lequel l'attribut `ref` correspondant est utilisé.

Dans les cas où l'auto-inférence n'est pas possible (par exemple, utilisation non-SFC ou composants dynamiques), vous pouvez toujours convertir la référence du template en un type explicite par l'intermédiaire de l'argument générique.

Pour obtenir le type d'instance d'un composant importé, nous devons d'abord obtenir son type via `typeof`, puis utiliser l'utilitaire intégré `InstanceType` de TypeScript pour extraire son type d'instance :

```vue{6,7} [App.vue]
<script setup lang="ts">
import { useTemplateRef } from 'vue'
import Foo from './Foo.vue'
import Bar from './Bar.vue'

type FooType = InstanceType<typeof Foo>
type BarType = InstanceType<typeof Bar>

const compRef = useTemplateRef<FooType | BarType>('comp')
</script>

<template>
  <component :is="Math.random() > 0.5 ? Foo : Bar" ref="comp" />
</template>
```

Dans les cas où le type exact du composant n'est pas disponible ou n'est pas important, `ComponentPublicInstance` peut être utilisé à la place. Cela n'inclura que les propriétés qui sont partagées par tous les composants, comme `$el` :

```ts
import { useTemplateRef } from 'vue'
import type { ComponentPublicInstance } from 'vue'

const child = useTemplateRef<ComponentPublicInstance>('child')
```

Dans le cas où le composant référencé est un [composant générique](/guide/typescript/overview.html#generic-components), par exemple `MyGenericModal` :

```vue [MyGenericModal.vue]
<script setup lang="ts" generic="ContentType extends string | number">
import { ref } from 'vue'

const content = ref<ContentType | null>(null)

const open = (newContent: ContentType) => (content.value = newContent)

defineExpose({
  open
})
</script>
```

Il doit être référencé en utilisant `ComponentExposed` de la bibliothèque [`vue-component-type-helpers`](https://www.npmjs.com/package/vue-component-type-helpers) car `InstanceType` ne fonctionnera pas.

```vue [App.vue]
<script setup lang="ts">
import { useTemplateRef } from 'vue'
import MyGenericModal from './MyGenericModal.vue'
import type { ComponentExposed } from 'vue-component-type-helpers'

const modal =
  useTemplateRef<ComponentExposed<typeof MyGenericModal>>('modal')

const openModal = () => {
  modal.value?.open('newValue')
}
</script>
```

Notez qu'avec `@vue/language-tools` 2.1+, les types des refs statiques des templates peuvent être automatiquement déduits et ce qui précède n'est nécessaire que dans les cas extrêmes.

## Typer les directives globales personnalisées {#typing-global-custom-directives}

Afin d'obtenir des indications de type et une vérification de type pour les directives personnalisées globales déclarées avec `app.directive()`, vous pouvez étendre `GlobalDirectives`

```ts [src/directives/highlight.ts]
import type { Directive } from 'vue'

export type HighlightDirective = Directive<HTMLElement, string>

declare module 'vue' {
  export interface GlobalDirectives {
    // préfixe avec v (v-highlight)
    vHighlight: HighlightDirective
  }
}

export default {
  mounted: (el, binding) => {
    el.style.backgroundColor = binding.value
  }
} satisfies HighlightDirective
```

```ts [main.ts]
import highlight from './directives/highlight'
// ...autre code
const app = createApp(App)
app.directive('highlight', highlight)
```

Utilisation dans un composant

```vue [App.vue]
<template>
  <p v-highlight="'blue'">This sentence is important!</p>
</template>
```

---

---
url: /guide/typescript/overview.md
---

# Utiliser Vue avec TypeScript {#using-vue-with-typescript}

Un système de typage comme TypeScript peut détecter de nombreuses erreurs courantes via une analyse statique au moment du build. Cela réduit le risque d'erreurs d'exécution en production et nous permet également de refactoriser le code avec plus de confiance dans les applications à grande échelle. TypeScript améliore également l'ergonomie des développeurs via l'auto-complétion basée sur le type dans les IDE.

Vue est écrit en TypeScript lui-même et fournit un support TypeScript nativement. Tous les packages Vue officiels sont livrés avec des déclarations de types prêts à l'emploi.

## Configuration du projet {#project-setup}

[`create-vue`](https://github.com/vuejs/create-vue), l'outil officiel de création de projet, offre les options pour construire un projet propulsé par [Vite](https://vite.dev/) et fonctionnant avec TypeScript.

### Vue d'ensemble {#overview}

Avec une configuration basée sur Vite, le serveur de développement et le bundler ne font que transpiler et n'effectuent aucune vérification de type. Cela garantit que le serveur de développement Vite reste extrêmement rapide même lorsque vous utilisez TypeScript.

* Pendant le développement, nous vous recommandons de vous fier à une bonne [configuration de votre IDE](#ide-support) pour un feedback instantané sur les erreurs de type.

* Si vous utilisez des SFC, utilisez [`vue-tsc`](https://github.com/vuejs/language-tools/tree/master/packages/tsc) pour la vérification du type en ligne de commande et pour la génération de déclarations de type. `vue-tsc` enveloppe `tsc`, l'interface en ligne de commande officielle de TypeScript. Il fonctionne en grande partie de la même manière que `tsc` sauf qu'il prend en charge les SFC de Vue en plus des fichiers TypeScript. Vous pouvez exécuter `vue-tsc` en mode *watch* en parallèle avec le serveur de développement Vite, ou utiliser un plugin Vite comme [vite-plugin-checker](https://vite-plugin-checker.netlify.app/) qui exécute les vérifications dans un thread de travail séparé.

* Vue CLI prend également en charge TypeScript, mais n'est plus recommandé. Voir [les notes ci-dessous](#note-on-vue-cli-and-ts-loader).

### Support des IDE {#ide-support}

* [Visual Studio Code](https://code.visualstudio.com/) (VS Code) est fortement recommandé pour son excellent support prêt à l'emploi pour TypeScript.

  * [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (précédemment Volar) est l'extension VS Code officielle qui fournit la prise en charge de TypeScript pour les SFC de Vue, ainsi que de nombreuses autres fonctionnalités intéressantes.

    :::tip
    Vue - Official remplace [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur), notre précédente extension VS Code officielle pour Vue 2. Si Vetur est actuellement installé, assurez-vous de le désactiver dans les projets Vue 3.
    :::

* [WebStorm](https://www.jetbrains.com/webstorm/) fournit également une prise en charge prête à l'emploi pour TypeScript et Vue. D'autres IDE JetBrains les prennent également en charge, soit prêts à l'emploi, soit via [un plugin gratuit](https://plugins.jetbrains.com/plugin/9442-vue-js). À partir de la version 2023.2, WebStorm et le plugin Vue sont livrés avec une prise en charge intégrée de Vue Language Server. Vous pouvez configurer le service Vue pour qu'il utilise l'intégration Volar sur toutes les versions de TypeScript, sous Settings > Languages and frameworks > TypeScript > Vue. Par défaut, Volar sera utilisé pour les versions TypeScript 5.0 et supérieures.

### Configurer `tsconfig.json` {#configuring-tsconfig-json}

Les projets construits via `create-vue` incluent un `tsconfig.json` préconfiguré. La configuration de base est résumée dans le package [`@vue/tsconfig`](https://github.com/vuejs/tsconfig). Au sein du projet, nous utilisons [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) pour nous assurer que les types de code corrects s'exécutent dans différents environnements (par exemple, le code d'application et le code de test doivent avoir différentes variables globales).

Lors de la configuration manuelle de `tsconfig.json`, certaines options notables incluent :

* [`compilerOptions.isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules) est défini sur `true` car Vite utilise [esbuild](https://esbuild.github.io/) pour transpiler TypeScript et est soumis à des limitations de transpilation de fichier unique. [`compilerOptions.verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax) est [un surensemble de `isolatedModules`](https://github.com/microsoft/TypeScript/issues/53601) et c'est aussi un bon choix - c'est ce que [`@vue/tsconfig`](https://github.com/vuejs/tsconfig) utilise.

* Si vous utilisez l'Options API, vous devez définir [`compilerOptions.strict`](https://www.typescriptlang.org/tsconfig#strict) sur `true` (ou au moins activer [`compilerOptions.noImplicitThis`](https://www.typescriptlang.org/tsconfig#noImplicitThis), qui fait partie de l'indicateur `strict`) pour tirer parti de la vérification de type de `this` dans les options de composant. Sinon, `this` sera traité comme `any`.

* Si vous avez configuré des alias de résolveur dans votre outil de construction, par exemple l'alias `@/*` configuré par défaut dans un projet `create-vue`, vous devez également le configurer pour TypeScript via [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths).

* Si vous avez l'intention d'utiliser TSX avec Vue, définissez [`compilerOptions.jsx`](https://www.typescriptlang.org/tsconfig#jsx) à `"preserve"`, et définissez [`compilerOptions.jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource) to `"vue"`.

Voir aussi :

* [Documentation officielle des options du compilateur TypeScript](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
* [Avertissements concernant la compilation TypeScript d'esbuild](https://esbuild.github.io/content-types/#typescript-caveats)

### Remarque à propos de Vue CLI et `ts-loader` {#note-on-vue-cli-and-ts-loader}

Dans les configurations basées sur Webpack telles que Vue CLI, il est courant d'effectuer une vérification de type dans le cadre du pipeline de transformation de module, par exemple avec `ts-loader`. Ceci, cependant, n'est pas une solution propre car le système de type a besoin de connaître l'ensemble du graphe de module pour effectuer des vérifications de type. L'étape de transformation d'un module individuel n'est tout simplement pas le bon endroit pour la tâche. Cela conduit aux problèmes suivants :

* `ts-loader` ne peut vérifier que le type d'un code post-transformé. Cela ne correspond pas aux erreurs que nous voyons dans les IDE ou de `vue-tsc`, qui renvoient directement au code source.

* La vérification de type peut être lente. Lorsqu'elle est effectuée dans le même thread /processus avec des transformations de code, cela affecte considérablement la vitesse de construction de l'ensemble de l'application.

* Nous avons déjà une vérification de type exécutée directement dans notre IDE dans un processus séparé, donc le ralentissement du coût de l'expérience de développement n'est tout simplement pas un bon compromis.

Si vous utilisez actuellement Vue 3 + TypeScript via Vue CLI, nous vous recommandons fortement de migrer vers Vite. Nous travaillons également sur les options du CLI pour activer le support de la transpilation TS uniquement, afin que vous puissiez passer à `vue-tsc` pour la vérification de type.

## Remarques générales d'utilisation {#general-usage-notes}

### `defineComponent()` {#definecomponent}

Pour permettre à TypeScript de déduire correctement les types dans les options de composant, nous devons définir les composants avec [`defineComponent()`](/api/general#definecomponent) :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  // inférence de type activée
  props: {
    name: String,
    msg: { type: String, required: true }
  },
  data() {
    return {
      count: 1
    }
  },
  mounted() {
    this.name // type: string | undefined
    this.msg // type: string
    this.count // type: number
  }
})
```

`defineComponent()` prend également en charge l'inférence des props passées à `setup()` lors de l'utilisation de la Composition API sans `<script setup>` :

```ts
import { defineComponent } from 'vue'

export default defineComponent({
  // inférence de type activée
  props: {
    message: String
  },
  setup(props) {
    props.message // type: string | undefined
  }
})
```

Voir aussi :

* [Note sur le Treeshaking de Webpack](/api/general#note-on-webpack-treeshaking)
* [Tests sur les types de `defineComponent`](https://github.com/vuejs/core/blob/main/packages-private/dts-test/defineComponent.test-d.tsx)

:::tip
`defineComponent()` permet également l'inférence de type pour les composants définis en JavaScript simple.
:::

### Utilisation dans les composants monofichiers {#usage-in-single-file-components}

Pour utiliser TypeScript dans les SFC, ajoutez l'attribut `lang="ts"` aux balises `<script>`. Lorsque `lang="ts"` est présent, toutes les expressions du template bénéficient également d'une vérification de type plus stricte.

```vue
<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      count: 1
    }
  }
})
</script>

<template>
  <!-- vérification du type et auto-complétion disponible -->
  {{ count.toFixed(2) }}
</template>
```

`lang="ts"` peut aussi être utilisé avec `<script setup>` :

```vue
<script setup lang="ts">
// TypeScript activé
import { ref } from 'vue'

const count = ref(1)
</script>

<template>
  <!-- vérification du type et auto-complétion disponible -->
  {{ count.toFixed(2) }}
</template>
```

### TypeScript dans les templates {#typescript-in-templates}

Le `<template>` prend également en charge TypeScript dans les expressions de liaison lorsque `<script lang="ts">` ou `<script setup lang="ts">` est utilisé. Ceci est utile dans les cas où vous devez effectuer un casting de type dans les expressions du template.

Voici un exemple :

```vue
<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  <!-- erreur parce que x pourrait être une string -->
  {{ x.toFixed(2) }}
</template>
```

Cela peut être contourné avec un casting littéral de type :

```vue{6}
<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  {{ (x as number).toFixed(2) }}
</template>
```

:::tip
Si vous utilisez Vue CLI ou une configuration basée sur Webpack, TypeScript dans les expressions de modèle nécessite `vue-loader@^16.8.0`.
:::

### Utilisation avec TSX {#usage-with-tsx}

Vue prend également en charge la création de composants avec JSX / TSX. Les détails sont couverts dans le guide [Fonction de rendu et JSX](/guide/extras/render-function.html#jsx-tsx).

## Composants génériques {#generic-components}

Les composants génériques sont pris en charge dans deux cas :

* Dans les composants monofichiers : [`<script setup>` avec l'attribut `generic`](/api/sfc-script-setup.html#generics)
* Fonction de rendu / composants JSX : [la signature de la fonction `defineComponent()`](/api/general.html#function-signature)

## Recettes spécifiques aux API {#api-specific-recipes}

* [TS avec la Composition API](./composition-api)
* [TS avec l'Options API](./options-api)

---

---
url: /guide/components/v-model.md
---
# v-model du composant {#component-v-model}

## Utilisation de base {#basic-usage}

`v-model` peut être utilisé sur un composant pour implémenter une liaison à double sens.

À partir de Vue 3.4, l'approche recommandée consiste à utiliser la macro [`defineModel()`](/api/sfc-script-setup#definemodel) :

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

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

<template>
  <div>Le v-model lié au parent est : {{ model }}</div>
  <button @click="update">Incrément</button>
</template>
```

Le parent peut alors lier une valeur avec `v-model` :

```vue-html [Parent.vue]
<Child v-model="countModel" />
```

La valeur retournée par `defineModel()` est une ref. On peut y accéder et la modifier comme n'importe quel autre ref, sauf qu'elle agit comme une liaison bidirectionnelle entre une valeur parent et une valeur locale :

* Sa `.value` est synchronisée avec la valeur liée au `v-model` parent ;
* Lorsqu'elle est modifiée par l'enfant, la valeur liée au parent est également mise à jour.

Cela signifie que vous pouvez également lier cette ref à un élément d'entrée natif avec `v-model`, ce qui permet d'envelopper les éléments d'entrée natifs tout en fournissant la même utilisation de `v-model` :

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

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

[Essayer en ligne](https://play.vuejs.org/#eNqFUtFKwzAU/ZWYl06YLbK30Q10DFSYigq+5KW0t11mmoQknZPSf/cm3eqEsT0l555zuefmpKV3WsfbBuiUpjY3XDtiwTV6ziSvtTKOLNZcFKQ0qiZRnATkG6JB0BIDJen2kp5iMlfSOlLbisw8P4oeQAhFPpURxVV0zWSa9PNwEgIHtRaZA0SEpOvbeduG5q5LE0Sh2jvZ3tSqADFjFHlGSYJkmhz10zF1FseXvIo3VklcrfX9jOaq1lyAedGOoz1GpyQwnsvQ3fdTqDnTwPhQz9eQf52ob+zO1xh9NWDBbIHRgXOZqcD19PL9GXZ4H0h03whUnyHfwCrReI+97L6RBdo+0gW3j+H9uaw+7HLnQNrDUt6oV3ZBzyhmsjiz+p/dSTwJfUx2+IpD1ic+xz5enwQGXEDJJaw8Gl2I1upMzlc/hEvdOBR6SNKAjqP1J6P/o6XdL11L5h4=)

### Sous le capot {#under-the-hood}

`defineModel` est une macro de commodité. Le compilateur l'étend de la manière suivante :

* Une propriété nommée `modelValue`, avec laquelle la valeur de la ref locale est synchronisée ;
* Un événement nommé `update:modelValue`, qui est émis lorsque la valeur de la ref locale est modifiée.

C'est ainsi que l'on mettrait en œuvre le même composant enfant que celui présenté ci-dessus avant la version 3.4 :

```vue [Child.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>
```

Ensuite, `v-model="foo"` dans le composant parent sera compilé en :

```vue-html [Parent.vue]
<Child
  :modelValue="foo"
  @update:modelValue="$event => (foo = $event)"
/>
```

Comme vous pouvez le voir, c'est un peu plus verbeux. Cependant, il est utile de comprendre ce qui se passe sous le capot.

Puisque `defineModel` déclare une prop, vous pouvez donc déclarer les options de la prop sous-jacente en la passant à `defineModel` :

```js
// rendre v-model obligatoire
const model = defineModel({ required: true })

// fournir une valeur par défaut
const model = defineModel({ default: 0 })
```

:::warning
Si vous avez une valeur `default` pour la propriété `defineModel` et que vous ne fournissez aucune valeur pour cette propriété à partir du composant parent, cela peut provoquer une désynchronisation entre les composants parent et enfant. Dans l'exemple ci-dessous, le composant parent `myRef` est undefined, mais le composant enfant `model` vaut 1 :

```vue [Child.vue]
<script setup>
const model = defineModel({ default: 1 })
</script>
```

```vue [Parent.vue]
<script setup>
const myRef = ref()
</script>

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

:::

Revenons tout d'abord sur la façon dont `v-model` est utilisé sur un élément natif :

```vue-html
<input v-model="searchText" />
```

Sous le capot, le compilateur de template transforme v-model en un équivalent plus verbeux pour nous. Ainsi, le code ci-dessus fait la même chose que ce qui suit :

```vue-html
<input
  :value="searchText"
  @input="searchText = $event.target.value"
/>
```

Lorsqu'il est utilisé sur un composant, `v-model` est alors équivalent à :

```vue-html
<CustomInput
  :model-value="searchText"
  @update:model-value="newValue => searchText = newValue"
/>
```

Toutefois, pour que cela fonctionne, le composant `<CustomInput>` doit faire deux choses :

1. Lier l'attribut value d'un élément natif `<input>` à la prop modelValue
2. Lorsqu'un événement natif `input` est déclenché, émettre un événement personnalisé `update:modelValue` avec la nouvelle valeur

Voici cela en action :

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

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

Maintenant, `v-model` devrait fonctionner parfaitement avec ce composant :

```vue-html
<CustomInput v-model="searchText" />
```

[Essayer en ligne](https://play.vuejs.org/#eNqFkctqwzAQRX9lEAEn4Np744aWrvoD3URdiHiSGvRCHpmC8b93JDfGKYGCkJjXvTrSJF69r8aIohHtcA69p6O0vfEuELzFgZx5tz4SXIIzUFT1JpfGCmmlxe/c3uFFRU0wSQtwdqxh0dLQwHSnNJep3ilS+8PSCxCQYrC3CMDgMKgrNlB8odaOXVJ2TgdvvNp6vSwHhMZrRcgRQLs1G5+M61A/S/ErKQXUR5immwXMWW1VEKX4g3j3Mo9QfXCeKU9FtvpQmp/lM0Oi6RP/qYieebHZNvyL0acLLODNmGYSxCogxVJ6yW1c2iWz/QOnEnY48kdUpMIVGSllD8t8zVZb+PkHqPG4iw==)

Une autre façon d'implémenter `v-model` dans ce composant consiste à utiliser une propriété `calculée` en écriture avec à la fois un accesseur et un mutateur. La méthode `get` doit renvoyer la propriété `modelValue` et la méthode `set` doit émettre l'événement correspondant :

```vue [CustomInput.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>
```

## Les arguments de `v-model` {#v-model-arguments}

`v-model` sur un composant peut également accepter un argument :

```vue-html
<MyComponent v-model:title="bookTitle" />
```

Dans le composant enfant, nous pouvons prendre en charge l'argument correspondant en passant une chaîne à `defineModel()` comme premier argument :

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

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

[Essayer en ligne](https://play.vuejs.org/#eNqFklFPwjAUhf9K05dhgiyGNzJI1PCgCWqUx77McQeFrW3aOxxZ9t+9LTAXA/q2nnN6+t12Db83ZrSvgE944jIrDTIHWJmZULI02iJrmIWctSy3umQRRaPOWhweNX0pUHiyR3FP870UZkyoTCuH7FPr3VJiAWzqSwfR/rbUKyhYatdV6VugTktTQHQjVBIfeYiEFgikpwi0YizZ3M2aplfXtklMWvD6UKf+CfrUVPBuh+AspngSd718yH+hX7iS4xihjUZYQS4VLPwJgyiI/3FLZSrafzAeBqFG4jgxeuEqGTo6OZfr0dZpRVxNuFWeEa4swL4alEQm+IQFx3tpUeiv56ChrWB41rMNZLsL+tbVXhP8zYIDuyeQzkN6HyBWb88/XgJ3ZxJ95bH/MN/B6aLyjMfYQ6VWhN3LBdqn8FdJtV66eY2g3HkoD+qTbcgLTo/jX+ra6D+449E47BOq5e039mr+gA==)

Si des options de prop sont également nécessaires, elles doivent être transmises après le nom du modèle :

```js
const title = defineModel('title', { required: true })
```

```vue [MyComponent.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>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9kE1rwzAMhv+KMIW00DXsGtKyMXYc7D7vEBplM8QfOHJoCfnvk+1QsjJ2svVKevRKk3h27jAGFJWoh7NXjmBACu4kjdLOeoIJPHYwQ+ethoJLi1vq7fpi+WfQ0JI+lCstcrkYQJqzNQMBKeoRjhG4LcYHbVvsofFfQUcCXhrteix20tRl9sIuOCBkvSHkCKD+fjxN04Ka57rkOOlrMwu7SlVHKdIrBZRcWpc3ntiLO7t/nKHFThl899YN248ikYpP9pj1V60o6sG1TMwDU/q/FZRxgeIPgK4uGcQLSZGlamz6sHKd1afUxOoGeeT298A9bHCMKxBfE3mTSNjl1vud5x8qNa76)

Dans ce cas, au lieu de la prop `modelValue` et de l'événement `update:modelValue` par défaut, le composant enfant doit s'attendre à une prop `title` et émettre un événement `update:title` pour mettre à jour la valeur du parent :

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

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

[Essayer en ligne](https://play.vuejs.org/#eNqFUNFqwzAM/BVhCm6ha9hryMrGnvcFdR9Mo26B2DGuHFJC/n2yvZakDAohtuTTne5G8eHcrg8oSlFdTr5xtFe2Ma7zBF/Xz45vFi3B2XcG5K6Y9eKYVFZZHBK8xrMOLcGoLMDphrqUMC6Ypm18rzXp9SZjATxS8PZWAVBDLZYg+xfT1diC9t/BxGEctHFtlI2wKR78468q7ttzQcgoTcgVQPXzuh/HzAnTVBVcp/58qz+lMqHelEinElAwtCrufGIrHhJYBPdfEs53jkM4yEQpj8k+miYmc5DBcRKYZeXxqZXGukDZPF1dWhQHUiK3yl63YbZ97r6nIe6uoup6KbmFFfbRCnHGyI4iwyaPPnqffgGMlsEM)

## Liaisons multiple avec `v-model` {#multiple-v-model-bindings}

En tirant parti de la possibilité de cibler une prop et un événement en particulier, comme nous l'avons appris précédemment avec les [arguments de `v-model`](#v-model-arguments), nous pouvons désormais créer plusieurs liaisons v-model sur une seule instance de composant.

Chaque v-model se synchronisera avec une prop différente, sans avoir besoin d'options supplémentaires dans le composant :

```vue-html
<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>
```

[Essayer en ligne](https://play.vuejs.org/#eNqFkstuwjAQRX/F8iZUAqKKHQpIfbAoUmnVx86bKEzANLEt26FUkf+9Y4MDSAg2UWbu9fjckVv6oNRw2wAd08wUmitLDNhGTZngtZLakpZoKIkjpZY1SdCadNK3Ab3IazhowzQ2/ES0MVFIYSwpucbvxA/qJXO5FsldlKr8qDxL8EKW7kEQAQsLtapyC1gRkq3vp217mOccwf8wwLksRSlYIoMvCNkOarmEahyODAT2J4yGgtFzhx8UDf5/r6c4NEs7CNqnpxkvbO0kcVjNhCyh5AJe/SW9pBPOV3DJGvu3dsKFaiyxf8qTW9gheQwVs4Z90BDm5oF47cF/Ht4aZC75argxUmD61g9ktJC14hXoN2U5ZmJ0TILitbyq5O889KxuoB/7xRqKnwv9jdn5HqPvGnDVWwTpNJvrFSCul2efi4DeiRigqdB9RfwAI6vGM+5tj41YIvaJL9C+hOfNxerLzHYWhImhPKh3uuBnFJ/A05XoR9zRcBTOMeGo+wcs+yse)

```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>
```

[Essayer en ligne](https://play.vuejs.org/#eNqNUc1qwzAMfhVjCk6hTdg1pGWD7bLDGIydlh1Cq7SGxDaOEjaC332yU6cdFNpLsPRJ348y8idj0qEHnvOi21lpkHWAvdmWSrZGW2Qjs1Azx2qrWyZoVMzQZwf2rWrhhKVZbHhGGivVTqsOWS0tfTeeKBGv+qjEMkJNdUaeNXigyCYjZIEKhNY0FQJVjBXHh+04nvicY/QOBM4VGUFhJHrwBWPDutV7aPKwslbU35Q8FCX/P+GJ4oB/T3hGpEU2m+ArfpnxytX2UEsF71abLhk9QxDzCzn7QCvVYeW7XuGyWSpH0eP6SyuxS75Eb/akOpn302LFYi8SiO8bJ5PK9DhFxV/j0yH8zOnzoWr6+SbhbifkMSwSsgByk1zzsoABFKZY2QNgGpiW57Pdrx2z3JCeI99Svvxh7g8muf2x)

```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>
```

[Essayer en ligne](https://play.vuejs.org/#eNqNkk1rg0AQhv/KIAETSJRexYYWeuqhl9JTt4clmSSC7i7rKCnif+/ObtYkELAiujPzztejQ/JqTNZ3mBRJ2e5sZWgrVNUYbQm+WrQfskE4WN1AmuXRwQmpUELh2Qv3eJBdTTAIBbDTLluhoraA4VpjXHNwL0kuV0EIYJE6q6IFcKhsSwWk7/qkUq/nq5be+aa5JztGfrmHu8t8GtoZhI2pJaGzAMrT03YYQk0YR3BnruSOZe5CXhKnC3X7TaP3WBc+ZaOc/1kk3hDJvYILRQGfQzx3Rct8GiJZJ7fA7gg/AmesNszMrUIXFpxbwCfZSh09D0Hc7tbN6sAWm4qZf6edcZgxrMHSdA3RF7PTn1l8lTIdhbXp1/CmhOeJRNHLupv4eIaXyItPdJEFD7R8NM0Ce/d/ZCTtESnzlVZXhP/vHbeZaT0tPdf59uONfx7mDVM=)

## Gestion des modificateurs de `v-model` {#handling-v-model-modifiers}

Lorsque nous avons appris les liaisons d'entrée de formulaire, nous avons vu que `v-model` avait des [modificateurs natifs](/guide/essentials/forms#modifiers) - `.trim`, `.number` et `.lazy`. Dans certains cas, vous pouvez également souhaiter que le `v-model` de votre composant d'entrée personnalisé prenne en charge les modificateurs personnalisés.

Créons un exemple de modificateur personnalisé, `capitalize`, qui met en majuscule la première lettre de la chaîne de caractères fournie par la liaison `v-model` :

```vue-html
<MyComponent v-model.capitalize="myText" />
```

Les modificateurs ajoutés à un composant `v-model` sont accessibles dans le composant enfant en déstructurant la valeur de retour de `defineModel()` comme suit :

```vue{4}
<script setup>
const [model, modifiers] = defineModel()

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

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

Pour ajuster conditionnellement la façon dont la valeur doit être lue / écrite en fonction des modificateurs, nous pouvons passer les options `get` et `set` à `defineModel()`. Ces deux options reçoivent la valeur sur get / set du modèle ref et doivent retourner une valeur transformée. C'est ainsi que nous pouvons utiliser l'option `set` pour implémenter le modificateur `capitalize` :

```vue{4-6}
<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>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9UsFu2zAM/RVClzhY5mzoLUgHdEUPG9Bt2LLTtIPh0Ik6WRIkKksa5N9LybFrFG1OkvgeyccnHsWNc+UuoliIZai9cgQBKbpP0qjWWU9wBI8NnKDxtoUJUycDdH+4tXwzaOgMl/NRLNVlMoA0tTWBoD2scE9wnSoWk8lUmuW8a8rt+EHYOl0R8gtgtVUBlHGRoK6cokqrRwxAW4RGea6mkQg9HGwEboZ+kbKWY027961doy6f86+l6ERIAXNus5wPPcVMvNB+yZOaiZFw/cKYftI/ufEM+FCNQh/+8tRrbJTB+4QUxySWqxa7SkecQn4DqAaKIWekeyAAe0fRG8h5Zb2t/A0VH6Yl2d/Oob+tAhZTeHfGg1Y1Fh/Z6ZR66o5xhRTh8OnyXyy7f6CDSw5S59/Z3WRpOl91lAL70ahN+RCsYT/zFFIk95RG/92RYr+kWPTzSVFpbf9/zTHyEWd9vN5i/e+V+EPYp5gUPzwG9DuUYsCo8htkrQm++/Ut6x5AVh01sy+APzFYHZPGjvY5mjXLHvGy2i95K5TZrMLdntCEfqgkNDuc+VLwkqQNe2v0Z7lX5VX/M+L0BFEuPdc=)

```vue{11-13}
<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>
```

[Essayer en ligne](https://play.vuejs.org/#eNp9Us1Og0AQfpUJF5ZYqV4JNTaNxyYmVi/igdCh3QR2N7tDIza8u7NLpdU0nmB+v5/ZY7Q0Jj10GGVR7iorDYFD6sxDoWRrtCU4gsUaBqitbiHm1ngqrfuV5j+Fik7ldH6R83u5GaBQlVaOoO03+Emw8BtFHCeFyucjKMNxQNiapiTkCGCzlw6kMh1BVRpJZSO/0AEe0Pa0l2oHve6AYdBmvj+/ZHO4bfUWm/Q8uSiiEb6IYM4A+XxCi2bRH9ZX3BgVGKuNYwFbrKXCZx+Jo0cPcG9l02EGL2SZ3mxKr/VW1hKty9hMniy7hjIQCSweQByHBIZCDWzGDwi20ps0Yjxx4MR73Jktc83OOPFHGKk7VZHUKkyFgsAEAqcG2Qif4WWYUml3yOp8wldlDSLISX+TvPDstAemLeGbVvvSLkncJSnpV2PQrkqHLOfmVHeNrFDcMz3w0iBQE1cUzMYBbuS2f55CPj4D6o0/I41HzMKsP+u0kLOPoZWzkx1X7j18A8s0DEY=)

Les modificateurs ajoutés à un composant `v-model` seront fournis au composant via la prop `modelModifiers`. Dans l'exemple ci-dessous, nous avons créé un composant qui contient une prop `modelModifiers` qui est par défaut un objet vide :

```vue{11}
<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>
```

Notez que la prop `modelModifiers` du composant contient `capitalize` et que sa valeur est `true` - parce qu'elle est définie sur le lien `v-model` `v-model.capitalize="myText"`.

Maintenant que nous avons mis en place notre prop, nous pouvons vérifier les clés de l'objet `modelModifiers` et écrire un gestionnaire pour changer la valeur émise. Dans le code ci-dessous, nous mettrons la chaîne en majuscules chaque fois que l'élément `<input />` déclenchera un événement `input`.

```vue{13-15}
<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>
```

[Essayer en ligne](https://play.vuejs.org/#eNqFks1qg0AQgF9lkIKGpqa9iikNOefUtJfaw6KTZEHdZR1DbPDdO7saf0qgIq47//PNXL2N1uG5Ri/y4io1UtNrUspCK0Owa7aK/0osCQ5GFeCHq4nMuvlJCZCUeHEOGR5EnRNcrTS92VURXGex2qXVZ4JEsOhsAQxSbcrbDaBo9nihCHyXAaC1B3/4jVdDoXwhLHQuCPkGsD/JCmSpa4JUaEkilz9YAZ7RNHSS5REaVQPXgCay9vG0rPNToTLMw9FznXhdHYkHK04Qr4Zs3tL7g2JG8B4QbZS2LLqGXK5PkdcYwTsZrs1R6RU7lcmDRDPaM7AuWARMbf0KwbVdTNk4dyyk5f3l15r5YjRm8b+dQYF0UtkY1jo4fYDDLAByZBxWCmvAkIQ5IvdoBTcLeYCAiVbhvNwJvEk4GIK5M0xPwmwoeF6EpD60RrMVFXJXj72+ymWKwUvfXt+gfVzGB1tzcKfDZec+o/LfxsTdtlCj7bSpm3Xk4tjpD8FZ+uZMWTowu7MW7S+CWR77)

### Modificateurs pour `v-model` avec arguments {#modifiers-for-v-model-with-arguments}

Pour les liens `v-model` avec à la fois un argument et un modificateur, le nom de la prop générée sera `arg + "Modifiers"`. Par exemple :

```vue-html
<MyComponent v-model:title.capitalize="myText">
```

Les déclarations correspondantes doivent être :

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

Voici un autre exemple d'utilisation de modificateurs avec plusieurs `v-model` ayant des arguments différents :

```vue-html
<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>
```

```vue{5,6,10,11}
<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{15,16}
<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>
```

---

---
url: /guide/extras/web-components.md
---
# Vue et les Web Components {#vue-and-web-components}

Les [Web Components](https://developer.mozilla.org/fr/docs/Web/Web_Components) est un terme générique pour l'ensemble des API web natives qui permettent aux développeurs de créer des éléments personnalisés réutilisables.

Nous considérons que Vue et les Web Components sont avant tout des technologies complémentaires. Vue offre un excellent support pour la consommation et la création d'éléments personnalisés. Que vous intégriez des éléments personnalisés dans une application Vue existante ou que vous utilisiez Vue pour créer et distribuer des éléments personnalisés, vous êtes au bon endroit.

## Utiliser des éléments personnalisés dans Vue {#using-custom-elements-in-vue}

Vue [obtient un score parfait de 100 % dans les tests Custom Elements Everywhere](https://custom-elements-everywhere.com/libraries/vue/results/results.html). L'utilisation d'éléments personnalisés dans une application Vue fonctionne en grande partie de la même manière que l'utilisation d'éléments HTML natifs, avec quelques éléments à garder à l'esprit :

### Ignorer la résolution des composants {#skipping-component-resolution}

Par défaut, Vue tentera de résoudre une balise HTML non native en tant que composant Vue enregistré avant de revenir à son rendu en tant qu'élément personnalisé. Cela entraînera l'émission par Vue d'un avertissement "Échec de la résolution du composant" pendant le développement. Pour faire savoir à Vue que certains éléments doivent être traités comme des éléments personnalisés et ignorer la résolution des composants, nous pouvons spécifier l'[`option compilerOptions.isCustomElement`](/api/application#app-config-compileroptions).

Si vous utilisez Vue avec une configuration de build, l'option doit être transmise via les configurations de build car il s'agit d'une option de compilation.

#### Exemple de configuration dans le navigateur {#example-in-browser-config}

```js
// Ne fonctionne que si vous utilisez la compilation dans le navigateur.
// Si vous utilisez des outils de build, consultez les exemples de configuration ci-dessous.
app.config.compilerOptions.isCustomElement = (tag) => tag.includes('-')
```

#### Exemple pour une config Vite {#example-vite-config}

```js [vite.config.js]
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // traiter toutes les balises avec un tiret comme des éléments personnalisés
          isCustomElement: (tag) => tag.includes('-')
        }
      }
    })
  ]
}
```

#### Exemple avec une config Vue CLI {#example-vue-cli-config}

```js [vue.config.js]
module.exports = {
  chainWebpack: (config) => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap((options) => ({
        ...options,
        compilerOptions: {
          // traiter toute balise commençant par ion- comme un élément personnalisé
          isCustomElement: (tag) => tag.startsWith('ion-')
        }
      }))
  }
}
```

### Passer des propriétés DOM {#passing-dom-properties}

Bien que que les attributs DOM ne peuvent être que des chaînes de caractères, nous devons transmettre des données complexes à des éléments personnalisés en tant que propriétés DOM. Lors de la définition de props sur un élément personnalisé, Vue 3 vérifie automatiquement la présence de la propriété DOM à l'aide de l'opérateur "in" et préfère définir la valeur en tant que propriété DOM si la clé est présente. Cela signifie que, dans la plupart des cas, vous n'aurez pas besoin d'y penser si l'élément personnalisé suit les [bonnes pratiques recommandées](https://web.dev/custom-elements-best-practices/).

Cependant, il peut y avoir de rares cas où les données doivent être transmises en tant que propriété DOM, mais l'élément personnalisé ne définit / ne reflète pas correctement la propriété (provoquant l'échec de la vérification `in`). Dans ce cas, vous pouvez forcer la définition d'une liaison `v-bind` en tant que propriété DOM à l'aide du modificateur `.prop` :

```vue-html
<my-element :user.prop="{ name: 'jack' }"></my-element>

<!-- raccourci équivalent -->
<my-element .user="{ name: 'jack' }"></my-element>
```

## Créer des éléments personnalisés avec Vue {#building-custom-elements-with-vue}

Le principal avantage des éléments personnalisés est qu'ils peuvent être utilisés avec n'importe quel framework, ou même sans framework. Cela les rend parfaits pour distribuer des composants là où le consommateur final n'utilise peut-être pas la même stack frontend, ou lorsque vous souhaitez isoler l'application finale des détails d'implémentation des composants qu'elle utilise.

### defineCustomElement {#definecustomelement}

Vue prend en charge la création d'éléments personnalisés en utilisant exactement les mêmes API de composants Vue via la méthode [`defineCustomElement`](/api/general#definecustomelement). La méthode accepte le même argument que [`defineComponent`](/api/general#definecomponent), mais renvoie à la place un constructeur d'élément personnalisé qui étend `HTMLElement` :

```vue-html
<my-vue-element></my-vue-element>
```

```js
import { defineCustomElement } from 'vue'

const MyVueElement = defineCustomElement({
  // options normales de composant Vue ici
  props: {},
  emits: {},
  template: `...`,

  // defineCustomElement uniquement : CSS à injecter dans le shadowRoot
  styles: [`/* css littéraux */`]
})

// Enregistre l'élément personnalisé.
// Après l'enregistrement, toutes les balises `<my-vue-element>`
// sur la page seront mises à jour.
customElements.define('my-vue-element', MyVueElement)

// Vous pouvez également instancier programmatiquement l'élément :
// (ne peut être fait qu'après l'enregistrement)
document.body.appendChild(
  new MyVueElement({
    // props initiales (facultatif)
  })
)
```

#### Cycle de vie {#lifecycle}

* Un élément personnalisé Vue montera une instance de composant Vue interne à l'intérieur du shadowRoot lorsque la fonction [`connectedCallback`](https://developer.mozilla.org/fr/docs/Web/Web_Components/Using_custom_elements#utilisation_des_rappels_de_cycle_de_vie) de l'élément est appelée pour la première fois.

* Lorsque la fonction `disconnectedCallback` de l'élément est invoquée, Vue vérifiera si l'élément est détaché du document après un tic de micro-tâche.

  * Si l'élément est toujours dans le document, c'est un déplacement et l'instance du composant sera conservée ;

  * Si l'élément est détaché du document, il s'agit d'une suppression et l'instance du composant sera démontée.

#### Props {#props}

* Toutes les props déclarées à l'aide de l'option `props` seront définies sur l'élément personnalisé en tant que propriétés. Vue gérera automatiquement la réflexion entre les attributs / propriétés le cas échéant.

  * Les attributs sont toujours reflétés dans les propriétés correspondantes.

  * Les propriétés avec des valeurs primitives (`string`, `boolean` ou `number`) sont reflétées en tant qu'attributs.

* Vue convertit également automatiquement les props déclarées avec les types `Boolean` ou `Number` dans le type souhaité lorsqu'elles sont définies en tant qu'attributs (qui sont toujours des chaînes de caractères). Par exemple, étant donné la déclaration de props suivante :

  ```js
  props: {
    selected: Boolean,
    index: Number
  }
  ```

  Et l'utilisation de l'élément personnalisé :

  ```vue-html
  <my-element selected index="1"></my-element>
  ```

  Dans le composant, `selected` sera converti en `true` (booléen) et `index` sera converti en `1` (nombre).

#### Événements {#events}

Les événements émis via `this.$emit` ou la configuration `emit` sont distribués en tant que [CustomEvents](https://developer.mozilla.org/fr/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) natifs sur l'élément personnalisé. Des arguments d'événement supplémentaires (données) seront exposés sous forme de tableau sur l'objet CustomEvent en tant que propriété `detail`.

#### Slots {#slots}

À l'intérieur du composant, les slots peuvent être rendus en utilisant l'élément `<slot/>` comme d'habitude. Cependant, lors de la consommation de l'élément résultant, il n'accepte que la [syntaxe native des slots](https://developer.mozilla.org/fr/docs/Web/Web_Components/Using_templates_and_slots) :

* Les [scoped slots](/guide/components/slots#scoped-slots) ne sont pas supportés.

* Lorsque vous passez des slots nommés, utilisez l'attribut `slot` au lieu de la directive `v-slot` :

  ```vue-html
  <my-element>
    <div slot="named">hello</div>
  </my-element>
  ```

#### Provide / Inject {#provide-inject}

L'[API Provide /Inject](/guide/components/provide-inject#provide-inject) et son [équivalent pour la Composition API](/api/composition-api-dependency-injection#provide) fonctionnent également entre les éléments personnalisés définis par Vue. Cependant, notez que cela fonctionne **uniquement entre les éléments personnalisés**. C'est-à-dire qu'un élément personnalisé défini par Vue ne pourra pas injecter les propriétés fournies par un composant Vue non personnalisé.

#### Configuration au niveau de l'application  {#app-level-config}

Vous pouvez configurer l'instance d'application d'un élément personnalisé Vue en utilisant l'option `configureApp` :

```js
defineCustomElement(MyComponent, {
  configureApp(app) {
    app.config.errorHandler = (err) => {
      /* ... */
    }
  }
})
```

### SFC comme élément personnalisé {#sfc-as-custom-element}

`defineCustomElement` fonctionne également avec les composants monofichiers (SFC). Cependant, avec la configuration des outils par défaut, le `<style>` à l'intérieur des SFC sera toujours extrait et fusionné dans un seul fichier CSS lors du build en production. Lors de l'utilisation d'un SFC comme élément personnalisé, il est souvent préférable d'injecter les balises `<style>` dans le shadowRoot de l'élément personnalisé.

Les outils SFC officiels prennent en charge l'importation de SFC en "mode élément personnalisé" (nécessite `@vitejs/plugin-vue@^1.4.0` ou `vue-loader@^16.5.0`). Un SFC chargé en mode élément personnalisé place ses balises `<style>` comme des chaînes de caractères de CSS litérales et les expose sous l'option `styles` du composant. Ceci sera récupéré par `defineCustomElement` et injecté dans le shadowRoot de l'élément lors de son instanciation.

Pour activer ce mode, terminez simplement le nom de votre fichier de composant par `.ce.vue` :

```js
import { defineCustomElement } from 'vue'
import Example from './Example.ce.vue'

console.log(Example.styles) // ["/* css litéral */"]

// convertion en constructeur d'élément personnalisé
const ExampleElement = defineCustomElement(Example)

// enregistrement
customElements.define('my-example', ExampleElement)
```

Si vous souhaitez personnaliser les fichiers à importer en mode élément personnalisé (par exemple, traiter *tous* les SFC comme des éléments personnalisés), vous pouvez passer l'option `customElement` aux plugins de build respectifs :

* [@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#using-vue-sfcs-as-custom-elements)
* [vue-loader](https://github.com/vuejs/vue-loader/tree/next#v16-only-options)

### Conseils pour une bibliothèque d'éléments personnalisés Vue {#tips-for-a-vue-custom-elements-library}

Lors de la création d'éléments personnalisés avec Vue, les éléments s'appuieront sur l'environnement d'exécution de Vue. Il y a un coût de taille de base d'environ 16 Ko en fonction du nombre de fonctionnalités utilisées. Cela signifie qu'il n'est pas idéal d'utiliser Vue si vous expédiez un seul élément personnalisé - vous pouvez utiliser du JavaScript pur, [petite-vue](https://github.com/vuejs/petite-vue) ou des frameworks qui se spécialisent dans leur petite taille d'exécution. Cependant, la taille de base est plus que rentable si vous expédiez une collection d'éléments personnalisés avec une logique complexe, car Vue permettra à chaque composant d'être créé avec beaucoup moins de code. Plus vous expédiez d'éléments ensemble, meilleur est le compromis.

Si les éléments personnalisés seront utilisés dans une application qui utilise également Vue, vous pouvez choisir d'externaliser Vue à partir du bundle construit afin que les éléments utilisent la même copie de Vue à partir de l'application hôte.

Il est recommandé d'exporter les constructeurs d'éléments individuels pour donner à vos utilisateurs la possibilité de les importer à la demande et de les enregistrer avec les noms de balises souhaités. Vous pouvez également exporter une fonction pratique pour enregistrer automatiquement tous les éléments. Voici un exemple de point d'entrée d'une bibliothèque d'éléments personnalisés Vue :

```js [elements.js]

import { defineCustomElement } from 'vue'
import Foo from './MyFoo.ce.vue'
import Bar from './MyBar.ce.vue'

const MyFoo = defineCustomElement(Foo)
const MyBar = defineCustomElement(Bar)

// exporte des éléments individuellement
export { MyFoo, MyBar }

export function register() {
  customElements.define('my-foo', MyFoo)
  customElements.define('my-bar', MyBar)
}
```

On peut utiliser les éléments d'un fichier Vue :

```vue
<script setup>
import { register } from 'path/to/elements.js'
register()
</script>

<template>
  <my-foo ...>
    <my-bar ...></my-bar>
  </my-foo>
</template>
```

Ou dans tout autre framework, par exemple avec JSX, et avec des noms personnalisés :

```jsx
import { MyFoo, MyBar } from 'path/to/elements.js'

customElements.define('some-foo', MyFoo)
customElements.define('some-bar', MyBar)

export function MyComponent() {
  return <>
    <some-foo ... >
      <some-bar ... ></some-bar>
    </some-foo>
  </>
}
```

### Composants personnalisés basé sur Vue, et TypeScript {#web-components-and-typescript}

Lorsque vous écrivez des templates Vue SFC, vous pouvez vouloir [vérifier le type](/guide/scaling-up/tooling.html#typescript) de vos composants Vue, y compris ceux qui sont définis en tant qu'éléments personnalisés.

Les éléments personnalisés sont enregistrés globalement dans les navigateurs à l'aide de leurs API intégrées et, par défaut, ils n'ont pas d'inférence de type lorsqu'ils sont utilisés dans les templates Vue. Pour fournir un support de type aux composants Vue enregistrés en tant qu'éléments personnalisés, nous pouvons enregistrer des typages de composants globaux en augmentant l'interface [`GlobalComponents` interface](https://github.com/vuejs/language-tools/wiki/Global-Component-Types) pour la vérification de type dans les templates Vue (les utilisateurs de JSX peuvent augmenter le type [JSX.IntrinsicElements](https://www.typescriptlang.org/docs/handbook/jsx.html#intrinsic-elements) à la place, ce qui n'est pas montré ici).

Voici comment définir le type d'un élément personnalisé réalisé avec Vue :

```typescript
import { defineCustomElement } from 'vue'

// Importez le composant Vue.
import SomeComponent from './src/components/SomeComponent.ce.vue'

// Transformer le composant Vue en une classe d'éléments personnalisés
export const SomeElement = defineCustomElement(SomeComponent)

// N'oubliez pas d'enregistrer la classe de l'élément auprès du navigateur
customElements.define('some-element', SomeElement)

// Ajouter le nouveau type d'élément au type GlobalComponents de Vue
declare module 'vue' {
  interface GlobalComponents {
    // Veillez à indiquer ici le type de composant Vue
    // (SomeComponent, *et non* SomeElement).
    // Les éléments personnalisés requièrent un trait d'union dans leur nom,
    // utilisez donc le nom de l'élément avec trait d'union comme ici.
    'some-element': typeof SomeComponent
  }
}
```

## Composants personnalisés sans Vue, et TypeScript {#non-vue-web-components-and-typescript}

Voici la méthode recommandée pour activer la vérification de type dans les templates SFC des éléments personnalisés qui ne sont pas construits avec Vue.

:::tip Note
Cette approche est une façon possible de procéder, mais elle peut varier en fonction du
framework utilisé pour créer les éléments personnalisés.
:::

Supposons que nous ayons un élément personnalisé avec des propriétés JS et des événements définis, et qu'il soit livré dans une bibliothèque appelée `some-lib` :

```ts [some-lib/src/SomeElement.ts]

// Définir une classe avec des propriétés JS typées
export class SomeElement extends HTMLElement {
  foo: number = 123
  bar: string = 'blah'

  lorem: boolean = false

  // Cette méthode ne doit pas être exposée aux types de templates.
  someMethod() {
    /* ... */
  }

  // ... détails de la mise en œuvre omitte ...
  // ... supposons que l'élément envoie des événements nommés "apple-fell" ...
}

customElements.define('some-element', SomeElement)

// Il s'agit d'une liste de propriétés de SomeElement qui seront sélectionnées pour le typage.
// vérification des template de framework (par exemple, les templates Vue SFC). Toutes les autres
// propriétés ne seront pas exposées.
export type SomeElementAttributes = 'foo' | 'bar'

// Définir les types d'événements traités par SomeElement.
export type SomeElementEvents = {
  'apple-fell': AppleFellEvent
}

export class AppleFellEvent extends Event {
  /* ... détails omis ... */
}
```

Les détails de la mise en œuvre ont été omis, mais l'essentiel est que nous disposons de définitions de types pour deux choses : les types de propriétés et les types d'événements.

Créons un assistant de type pour enregistrer facilement des définitions de types d'éléments personnalisés dans Vue :

```ts [some-lib/src/DefineCustomElement.ts]
// Nous pouvons réutiliser ce type d'aide pour chaque élément que nous devons définir.
type DefineCustomElement<
  ElementType extends HTMLElement,
  Events extends EventMap = {},
  SelectedAttributes extends keyof ElementType = keyof ElementType
> = new () => ElementType & {
  // Utilisez $props pour définir les propriétés exposées à la vérification du type de template. Vue
  // lit spécifiquement les définitions d'objets du type `$props`.Notez que nous
  // combine les props de l'élément avec les props HTML globaux et les props spéciaux de Vue.

  /** @deprecated N'utilisez pas la propriété $props sur un élément personnalisé ref,
   ceci est réservé aux templates de type prop uniquement. */
  $props: HTMLAttributes &
    Partial<Pick<ElementType, SelectedAttributes>> &
    PublicProps

  // Utiliser $emit pour définir spécifiquement les types d'événements. Vue lit spécifiquement même les types d'événements
  // depuis le type `$emit`. Notez que `$emit` attend un format particulier
  // à laquelle nous faisons correspondre `Events`.
  /** @deprecated N'utilisez pas la propriété $emit sur une référence d'élément personnalisé,
   ceci est réservé aux template de type prop uniquement. */
  $emit: VueEmit<Events>
}

type EventMap = {
  [event: string]: Event
}

// Cela permet de faire correspondre un EventMap au format attendu par le type $emit de Vue.
type VueEmit<T extends EventMap> = EmitFn<{
  [K in keyof T]: (event: T[K]) => void
}>
```

:::tip Note
Nous avons marqué `$props` et `$emit` comme dépréciés de sorte que lorsque nous obtenons une `ref` à
un élément personnalisé, nous ne serons pas tentés d'utiliser ces propriétés, car ces
propriétés ne servent qu'à vérifier le type des éléments personnalisés.
Ces propriétés n'existent pas réellement sur les instances d'éléments personnalisés.
:::

En utilisant l'assistant de type, nous pouvons maintenant sélectionner les propriétés JS qui doivent être exposées pour la vérification de type dans les templates Vue :

```ts [some-lib/src/SomeElement.vue.ts]
import {
  SomeElement,
  SomeElementAttributes,
  SomeElementEvents
} from './SomeElement.js'
import type { Component } from 'vue'
import type { DefineCustomElement } from './DefineCustomElement'

// Ajoutez le nouveau type d'élément au type GlobalComponents de Vue.
declare module 'vue' {
  interface GlobalComponents {
    'some-element': DefineCustomElement<
      SomeElement,
      SomeElementAttributes,
      SomeElementEvents
    >
  }
}
```

Supposons que `some-lib` compile ses fichiers source TypeScript dans un dossier `dist/`. Un utilisateur de `some-lib` peut alors importer `SomeElement` et l'utiliser dans un SFC Vue comme suit :

```vue [SomeElementImpl.vue]
<script setup lang="ts">
// Cette opération permet de créer et d'enregistrer l'élément dans le navigateur.
import 'some-lib/dist/SomeElement.js'

// Un utilisateur qui utilise TypeScript et Vue doit importer en plus le fichier
// Définition de type spécifique à Vue (les utilisateurs d'autres frameworks peuvent importer d'autres
// définitions de types spécifiques au framework).
import type {} from 'some-lib/dist/SomeElement.vue.js'

import { useTemplateRef, onMounted } from 'vue'

const el = useTemplateRef('el')

onMounted(() => {
  console.log(
    el.value!.foo,
    el.value!.bar,
    el.value!.lorem,
    el.value!.someMethod()
  )

  // N'utilisez pas ces props, ils sont `undefined`
  // l'IDE les affichera barrés
  el.$props
  el.$emit
})
</script>

<template>
  <!-- Nous pouvons maintenant utiliser l'élément, avec vérification du type : -->
  <some-element
    ref="el"
    :foo="456"
    :blah="'hello'"
    @apple-fell="
      (event) => {
        // Le type de `event` est ici déduit comme étant `AppleFellEvent`
      }
    "
  ></some-element>
</template>
```

Si un élément n'a pas de définition de type, les types de propriétés et d'événements peuvent être définis de manière plus manuelle :

```vue [SomeElementImpl.vue]
<script setup lang="ts">
// Supposons que `some-lib` soit du JS simple sans définition de type, et TypeScript
// ne peut pas déduire les types :
import { SomeElement } from 'some-lib'

// Nous utiliserons le même type d'aide que précédemment.
import { DefineCustomElement } from './DefineCustomElement'

type SomeElementProps = { foo?: number; bar?: string }
type SomeElementEvents = { 'apple-fell': AppleFellEvent }
interface AppleFellEvent extends Event {
  /* ... */
}

// Ajouter le nouveau type d'élément au type GlobalComponents de Vue.
declare module 'vue' {
  interface GlobalComponents {
    'some-element': DefineCustomElement<
      SomeElementProps,
      SomeElementEvents
    >
  }
}

// ... comme précédemment, utiliser une référence à l'élément ...
</script>

<template>
  <!-- ... comme précédemment, utiliser l'élément dans le template ... -->
</template>
```

Les auteurs d'éléments personnalisés ne doivent pas exporter automatiquement les définitions de types d'éléments personnalisés spécifiques au framework à partir de leurs bibliothèques, par exemple ils ne doivent pas les exporter à partir d'un fichier `index.ts` qui exporte également le reste de la bibliothèque, sinon les utilisateurs auront des erreurs inattendues d'augmentation de module. Les utilisateurs doivent importer le fichier de définition de type spécifique au framework dont ils ont besoin.

## Web Components vs. les composants Vue {#web-components-vs-vue-components}

Certains développeurs pensent que les modèles de composants propriétaires du framework doivent être évités et que l'utilisation exclusive d'éléments personnalisés rend une application "à l'épreuve du temps". Ici, nous allons essayer d'expliquer pourquoi nous pensons qu'il s'agit d'une approche trop simpliste du problème.

Il existe en effet un certain niveau de chevauchement de fonctionnalités entre les éléments personnalisés et les composants Vue : ils nous permettent tous deux de définir des composants réutilisables avec transmission de données, émission d'événements et gestion du cycle de vie. Cependant, les API des Web Components sont de niveau relativement bas et rudimentaires. Pour créer une application réelle, nous avons besoin de quelques fonctionnalités supplémentaires que la plate-forme ne couvre pas :

* Un système de template déclaratif et efficace ;

* Un système de gestion d'état réactif qui facilite l'extraction et la réutilisation de la logique entre composants ;

* Un moyen performant de rendre les composants sur le serveur et de les hydrater sur le client (SSR), ce qui est important pour le référencement et [les métriques Web Vitals telles que LCP](https://web.dev/vitals/). Les éléments personnalisés natifs SSR impliquent généralement de simuler le DOM dans Node.js, puis de sérialiser le DOM muté, tandis que Vue SSR se compile en concaténation de chaînes autant que nécessaire, ce qui est beaucoup plus efficace.

Le modèle de composants de Vue est conçu avec ces besoins à l'esprit en tant que système cohérent.

Avec une équipe d'ingénieurs compétente, vous pourriez probablement créer l'équivalent au-dessus des éléments personnalisés natifs - mais cela signifie également que vous assumez le fardeau de la maintenance à long terme d'un framework interne, tout en perdant les avantages écosystémiques et communautaires d'un framework mature comme Vue.

Il existe également des frameworks construits à l'aide d'éléments personnalisés comme base de leur modèle de composants, mais ils doivent tous inévitablement introduire leurs solutions propriétaires aux problèmes répertoriés ci-dessus. L'utilisation de ces frameworks implique d'accepter leurs décisions techniques sur la façon de résoudre ces problèmes - ce qui, malgré ce qui peut être annoncé, ne vous isole pas automatiquement des futures évolutions potentielles.

Il existe également des domaines dans lesquels nous trouvons que les éléments personnalisés sont limités :

* L'évaluation en avance des slots entrave la composition des composants. Les [scoped slots](/guide/components/slots#scoped-slots) de Vue sont un mécanisme puissant pour la composition de composants, qui ne peut pas être prise en charge par des éléments personnalisés en raison de la déclaration en avance des slots natifs. Les slots en avance signifient également que le composant récepteur ne peut pas contrôler quand ou s'il faut rendre un élément du contenu du slot.

* Aujourd’hui, distribuer des éléments personnalisés avec du CSS à portée limitée étendus au shadow DOM nécessite l'intégration du CSS dans JavaScript afin qu'ils puissent être injectés dans les shadowRoot lors de l'exécution. Ils entraînent également des styles dupliqués dans le balisage des scénarios SSR. Il y a des [fonctionnalités de la plate-forme](https://github.com/whatwg/html/pull/4898/) en cours d'élaboration dans ce domaine - mais pour l'instant, elles ne sont pas encore universellement prises en charge, et il existe encore des performances de production / préoccupations SSR à traiter. En attendant, les SFC Vue fournissent des [mécanismes de limitation de la portée du CSS](/api/sfc-css-features) qui prennent en charge l'extraction des styles dans des fichiers CSS simples.

Vue restera toujours à jour avec les dernières normes de la plate-forme Web, et nous nous ferons un plaisir de tirer parti de tout ce que la plate-forme fournit si cela facilite notre travail. Cependant, notre objectif est de fournir des solutions qui fonctionnent bien et qui fonctionnent aujourd’hui. Cela signifie que nous devons intégrer de nouvelles fonctionnalités de plate-forme avec un état d'esprit critique - et cela implique de combler les lacunes là où les normes sont insuffisantes aussi longtemps que ce sera nécessaire.