Comprendre l’API Composition introduite dans Vue.JS 3

Tout d’abord, sachez que rien ne vous oblige à utiliser l’API Composition avec Vue 3. Vous pouvez très bien :

• n’utiliser que l’API Option : attention toutefois aux éléments dépréciés par Vue 3 !;
• n’utiliser que l’API Composition ;
• ou bien même mixer les deux : déclarer certains de vos composants avec l’API Option et d’autres avec l’API Composition.

Vous l’aurez peut-être remarqué dans l’introduction, mais avec l’API Composition on n’utilise plus le mot-clé this. Et pour cause : il n’est plus possible de l’utiliser.

Et pour chaque cas où l’on disposait du mot-clé this dans l’écriture API Option, il existe une solution de remplacement. Y compris pour les fonctions introduites par Vuex (la bibliothèque de gestion de valeurs globales pour Vue) et Vue-Router (la bibliothèque de gestion des pages de votre site Vue JS).

Nous les passerons en revue au fur et à mesure de notre progression dans ce tutoriel.

Dans l’exemple d’introduction, nous avons remplacé la section data par plusieurs constantes. Mais si l’on devait se limiter aux constantes dans la Composition API, on perdrait à coup sûr en flexibilité au sein de notre application. Heureusement, il est possible de définir et d’exporter des propriétés réactives pour le template.

II-C-1. Propriété ref (référence)▲

<template>
  <div id="app">
    <button @click="handleDown">-</button>
    {{ counter }}
    <button @click="handleUp">+</button>
  </div>
</template>

<script>
import {ref} from 'vue';

export default {
  name: 'App',
  setup() {
    const counter = ref(0);

    function handleUp() {
      counter.value++;
    }

    function handleDown() {
      if (counter.value > 0) counter.value--;
    }

    return {
      counter, handleUp, handleDown,
    };
  },
};
</script>

<style>
</style>

II-C-2. Propriété réactive (reactive)▲

Admettons que l’on souhaite adapter l’écriture API Option suivante :

Section data avec une propriété complexe.

Sélectionnez

data() {
   return {
      john : {
         firstName : "John",
         lastName : "Doe",
          age : 32,
      }
   } ;
}

Si l’on devait adapter la propriété john dans l’API Composition avec des ref, on serait obligé de scinder cette propriété en trois références distinctes. Fort heureusement, pour ceux qui souhaitent éviter cela, il existe une autre solution : les propriétés réactives.

Voici un exemple d’utilisation :

Section data avec une propriété complexe : reactive.

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.

<template>
  <div id="app">
    <input type="text" v-model="john.firstName" />
    <input type="text" v-model="john.lastName" />
    <input type="number" v-model="john.age" />

    <button @click="reset">Reset</button>

  <p>
    {{ john.firstName }} {{ john.lastName }}
  </p>
  <p>
    {{ john.age }}
  </p>
  </div>
</template>

<script>
import {reactive} from 'vue';

export default {
  name: 'App',
  setup() {
    let john = reactive({
      firstName: "John",
      lastName: "Doe",
      age: 32
    });

    function reset() {
      /* Ne fonctionne pas
      john = {
        firstName: "John",
        lastName: "Doe",
        age: 32
      };
      */
     john.firstName = "John";
     john.lastName = "Doe";
     john.age = 32;
    }

    return {john, reset};
  },
};
</script>

<style>
#app {
  display: flex;
  flex-direction: column;
}
</style>

Ainsi :

• j’importe la fonction reactive (ligne 19) et je déclare une propriété john comme étant réactive (ligne 24-28). Attention ! Une référence de type reactive est certes encapsulée derrière un proxy, mais on ne peut pas la réaffecter dans sa globalité. C’est-à-dire que l’on pourra modifier/ajouter des propriétés, mais pas la valeur complète. Donc mieux vaut déclarer ce genre de variables comme étant muable ! (Avec le mot-clé let). Et bien-sûr, je n’oublie pas d’exporter la référence john pour le template (ligne 43) ;
• pour modifier la valeur de la référence réactive dans la fonction setup, il faut obligatoirement modifier les propriétés une à la fois (si toutefois l’on souhaite réellement en modifier plusieurs, voire toutes). Mais en tout cas, inutile d’essayer de modifier les différentes valeurs en attribuant un nouvel objet à la variable, sinon, il n’y aura pas de nouveau rendu du composant déclenché. (lignes 30-41) ;
• enfin, on accède simplement aux valeurs dans le template . (lignes 3-5, 10, 13).

