Conventions

Ceci est le guide des conventions officielles pour du code spécifique à Vue. Si vous utilisez Vue dans vos projets, c’est la référence pour éviter les erreurs, les discussions futiles ou les mauvais usages de code. Nous ne pensons cependant pas qu’un guide de conventions soit pertinent pour toutes les équipes ou tous les projets, aussi nous encourageons les écarts pourvu qu’ils soient éclairés et basés sur vos expériences passées, les technologies que vous côtoyez ainsi que vos valeurs personnelles.

Nous allons en grande partie éviter les conventions à propos du JavaScript ou du HTML en eux-mêmes. Nous ne nous soucions pas de votre utilisation des points-virgules ou de la place de la virgule en début de ligne. Nous ne nous soucierons pas non plus de savoir si votre HTML utilise des apostrophes ou des guillemets pour les valeurs des attributs. Quelques exceptions seront faites cependant, quand nous trouvons qu’une utilisation de code spécifique est utile dans le contexte de Vue.

Bientôt, nous fournirons des astuces pour la mise en application. Même si certains points sont une simple question de discipline, nous essayerons de vous montrer comment utiliser ESLint et d’autres processus automatisés pour mettre simplement en place ces conventions.

Nous avons donc divisé les règles en quatre catégories :

Catégories de règle

Priorité A : essentiel

Ces règles aident à éviter les erreurs, donc apprenez-les et respectez-les à tout prix. Des exceptions peuvent exister, mais elles devraient être rares et seulement faites par ceux qui ont une connaissance experte à la fois de JavaScript et de Vue.

Priorité B : fortement recommandé

Ces règles ont été établies pour améliorer la lisibilité et / ou l’expérience des développeurs dans la majorité des projets. Votre code fonctionnera toujours si vous ne les suivez pas, mais ces écarts doivent être rares et justifiés.

Priorité C : recommandé

Là où de multiples et équivalentes options existent, un choix arbitraire a été fait pour assurer la consistance. Dans ces règles, nous décrivons chaque option acceptable et suggérons un choix par défaut. Cela signifie que vous pouvez faire des choix différents sur votre propre base de code, aussi longtemps que vous êtes cohérent et avez de bonnes raisons. Mais gardez toujours les bonnes raisons à l’esprit ! En vous alignant sur les standards de la communauté vous :

1. pourrez améliorer votre cerveau à analyser plus facilement la plupart des codes communautaires rencontrés,
2. serez capable de copier et coller la plupart des exemples de code sans modifications,
3. trouverez de nouvelles recrues déjà habituées à votre style de codage préféré, au moins en ce qui concerne Vue.

Priorité D : faire attention

Certaines fonctionnalités de Vue existent pour régler des cas exceptionnels ou rendre la migration d’une vieille version de code plus simple. Mais utiliser avec excès, elles rendront votre code difficile à maintenir et même deviendront une source de bogues. Ces règles mettent en lumière des fonctionnalités potentiellement risquées, décrivant quand et pourquoi elles doivent être évitées.

Règles de priorité A : essentiel (prévenir les erreurs)

Nom de composant à mots multiples ^essentiel

Les noms de composant devraient toujours être des mots multiples, à l’exception du composant racine App et des composants préconçus fournis par Vue comme <transition> ou <component>.

Ceci afin de prévenir les conflits avec des éléments HTML futurs ou existant car toutes les balises HTML n’ont qu’un seul mot.

Vue.component('todo', {
  // ...
})

export default {
  name: 'Todo',
  // ...
}

Vue.component('todo-item', {
  // ...
})

export default {
  name: 'TodoItem',
  // ...
}

Données du composant ^essentiel

La propriété data doit être une fonction.

Quand vous utilisez la propriété data dans un composant (par ex. partout sauf sur new Vue), la valeur doit être une fonction qui retourne un objet.

data: {
  listTitle: '',
  todos: []
}

data: function () {
  return {
    listTitle: '',
    todos: []
  }
}

Vue.component('some-comp', {
  data: {
    foo: 'bar'
  }
})

export default {
  data: {
    foo: 'bar'
  }
}

Vue.component('some-comp', {
  data: function () {
    return {
      foo: 'bar'
    }
  }
})

// Dans un fichier `.vue`
export default {
  data () {
    return {
      foo: 'bar'
    }
  }
}

