Spécifications liées à la syntaxe des composants monofichiers ​

Vue d'ensemble ​

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 :

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

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

• Chaque fichier *.vue peut contenir au maximum un bloc <script> à la fois (sauf <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.

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

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

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>
• vite-plugin-vue-gql: <gql>
• vue-i18n: <i18n>

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 pour plus de détails.

Inférence automatique à parti des noms ​

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 ​

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

<script lang="ts">
  // use TypeScript
</script>

lang peut être appliqué à n'importe quel bloc - par exemple, nous pouvons utiliser <style> avec Sass et <template> avec Pug :

<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
• Vue CLI
• webpack + vue-loader

Imports src ​

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 :

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

<!-- 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 :

<unit-test src="./unit-test.js">
</unit-test>

<img src="~some-npm-package/foo.png">

Commentaires ​

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