Veuillez également noter, qu’avec une variable de type reactive, si sa valeur au moment de l’exportation dans le bloc return est de type objet ({}), tenter par la suite de la réaffecter dans une valeur primitive (par exemple 2) n’aura pas d’effet : la variable réactive conservera sa précédente valeur. En revanche, rien ne nous interdit de le faire dans la fonction setup, avant l’exportation : mais dans ce cas précis, la variable étant devenue en quelque sorte une valeur primitive, là aussi, tenter de modifier sa valeur par la suite (par un évènement par exemple ou un appel à setTimeoutau sein de la fonction setup), n’aura aucun effet.

Les variables de type reactive semblent donc présenter davantage de subtilités que les variables de type ref.

La fonction setup peut accepter aucun, un ou bien deux arguments, en fonction de nos besoins. Ces arguments existent notamment parce que dans la fonction setup, l’utilisation du mot-clé this a forcément disparu (Attention, il s’agit de $this avec Vue JS 2, et this avec Vue JS 3).

II-D-1. Argument props▲

<template>
  <div class="myBoxRoot">
    <div class="myBoxLayer1"></div>
    <div class="myBoxLayer2" :style="{backgroundColor: bg}">
      <button @click="alertColor">Alert my color</button>
    </div>
  </div>
</template>

<script>
export default {
  props: {
    bg: {
      type: String,
      default: 'white',
    },
  },
  methods: {
    alertColor() {
      alert(this.bg);
    }
  }
}
</script>

<style>
.myBoxRoot {
  width: 200px;
  height: 200px;
  position: relative;
  background-color: blue;
}

.myBoxLayer1 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: yellow;
}

.myBoxLayer2 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: green;
}
</style>

<template>
  <div class="myBoxRoot">
    <div class="myBoxLayer1"></div>
    <div class="myBoxLayer2" :style="{backgroundColor: bg}">
      <button @click="alertColor">Alert my color</button>
    </div>
  </div>
</template>

<script>
export default {
  props: {
    bg: {
      type: String,
      default: 'white',
    },
  },
  setup(props) {
    function alertColor() {
      alert(props.bg);
    }

    return {alertColor};
  }
}
</script>

<style>
.myBoxRoot {
  width: 200px;
  height: 200px;
  position: relative;
  background-color: blue;
}

.myBoxLayer1 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: yellow;
}

.myBoxLayer2 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: green;
}
</style>

II-D-2. Argument context▲

<template>
  <div class="myBoxRoot">
    <div class="myBoxLayer1"></div>
    <div class="myBoxLayer2" :style="{backgroundColor: bg}">
      <button @click="informMyColor">Alert my color</button>
    </div>
  </div>
</template>

<script>
export default {
  props: {
    bg: {
      type: String,
      default: 'white',
    },
  },
  methods: {
    informMyColor() {
      this.$emit('colorInfo', `My color is ${this.bg}`);
    }
  }
}
</script>

<style>
.myBoxRoot {
  width: 200px;
  height: 200px;
  position: relative;
  background-color: blue;
}

.myBoxLayer1 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: yellow;
}

.myBoxLayer2 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: green;
}
</style>

<template>
  <div id="app">
    <MyBox bg="red" @colorInfo="handleColorInfo" />
  </div>
</template>

<script>
import MyBox from './components/MyBox';
export default {
  name: 'App',
  components: {
    MyBox,
  },
  setup() {
    function handleColorInfo(msg) {
      alert(msg);
    }

    return {handleColorInfo};
  }
};
</script>

<style>
#app {
  display: flex;
  flex-direction: column;
}
</style>

<template>
  <div class="myBoxRoot">
    <div class="myBoxLayer1"></div>
    <div class="myBoxLayer2" :style="{backgroundColor: bg}">
      <button @click="informMyColor">Alert my color</button>
    </div>
  </div>