// Par contre l'utilisation directe d'un objet est possible dans
// l'instance racine de Vue, car il n'y a qu'une
// instance racine qui existe
new Vue({
  data: {
    foo: 'bar'
  }
})

Définitions de prop ^essentiel

Les définitions de prop devraient être aussi détaillées que possible.

Dans du code acté, les définitions de prop devraient être toujours aussi détaillées que possible, en spécifiant au moins le(s) type(s).

// Ceci est uniquement bon pour le prototypage
props: ['status']

props: {
  status: String
}

// Même mieux !
props: {
  status: {
    type: String,
    required: true,
    validator: function (value) {
      return [
        'syncing',
        'synced',
        'version-conflict',
        'error'
      ].indexOf(value) !== -1
    }
  }
}

Des clés pour v-for ^essentiel

Toujours utiliser key avec v-for.

key avec v-for est toujours requis sur les composants afin de maintenir l’état des composants internes aligné aux sous-arbres. Même pour les éléments, c’est une bonne pratique pour garder un comportement prédictible pour de la stabilité d’objet dans les animations.

data: function () {
  return {
    todos: [
      {
        id: 1,
        text: 'Apprendre à utiliser `v-for`'
      },
      {
        id: 2,
        text: 'Apprendre à utiliser `key`'
      }
    ]
  }
}

<ul>
  <li v-for="todo in todos">
    {{ todo.text }}
  </li>
</ul>

<ul>
  <li
    v-for="todo in todos"
    :key="todo.id"
  >
    {{ todo.text }}
  </li>
</ul>

Éviter v-if avec v-for ^essentiel

N’utilisez jamais v-if sur le même élément que v-for.

Il y a deux utilisations courantes qui seraient tentantes :

• Pour filtrer des éléments dans une liste (par ex. 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 ex. activeUsers).

• Pour ne pas faire le rendu d’une liste si elle ne doit pas être affichée (par ex. v-for="user in users" v-if="shouldShowUsers"). Dans ce cas, déplacez v-if dans un élément englobant (par ex. ul ou ol).

<ul>
  <li
    v-for="user in users"
    v-if="user.isActive"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

this.users.map(function (user) {
  if (user.isActive) {
    return user.name
  }
})

computed: {
  activeUsers: function () {
    return this.users.filter(function (user) {
      return user.isActive
    })
  }
}

<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

<ul>
  <li
    v-for="user in users"
    v-if="shouldShowUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

<ul v-if="shouldShowUsers">
  <li
    v-for="user in users"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

<ul>
  <li
    v-for="user in users"
    v-if="user.isActive"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

<ul>
  <li
    v-for="user in users"
    v-if="shouldShowUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

<ul v-if="shouldShowUsers">
  <li
    v-for="user in users"
    :key="user.id"
  >
    {{ user.name }}
  </li>
</ul>

Style des composants à portée limitée ^essentiel

Pour les applications, le style du niveau App au sommet et des composants de mises en page doivent être globaux, mais tous les autres styles des composants devraient être avec une portée limitée au composant.

Ceci n’est pertinent que pour les composants monofichiers. Cela _ne_ nécessite pas l’ajout de l’attribut scoped. La portée limitée peut être faite avec les modules CSS, une stratégie basée sur les classes comme BEM ou d’autres bibliothèques / conventions du même genre.

Les composants de bibliothèques, cependant, devraient utiliser une stratégie basée sur les classes plutôt que d’utiliser l’attribut scoped.

Cela permet de surcharger les styles internes facilement, avec des noms de classes lisibles par les humains avec un niveau de spécificité peu élevé qui entre en conflit vraiment très rarement.

<template>
  <button class="btn btn-close">X</button>
</template>

<style>
.btn-close {
  background-color: red;
}
</style>

<template>
  <button class="button button-close">X</button>
</template>

<!-- Utilisez l'attribut `scoped` -->
<style scoped>
.button {
  border: none;
  border-radius: 2px;
}

.button-close {
  background-color: red;
}
</style>

<template>
  <button :class="[$style.button, $style.buttonClose]">X</button>
</template>

<!-- Utilisez les modules CSS -->
<style module>
.button {
  border: none;
  border-radius: 2px;
}

.buttonClose {
  background-color: red;
}
</style>

<template>
  <button class="c-Button c-Button--close">X</button>
</template>

<!-- Utilisez des conventions BEM -->
<style>
.c-Button {
  border: none;
  border-radius: 2px;
}

