Formations — 1 037 leçons en français

Accueil › Vue.js › Choisir une bonne clé

Choisir une bonne clé

Listes et rendu conditionneldebutant

Une clé doit être unique entre frères et stable dans le temps. Unique, sinon Vue ne peut pas distinguer deux éléments. Stable, sinon l'identité qu'elle désigne change d'un rendu à l'autre, et toute la réconciliation se trompe.

L'index échoue sur le second point. Il décrit où se trouve un élément, pas qui il est.

<!-- ❌ -->
<li v-for="(tache, i) in taches" :key="i">
  <input v-model="brouillon[i]" />
</li>

<!-- ✅ -->
<li v-for="tache in taches" :key="tache.id">
  <input v-model="tache.titre" />
</li>

Insérez un élément en tête. Avec l'index, la clé 0 désignait la tâche A et désigne maintenant la tâche Z : Vue conclut que l'élément 0 a seulement changé de texte, garde son nœud DOM et son état — la saisie en cours, le focus, la case cochée restent sur la ligne devenue celle de Z.

Avec tache.id, Vue voit une clé inconnue, crée un nœud pour Z, et déplace les nœuds existants avec tout ce qu'ils portent.

La bonne clé est presque toujours l'identifiant qui vient de la base de données. À défaut, une clé composite (`${type}-${code}`) ou un identifiant attribué au moment où l'élément est créé côté client. Jamais Math.random() dans le template : la clé changerait à chaque rendu et tout serait recréé.

Les termes à connaître

Réconciliation

La comparaison que Vue fait entre l'ancien arbre de nœuds virtuels et le nouveau, pour décider ce qu'il déplace, met à jour, crée ou détruit.

Clé stable

Une clé qui désigne toujours la même donnée, rendu après rendu, quelles que soient la position de l'élément et la taille de la liste.

Clé unique

Deux éléments frères ne doivent jamais partager la même clé. En développement, Vue avertit en console quand c'est le cas.

Clé = index

:key="i" associe l'identité à la position. Une insertion en tête décale toutes les identités d'un cran.

État local de ligne

Tout ce qu'une ligne retient sans que la donnée le sache : saisie en cours, focus, panneau déplié, animation. C'est ce que la clé protège.

Clé composite

Une clé construite à partir de plusieurs champs — `${type}-${id}` — quand aucun champ seul n'est unique.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.