</template>

<script>
export default {
  props: {
    bg: {
      type: String,
      default: 'white',
    },
  },
  setup(props, context) {
    function informMyColor() {
      context.emit('colorInfo', `My color is ${props.bg}`);
    }

    return {informMyColor};
  }
}
</script>

<style>
.myBoxRoot {
  width: 200px;
  height: 200px;
  position: relative;
  background-color: blue;
}

.myBoxLayer1 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: yellow;
}

.myBoxLayer2 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: green;
}
</style>

Il est également possible de définir des propriétés calculées (computed) avec l’API Composition.

À titre d’exemple, reprenons l’exemple précédent, en l’enrichissant un tout petit peu.

<template>
  <div class="myBoxRoot">
    <div class="myBoxLayer1"></div>
    <div class="myBoxLayer2" :style="{backgroundColor: bg}">
      <button @click="informMyColor">Alert my color</button>
    </div>
  </div>
</template>

<script>
import {computed} from 'vue';
export default {
  props: {
    bg: {
      type: String,
      default: 'white',
    },
  },
  setup(props, context) {

    const bangBackground = computed(() => `!!!${props.bg}!!!`);

    function informMyColor() {
      context.emit('colorInfo', `My color is ${bangBackground.value}`);
    }

    return {informMyColor};
  }
}
</script>

<style>
.myBoxRoot {
  width: 200px;
  height: 200px;
  position: relative;
  background-color: blue;
}

.myBoxLayer1 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: yellow;
}

.myBoxLayer2 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: green;
}
</style>

Et le composant application App :

<template>
  <div id="app">
    <MyBox :bg="background" @colorInfo="handleColorInfo" />
    <button @click="changeColor">Change my color</button>
  </div>
</template>

<script>
import MyBox from './components/MyBox';
import {ref} from 'vue';

export default {
  name: 'App',
  components: {
    MyBox,
  },
  setup() {
    function handleColorInfo(msg) {
      alert(msg);
    }

    const background = ref('yellow');

    function changeColor() {
      background.value = 'green';
    }

    return {background, handleColorInfo, changeColor};
  }
};
</script>

<style>
#app {
  display: flex;
  flex-direction: column;
}
</style>

Dans cette application, en appuyant sur le bouton Alert my color, l’information est mise à jour en fonction de la couleur du composant (que l’on peut changer avec le deuxième bouton).

En ligne 11 du fichier composant, nous importons la fonction computed, et ensuite nous l’utilisons afin de définir une nouvelle propriété bangBackground (ligne 21) à l’aide de cette fonction.

Ainsi cette propriété bangBackground est une référence de type proxy, et nous devons donc accéder à sa valeur par l’intermédiaire de sa propriété value (ligne 24). Cette propriété fonctionne comme les propriétés calculées de l’API Option, se mettant automatiquement à jour avec la valeur de la propriété de base.

Il est même possible de créer une propriété calculée à partir de propriété référence/réactive, voire de mélanger props/refs/reactives dans une même propriété calculée.

Comme dans cette version du composant :

<template>
  <div class="myBoxRoot">
    <div class="myBoxLayer1"></div>
    <div class="myBoxLayer2" :style="{backgroundColor: bg}">
      <button @click="informMyColor">Alert my color</button>
    </div>
  </div>
</template>

<script>
import {computed, ref, reactive} from 'vue';
export default {
  props: {
    bg: {
      type: String,
      default: 'white',
    },
  },
  setup(props, context) {

    const decorator = ref('!!!');
    let number = reactive({number: 1});
    const bangBackground = computed(() => `${decorator.value}${props.bg}${decorator.value}-${number.number}`);

    function informMyColor() {
      context.emit('colorInfo', `My color is ${bangBackground.value}`);
    }

    setTimeout(() => {
      decorator.value = '@@@';
    }, 2000);

    setInterval(() => {
      number.number++;
    }, 1000);

    return {informMyColor};
  }
}
</script>

<style>
.myBoxRoot {
  width: 200px;
  height: 200px;
  position: relative;
  background-color: blue;
}

.myBoxLayer1 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: yellow;
}