.c-Button--close {
  background-color: red;
}
</style>

Noms de propriété privé ^essentiel

Utilisez la portée des modules pour garder les fonctions inaccessibles de l’extérieur. Si cela n’est pas possible, utilisez le préfixe $_ pour les propriétés privées personnalisées dans un plugin, mixin, etc car elles ne doivent pas être considérées comme des APIs publiques. Cela permet d’éviter les conflits avec le code d’autres développeurs. Il est également possible d’inclure un nom de portée (par ex. $_yourPluginName_).

var myGreatMixin = {
  // ...
  methods: {
    update: function () {
      // ...
    }
  }
}

var myGreatMixin = {
  // ...
  methods: {
    _update: function () {
      // ...
    }
  }
}

var myGreatMixin = {
  // ...
  methods: {
    $update: function () {
      // ...
    }
  }
}

var myGreatMixin = {
  // ...
  methods: {
    $_update: function () {
      // ...
    }
  }
}

var myGreatMixin = {
  // ...
  methods: {
    $_myGreatMixin_update: function () {
      // ...
    }
  }
}

// Encore mieux !
var myGreatMixin = {
  // ...
  methods: {
    publicMethod() {
      // ...
      myPrivateFunction()
    }
  }
}

function myPrivateFunction() {
  // ...
}

export default myGreatMixin

Règles de priorité B : fortement recommandé (améliorer la lisibilité)

Fichier composants ^{fortement recommandé}

Chaque fois qu’un système de build est disponible pour concaténer les fichiers, chaque composant devrait être dans son propre fichier.

Ceci aide à trouver plus rapidement un composant quand vous avez besoin de l’éditer ou de vérifier comment il fonctionne.

Vue.component('TodoList', {
  // ...
})

Vue.component('TodoItem', {
  // ...
})

components/
|- TodoList.js
|- TodoItem.js

components/
|- TodoList.vue
|- TodoItem.vue

Casse des noms de fichier des composants monofichiers ^{fortement recommandé}

Les noms de fichier des composants monofichiers devraient toujours être écrits en PascalCase ou en kebab-case.

La PascalCase fonctionne mieux avec l’autocomplétion dans des éditeurs de code. Comme ils sont consistants avec la manière dont nous référençons les composants avec du JS(X) et des templates, utilisez-la si possible. Cependant, les casses de noms mixtes (majuscules et minuscules) peuvent parfois créer des problèmes sur des systèmes de fichier non sensibles à la casse. C’est pourquoi la kebab-case est aussi parfaitement acceptable.

components/
|- mycomponent.vue

components/
|- myComponent.vue

components/
|- MyComponent.vue

components/
|- my-component.vue

Base de nom de composant ^{fortement recommandé}

Les composants de base (c.-à-d. les composants de présentation, de support ou purement fonctionnels) qui appliquent un style et des conventions spécifiques à l’application devraient tous commencer avec un même préfixe, comme par exemple Base, App, ou V.

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

Nom des composants à une seule instance ^{fortement recommandé}

Les composants qui devraient uniquement avoir une seule instance active devraient commencer par le préfixe The pour indiquer qu’il ne peut y en avoir qu’un.

Cela ne signifie pas que le composant doit être utilisé uniquement sur une seule page, mais qu’il ne peut y en avoir qu’un par page. Ces composants n’acceptent jamais de props car ils sont spécifiques à votre application et n’ont pas leur propre contexte dans l’application. Si vous ressentez le besoin d’ajouter des props c’est une bonne indication que c’est en fait un composant réutilisable qui n’est utilisé qu’une fois par page pour le moment.

components/
|- Heading.vue
|- MySidebar.vue

components/
|- TheHeading.vue
|- TheSidebar.vue

Noms de composants fortement couplés ^{fortement recommandé}

Les composants qui sont fortement liés à leur parent devraient inclure le nom du parent en tant que préfixe.

Si un composant n’a de sens que dans le contexte d’un composant parent, cette relation devrait être évidente dans son nom. Puisque les éditeurs organisent les fichiers par ordre alphabétique, cela permet de garder ses fichiers proches les uns des autres.

components/
|- TodoList/
   |- Item/
      |- index.vue
      |- Button.vue
   |- index.vue

components/
|- TodoList/
   |- Item/
      |- Button.vue
   |- Item.vue
|- TodoList.vue

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 un nom de composant ^{fortement recommandé}

