Règles de priorité B : Fortement recommandées #

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 #

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.

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

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

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

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

La casse des noms de composants #

Le nom des composants monofichiers 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 #

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.

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 à instance unique #

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

Cela ne signifie pas que le composant n'est utilisé que dans une seule page, mais il ne sera utilisé qu'une seule fois par page. Ces composants n'acceptent aucun accessoire, car ils sont spécifiques à votre application, pas à leur contexte dans votre application. Si vous trouvez le besoin d'ajouter des accessoires, c'est une bonne indication qu'il s'agit en fait d'un composant réutilisable qui n'est utilisé qu'une fois par page pour l'instant.

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

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

Noms des composants étroitement liés #

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.

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 les noms des composants #

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.

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

Composants auto-fermants #

Les composants sans contenu doivent être auto-fermants dans les composants monofichiers, dans les templates, et dans JSX - 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". 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.

<!-- Dans les composants monofichiers, string templates, et JSX -->
<MyComponent></MyComponent>

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

<!-- Dans les composants monofichiers, string templates, et JSX -->
<MyComponent/>

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

La casse des noms de composants dans les templates #

Dans la plupart des projets, les noms de composants doivent toujours être en PascalCase dans les composants monofichiers 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 composant Web, 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.

<!-- Dans les composants monofichiers, string templates, et JSX -->
<mycomponent/>

<!-- Dans les composants monofichiers, string templates, et JSX -->
<myComponent/>

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

<!-- Dans les composants monofichiers, string templates, et JSX -->
<MyComponent/>

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

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

La casse des noms de composants en JS/JSX #

Les noms de composants en JS/JSX 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.

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

import myComponent from './MyComponent.vue'

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

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

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

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

import MyComponent from './MyComponent.vue'

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

Nom des composants en mot entier #

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 #

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 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.

props: {
  'greeting-text': String
}

const props = defineProps({
  'greeting-text': String
})

// for in-DOM templates
<welcome-message greetingText="hi"></welcome-message>

props: {
  greetingText: String
}

const props = defineProps({
  greetingText: String
})

// 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"/>

// pour les template du DOM
<welcome-message greeting-text="hi"></welcome-message>

Éléments à attributs multiples #

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 méritent la même considération.

<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 #

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.

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

<!-- Dans un template -->
{{ normalizedFullName }}

// 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(' ')
  }
}

// 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 #

Les propriétés calculées complexes doivent être divisées en propriétés plus simples.

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

const price = computed(() => {
  const basePrice = manufactureCost.value / (1 - profitMargin.value)
  return basePrice - basePrice * (discountPercent.value || 0)
})

computed: {
  basePrice() {
    return this.manufactureCost / (1 - this.profitMargin)
  },

  discount() {
    return this.basePrice * (this.discountPercent || 0)
  },

  finalPrice() {
    return this.basePrice - this.discount
  }
}

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 #

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.

<input type=text>

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

<input type="text">

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

Les raccourcis de directives #

Les raccourcis de directives (: pour v-bind:, @ pour v-on: et # pour v-slot) doivent toujours être utilisés ou ne jamais l'être.

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

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

<template v-slot:header>
  <h1>Ceci est le titre de la page</h1>
</template>

<template #footer>
  <p>Ici quelques infos contacts</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>Ceci est le titre de la page</h1>
</template>

<template v-slot:footer>
  <p>Ici quelques infos contacts</p>
</template>

<template #header>
  <h1>Ceci est le titre de la page</h1>
</template>

<template #footer>
  <p>Ici quelques infos contacts</p>
</template>