.myBoxLayer2 {
  width: 200px;
  height: 200px;
  position: absolute;
  background-color: green;
}
</style>

Il est aussi possible de mettre en place des observateurs (watchers) avec l’API Composition. Il existe plusieurs manières d’utiliser la fonction watch, ici je ne m’attarderai que sur deux cas précis :

1. L’observation d’une propriété référence ;
2. L’observation d’une valeur unique d’une propriété réactive.

II-F-1. Observation d’une propriété référence▲

<script>
import {ref, watch} from "vue";

export default {
   setup() {
       const myRef = ref&#160;;
       watch(myRef, (newValue, oldValue) => {
           console.log(newValue)&#160;;
           console.log(oldValue)&#160;;
       })&#160;;
   }
}
</script>

<script>
import {ref, toRefs, watch} from "vue"&#160;;

export default {
   props&#160;: {
      bg&#160;: {
         type&#160;: Number,
         required&#160;: true,
      },
      name&#160;: {
         type&#160;: String,
         default&#160;: "John",
      },
   },
   setup(props) {
       const {bg, name} = toRefs(props)&#160;;
       watch(bg, (newValue, oldValue) => {
           console.log("new bg: "+newValue)&#160;;
           console.log("old bg": +oldValue)&#160;;
       })&#160;;
       watch(name, (newValue, oldValue) => {
           console.log("new name&#160;:"+newValue)&#160;;
           console.log("old name&#160;:"+oldValue)&#160;;
       })&#160;;

       return {}&#160;;
   }
}
</script>

II-F-2. Observation d’une valeur d’une propriété réactive▲

<script>
import {reactive, watch} from 'vue'&#160;;

export default {
   setup() {
       const john = reactive({
         name: 'john',
         age: 32,
       })&#160;;
       watch(() => john.age, (newValue) => { 
         console.log('John is', newValue, 'years old');
       })&#160;;

       setInterval(() => john.age++, 1000);

       return {}&#160;;
   }
}
</script>

Pour gérer un cycle de vie à l’intérieur de la fonction setup, rien de plus simple : il suffit d’utiliser la fonction onXXX équivalente. Veuillez noter qu’il n’y a pas d’équivalent pour les cycles de vie beforeCreate et created : c’est déjà le rôle de la fonction setup.

<script>
import {onBeforeUnmount, onUpdated} from "vue"&#160;;