Les noms de composant devraient commencer avec le mot le plus important en premier et se décliner avec des mots descriptifs.

components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputExcludeGlob.vue
|- SearchInputQuery.vue
|- SettingsCheckboxLaunchOnStartup.vue
|- SettingsCheckboxTerms.vue

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

Les composants autofermants ^{fortement recommandé}

Les composants sans contenu devraient être autofermants dans les composants monofichiers, les templates de chaine de caractères, et le JSX : mais jamais dans les templates du DOM.

Les composants qui sont autofermants n’indiquent pas seulement qu’ils n’ont pas de contenu, mais qu’ils sont faits pour ne pas en avoir. C’est la différence entre une page blanche dans un livre et une qui indiquerait « Cette page est intentionnellement vide ». Votre code est aussi plus clair sans balises fermantes inutiles.

Malheureusement, le HTML ne permet pas aux éléments personnalisés d’être autofermant. Seuls les éléments vides officiels peuvent l’être. C’est pourquoi il est possible d’utiliser cette stratégie seulement quand les templates Vue sont compilés avant qu’ils soient injectés dans le DOM. Ensuite du code HTML valide aux spécifications est fourni au DOM.

<!-- Dans les composants monofichiers, les templates avec chaine de caractères et en JSX -->
<MyComponent></MyComponent>

<!-- Dans les templates du DOM -->
<my-component/>

<!-- Dans les composants monofichiers, les templates avec chaine de caractères et en JSX -->
<MyComponent/>

<!-- Dans les templates du DOM -->
<my-component></my-component>

Casse des noms de composant dans les templates ^{fortement recommandé}

Dans la plupart des projets, les noms de composant devraient toujours être écrits en PascalCase dans les composants monofichiers mais en kebab-case pour les templates dans le DOM.

La PascalCase a plusieurs avantages comparés à la kebab-case :

• Les éditeurs peuvent autocompléter un nom de composant dans les templates car la PascalCase est également utilisée en JavaScript.
• <MyComponent> est visuellement plus distinct qu’un élément HTML d’un seul mot comme <my-component> car il y a deux caractères de différenciation (les deux capitales) plutôt que juste un (le trait d’union).
• Si vous utilisez des composants personnalisés qui ne sont pas des éléments Vue dans vos templates, comme les Web Composants, la PascalCase vous assure que les composants Vue restent bien différentiables.

Malheureusement, du fait de l’insensibilité à la casse du HTML, les templates du DOM doivent rester en kebab-case.

Notez également que si vous avez déjà largement utilisé la kebab-case de manière consistante avec vos conventions HTML à travers tous vos projets, cela peut être plus important que les avantages listés plus haut. Dans de tels cas, utiliser la kebab-case partout est également acceptable.

<!-- Dans les composants monofichiers, les templates avec chaine de caractères -->
<mycomponent/>

<!-- Dans les composants monofichiers, les templates avec chaine de caractères -->
<myComponent/>

<!-- Dans les templates du DOM -->
<MyComponent></MyComponent>

<!-- Dans les composants monofichiers, les templates avec chaine de caractères -->
<MyComponent/>

<!-- Dans les templates du DOM -->
<my-component></my-component>

<!-- Partout -->
<my-component></my-component>

Casse des noms de composant en JS / JSX ^{fortement recommandé}

Les noms de composant en JS / JSX devraient toujours être en PascalCase, cependant ils peuvent être en kebab-case à l’intérieur des chaines de caractères pour de simples applications qui utilisent seulement des composants globaux avec Vue.component.

Vue.component('myComponent', {
  // ...
})

import myComponent from './MyComponent.vue'

export default {
  name: 'myComponent',
  // ...
}

export default {
  name: 'my-component',
  // ...
}

Vue.component('MyComponent', {
  // ...
})

Vue.component('my-component', {
  // ...
})

import MyComponent from './MyComponent.vue'

export default {
  name: 'MyComponent',
  // ...
}

Nom de composant avec mot complet ^{fortement recommandé}

Les noms de composant devraient préférer des mots complets à des abréviations.

L’autocomplétion dans les éditeurs rend le cout d’un long nom de composant insignifiant alors que la clarté qu’il amène est sans valeur. Les abréviations non communes, en particulier, sont à éviter.

components/
|- SdSettings.vue
|- UProfOpts.vue

components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue

Casse des noms de prop ^{fortement recommandé}