export default {
   setup() {
      onUpdated(() => console.log("Updated my component")&#160;;
      onBeforeUnmount(() => console.log("About to unmount my component")&#160;;
      return {}&#160;;
   }
}
</script>

Pour ceux d’entre vous qui utilisent Vuex, le framework de gestion d’état global pour Vue, vous vous êtes sûrement demandé ce qu’il advient de son utilisation avec l’API Composition.

La réponse est simple, dans la dernière version, installable avec npm install vuex@next (évidemment vous pouvez aussi utiliser yarn au lieu de npm), les développeurs ont prévu des fonctions équivalentes afin de pouvoir utiliser Vuex avec l’API Composition. (Notez bien que la version next, correspondait à la version 4.0.2 lors de la rédaction du tutoriel.)

Sans vouloir être exhaustif encore une fois, la documentation officiellela documentation officielle Vuex API Composition est disponible pour cela et sera plus à même de vous présenter des informations mises à jour, dans cette section je vais essayer de répondre à cette problématique.

Tout d’abord, admettons que nous définissons un simple store pour notre application fictive VueJS. Ce store sera le même dans les versions API Option et API Composition de notre exemple. Il s’agit d’ailleurs de l’exemple de la documentation officielle de Vuex 3.

const store = new Vuex.Store({
  state: {
    count: 0
  },
  mutations: {
    increment (state) {
      state.count++
    }
  }
})

Rien de compliqué : il s’agit d’un compteur disposant d’une méthode mutatrice increment.

Je pars du principe que vous savez déjà comment déclarer votre application VueJS comme dépendante de Vuex et de votre store.

Dans l’API Option, afin d’émettre une mutation de type increment sur notre store, nous pouvons nous y prendre de la manière suivante :

methods: {
  increment() {
    this.$store.commit('increment')
    console.log(this.$store.state.count)
  }
}

Évidemment, pour l’API Composition, le problème réside dans l’utilisation du mot-clé this.

Pour contourner ce problème, il suffit donc d’importer la fonction depuis Vuex (que vous aurez bien sûr pensé à mettre à jour) afin de créer une référence sur notre store et la fonction computed afin de surveiller les modifications du store :

import { computed } from 'vue';
import { useStore } from 'vuex';

export default {
  setup () {
    const store = useStore()
    
    const increment = computed(() => {
        store.commit('increment');
        
        // Evidemment déconseillé
        console.log(store.state.count);
    });
    
    return {
        increment,
    }
  }
}

N’oubliez pas également qu’accéder directement aux états du store est considéré comme une mauvaise pratique.

De la même manière, vous disposez de la fonction store.dispatch afin notamment de faire appel à des mutations asynchrones du store.

Encore une fois, n’hésitez pas à consulter la documentation officielledocumentation officielle de Vuex 4.

Le framework Vue Router, pour gérer la navigation dans les différentes pages de votre site Single Page Application, est également « impacté » par l’utilisation de l’API Composition, mais la transition, à l’instar de l’utilisation de Vuex, n’est pas très complexe.

Pour cela, il faut utiliser une version récente de Vue Router : lors de la rédaction, la version next correspondait à la version 4.0.11 . La documentation officielleLa documentation officielle de Vue Router avec l'API Composition est également là pour vous aider dans votre éventuelle transition.

Là aussi, je pars du principe que vous savez utiliser Vue Router et que vous savez la configurer pour votre application.

Dans l’API Option, vous disposez de deux objets très importants depuis le mot-clé this : this.$route et this.$router.

Dans l’API Composition, il suffit :

1. D’importer les fonctions useRoute et useRouter depuis la librairie vue-router ;
2. De créer une référence à partir de ces fonctions ;
3. D’appeler les fonctions disponibles depuis ces références presque comme l’on ferait depuis l’API Option.

Voici un court script d’exemple dans l’API Composition :

import { useRouter, useRoute } from 'vue-router'

export default {
  setup() {
    const router = useRouter()
    const route = useRoute()

 
    const exampleUseFunction() {
        // ...
        const query = route.query;
        const params = route.params;
        // ...
    }
    
    return {
        exampleUseFunction,
    }
}

De même, il existe des fonctions pour les navigation guards, notamment beforeRouteLeave, beforeRouteUpdate (exemple adapté depuis la documentation officielle):

import { onBeforeRouteLeave } from 'vue-router'
import { ref } from 'vue'

export default {
  setup() {
   // from is from where we try to exit
   // to is the destination page
    onBeforeRouteLeave((to, from) => {
      const answer = window.confirm(
        'Do you really want to leave? you have unsaved changes!'
      )
      // cancels the navigation and stays on the same page
      if (!answer) return false
    })
    
    return {};

  },
}

Sachez qu’il est possible d’utiliser l’API Composition avec la version 2 de Vue JS. Pour cela vous pouvez installer le plugin Vue JS @vue/composition-api, notamment à l’aide de votre gestionnaire de paquets NPMNode JS ou YarnYarn le cas échéant.

Par contre, cela ne va pas sans limitation : vous pouvez les retrouver sur la page NPM du paquetpage NPM du paquet composition-api.

Si vous écrivez des composants définis en uniques fichiers (Single File Component en anglais), vous pouvez en plus utiliser la syntaxe « script setup ».

Il s’agit d’un simplification de l’API Composition dans laquelle notamment

• l’instruction return n’est plus nécessaire ;
• l’ensemble des éléments déclarés est exporté pour la partie template ;
• tout code déclaré dans cette section est exécuté à chaque fois que le composant est créé.

Voici un bref exemple, extrait de la documentation officielle :

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

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

Ainsi la variable msg et la fonction log seront directement disponibles dans la partie template du composant fichier unique.

En revanche, il est fort probable que la plupart des éditeurs en ligne (tels que StackBlitzl'éditeur en ligne StackBlitz) ne reconnaissent pas encore cette syntaxe.