Les noms de prop devraient toujours utiliser la camelCase lors de leur déclaration, mais la kebab-case dans les templates et les JSX.

Nous suivons simplement les conventions de chaque langage. Dans le JavaScript, la camelCase est plus naturelle. Dans le HTML, c’est la kebab-case.

props: {
  'greeting-text': String
}

<WelcomeMessage greetingText="hi"/>

props: {
  greetingText: String
}

<WelcomeMessage greeting-text="hi"/>

Éléments avec attributs multiples ^{fortement recommandé}

Des éléments avec de multiples attributs devraient occuper plusieurs lignes, avec un attribut par ligne.

En JavaScript, scinder les objets avec de multiples propriétés sur plusieurs lignes est largement considéré comme une bonne convention, car cela rend le code plus facile à lire. Nos templates et JSX suivent les mêmes règles.

<img src="https://vuejs.org/images/logo.png" alt="Vue Logo">

<MyComponent foo="a" bar="b" baz="c"/>

<img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo"
>

<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>

Expressions simples dans les templates ^{fortement recommandé}

Les templates de composant devraient seulement inclure de simples expressions, avec les expressions les plus complexes refactorisées dans des propriétés calculées ou des méthodes.

Les expressions complexes dans vos templates les rendent moins déclaratifs. Nous devrions voir ce qui devrait apparaitre, et non comment cette valeur est calculée. Les propriétés calculées et les méthodes permettent également de rendre le code réutilisable.

{{
  fullName.split(' ').map(function (word) {
    return word[0].toUpperCase() + word.slice(1)
  }).join(' ')
}}

<!-- In a template -->
{{ normalizedFullName }}

// L'expression complexe a été bougée dans une propriété calculée
computed: {
  normalizedFullName: function () {
    return this.fullName.split(' ').map(function (word) {
      return word[0].toUpperCase() + word.slice(1)
    }).join(' ')
  }
}

Propriétés calculées simples ^{fortement recommandé}

Les propriétés calculées complexes devraient être scindées en plusieurs propriétés plus simples autant que possible.

computed: {
  price: function () {
    var basePrice = this.manufactureCost / (1 - this.profitMargin)
    return (
      basePrice -
      basePrice * (this.discountPercent || 0)
    )
  }
}

computed: {
  basePrice: function () {
    return this.manufactureCost / (1 - this.profitMargin)
  },
  discount: function () {
    return this.basePrice * (this.discountPercent || 0)
  },
  finalPrice: function () {
    return this.basePrice - this.discount
  }
}

Valeur d’attribut entre guillemets ^{fortement recommandé}

Les attributs HTML non vides devraient toujours être entre guillemets (ou apostrophe, celui qui n’est pas utilisé dans le JS).

Alors que les valeurs d’attributs sans espaces ne sont pas requises en HTML, cela les mène à ne jamais mettre d’espace, laissant place à des valeurs moins lisibles.

<input type=text>

<AppSidebar :style={width:sidebarWidth+'px'}>

<input type="text">

<AppSidebar :style="{ width: sidebarWidth + 'px' }">

Abréviations de directive ^{fortement recommandé}

Les abréviations de directive (: pour v-bind:, @ pour v-on: et # pour v-slot) devraient toujours être utilisées ou jamais.

<input
  v-bind:value="newTodoText"
  :placeholder="newTodoInstructions"
>

<input
  v-on:input="onInput"
  @focus="onFocus"
>

<template v-slot:header>
  <h1>Ici on place le titre de page</h1> 
</template>

<template #footer>
  <p>Ici les informations de contact</p>
</template>

<input
  :value="newTodoText"
  :placeholder="newTodoInstructions"
>

<input
  v-bind:value="newTodoText"
  v-bind:placeholder="newTodoInstructions"
>

<input
  @input="onInput"
  @focus="onFocus"
>

<input
  v-on:input="onInput"
  v-on:focus="onFocus"
>

<template v-slot:header>
  <h1>Ici on place le titre de page</h1> 
</template>

<template v-slot:footer>
  <pIci les informations de contact</p>
</template>

<template #header>
  <h1>Ici on place le titre de page</h1> 
</template>

<template #footer>
  <p>Ici les informations de contact</p>
</template>

Règles de priorité C : recommandé (minimiser les choix arbitraires et la surcharge cognitive)

Ordre des options de composants / instances ^recommandé

Les options des instances / composants devraient être ordonnées avec consistance.

Voici l’ordre par défaut que nous recommandons pour les options de composant. Elles sont séparées en catégories ainsi vous saurez où ajouter vos nouvelles propriétés pour vos plugins.

1. Effets de bord (créer des effets en dehors du composant)

   • el

2. Informations globales (nécessite des connaissances au-delà du composant)

   • name
   • parent

3. Type de composant (change le type du composant)

   • functional

4. Modificateurs de template (change la manière dont les templates sont compilés)

   • delimiters
   • comments

5. Dépendances des templates (les ressources utilisées dans le template)

   • components
   • directives
   • filters

6. Composition (fusionner des propriétés dans les options)

   • extends
   • mixins

7. Interface (interface du composant)

   • inheritAttrs
   • model
   • props / propsData

8. État local (propriétés réactives locales)

   • data
   • computed

9. Évènements (fonctions de rappel déclenchées par des évènements réactifs)

   • watch
   • Évènements du cycle de vie (dans leur ordre d’appel)
     • beforeCreate
     • created
     • beforeMount
     • mounted
     • beforeUpdate
     • updated
     • activated
     • deactivated
     • beforeDestroy
     • destroyed

10. Propriétés non réactives (propriétés d’instance indépendantes du système de réactivité)

    • methods

11. Rendu (description déclarative de la sortie du composant)

    • template / render
    • renderError

Ordre des attributs des éléments ^recommandé

Les attributs d’éléments (incluant les composants) devraient être ordonnés avec consistance.

Voici l’ordre par défaut que nous recommandons pour les attributs d’éléments. Ils sont séparés en catégories, ainsi vous saurez où ajouter vos attributs et directives personnalisées.

1. Définition (fournit les options du composant)

   • is

2. Rendu de liste (crée des variations multiples du même élément)

   • v-for

3. Conditions (comment l’élément est rendu / affiché)

   • v-if
   • v-else-if
   • v-else
   • v-show
   • v-cloak

4. Modificateurs de rendu (change la manière de faire le rendu de l’élément)

   • v-pre
   • v-once

5. Attention globale (nécessite des connaissances au-delà du composant)

   • id

6. Attributs uniques (attributs nécessitant une valeur unique)

   • ref
   • key

7. Liaison bidirectionnelle (combiner les liaisons descendantes et les évènements montants)

   • v-model

8. Autres attributs (tous les attributs qui sont liés ou non liés)

9. Évènements (gestionnaire d’évènement de composant)

   • v-on

10. Contenu (écrase le contenu d’un élément)

    • v-html
    • v-text

Ligne vide dans les options d’instance / de composant ^recommandé

Vous pourriez ajouter une ligne vide entre de multiples propriétés, en particulier si la longueur de votre option dépasse la taille de l’écran.

Quand les composants commencent à devenir difficile à lire, ajouter des espaces entre des propriétés sur plusieurs lignes peut les rendre de nouveau simple à lire. Dans divers éditeurs, comme Vim, formater les options ainsi peut rendre la navigation plus simple avec le clavier.

props: {
  value: {
    type: String,
    required: true
  },

  focused: {
    type: Boolean,
    default: false
  },

  label: String,
  icon: String
},

computed: {
  formattedValue: function () {
    // ...
  },

  inputClasses: function () {
    // ...
  }
}

// Sans espaces, c'est bien aussi, du moment que le composant
// reste simple à lire et à parcourir.
props: {
  value: {
    type: String,
    required: true
  },
  focused: {
    type: Boolean,
    default: false
  },
  label: String,
  icon: String
},
computed: {
  formattedValue: function () {
    // ...
  },
  inputClasses: function () {
    // ...
  }
}

Ordre des balises principales des composants monofichiers ^recommandé

Les composants monofichiers devraient toujours ordonner de manière consistante les balises <script>, <template>, et <style>, avec <style> en dernier, car au moins l’un des deux autres est toujours nécessaire.

<style>/* ... */</style>
<script>/* ... */</script>
<template>...</template>

<!-- ComponentA.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

<!-- ComponentA.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<script>/* ... */</script>
<template>...</template>
<style>/* ... */</style>

<!-- ComponentA.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

<!-- ComponentB.vue -->
<template>...</template>
<script>/* ... */</script>
<style>/* ... */</style>

Règles de priorité D : faire attention (potentiellement dangereux)

v-if / v-else-if/ v-else sans key ^{faire attention}

Il est généralement préférable d’utiliser key avec v-if + v-else, si les éléments sont de même type (c.-à-d. avec deux éléments <div> par ex.).

Par défaut, Vue met à jour le DOM aussi efficacement que possible. Cela signifie que quand il commute entre deux éléments de même type, il va simplement modifier l’élément existant, plutôt que de l’enlever et d’en ajouter un nouveau à la place. Cela peut avoir des effets non souhaités si ces éléments ne doivent pas être considérés comme les mêmes.

<div v-if="error">
  Error: {{ error }}
</div>
<div v-else>
  {{ results }}
</div>

<div
  v-if="error"
  key="search-status"
>
  Error: {{ error }}
</div>
<div
  v-else
  key="search-results"
>
  {{ results }}
</div>

Sélecteurs par nom de balise avec scoped ^{faire attention}

Les sélecteurs par nom de balise devraient être évités avec scoped.

Préférez les sélecteurs de classes plutôt que les sélecteurs de nom dans des styles scoped car utiliser un nombre important de sélecteurs par nom de balise est lent.

<template>
  <button>X</button>
</template>

<style scoped>
button {
  background-color: red;
}
</style>

<template>
  <button class="btn btn-close">X</button>
</template>

<style scoped>
.btn-close {
  background-color: red;
}
</style>

Communication parent-enfant implicite ^{faire attention}

Les évènements et props devraient être préférés pour la communication entre composants parent-enfant, au lieu de l’utilisation de this.$parent ou la mutation des props.

Une application Vue idéale est une application où les props descendent et où les évènements remontent. Rester dans cette convention rend vos composants plus simples à comprendre. Cependant, il y a quelques cas où la mutation des props ou this.$parent peut simplifier l’utilisation de deux composants qui sont fortement couplés.

Le problème est qu’il y a beaucoup de cas simples où leur utilisation offre de la facilité. Attention : ne vous laissez pas séduire par une apparente simplicité (être capable de comprendre le flux de votre état) pour une vision court-termiste (écrire moins de code).

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  template: '<input v-model="todo.text">'
})

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  methods: {
    removeTodo () {
      var vm = this
      vm.$parent.todos = vm.$parent.todos.filter(function (todo) {
        return todo.id !== vm.todo.id
      })
    }
  },
  template: `
    <span>
      {{ todo.text }}
      <button @click="removeTodo">
        X
      </button>
    </span>
  `
})

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  template: `
    <input
      :value="todo.text"
      @input="$emit('input', $event.target.value)"
    >
  `
})

Vue.component('TodoItem', {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  template: `
    <span>
      {{ todo.text }}
      <button @click="$emit('delete')">
        X
      </button>
    </span>
  `
})

Non-gestion de l’état par flux ^{faire attention}

Vuex devrait être préféré pour une gestion globale d’état à la place de this.$root ou d’un canal global d’évènement.

Gérer l’état avec this.$root et/ou utiliser un canal d’évènement global peut faciliter la tâche dans des cas vraiment simples. Cependant cela n’est pas approprié pour la plupart des applications.

Vuex est l’implémentation flux officielle pour Vue. Elle n’offre pas seulement une place centrale pour gérer l’état mais également des outils pour organiser, tracer et déboguer les changements d’états. Il s’intègre bien dans l’écosystème de Vue (incluant un support complet par Vue DevTools également).

// main.js
new Vue({
  data: {
    todos: []
  },
  created: function () {
    this.$on('remove-todo', this.removeTodo)
  },
  methods: {
    removeTodo: function (todo) {
      var todoIdToRemove = todo.id
      this.todos = this.todos.filter(function (todo) {
        return todo.id !== todoIdToRemove
      })
    }
  }
})

// store/modules/todos.js
export default {
  state: {
    list: []
  },
  mutations: {
    REMOVE_TODO (state, todoId) {
      state.list = state.list.filter(todo => todo.id !== todoId)
    }
  },
  actions: {
    removeTodo ({ commit, state }, todo) {
      commit('REMOVE_TODO', todo.id)
    }
  }
}

<!-- TodoItem.vue -->
<template>
  <span>
    {{ todo.text }}
    <button @click="removeTodo(todo)">
      X
    </button>
  </span>
</template>

<script>
import { mapActions } from 'vuex'

export default {
  props: {
    todo: {
      type: Object,
      required: true
    }
  },
  methods: mapActions(['removeTodo'])
}
</script>