Provide / Inject #

Cette page suppose que vous avez déjà lu les principes fondamentaux des composants. Lisez-les d'abord si vous débutez avec les composants.

Passage de props en profondeur (Prop Drilling) #

Habituellement, lorsque nous devons transmettre des données du parent à un composant enfant, nous utilisons des props. Cependant, imaginez le cas où nous avons un arbre de composants important, et qu'un composant profondément imbriqué aurait besoin d'accéder à des informations d'un de ses composants parents. Avec seulement des props, nous devrions passer la même prop sur toute la chaîne composants parents :

Notez que bien que le composant <Footer> n'utilise pas du tout ces props, il doit malgré tout les déclarer et les transmettre uniquement afin que <DeepChild> puisse y accéder. S'il y a une chaîne de composants parents plus longue, encore plus de composants seront affectés par le problème. C'est ce qu'on appelle le "props drilling" et ce n'est certainement pas amusant à gérer.

Nous pouvons résoudre le "props drilling" avec provide and inject. Un composant parent peut servir de fournisseur de dépendances pour tous ses descendants. Tout composant enfant de l'arborescence, quelle que soit sa profondeur, peut injecter des dépendances fournies par des composants présent dans sa chaîne de composants parents.

Provide #

<script setup>
import { provide } from 'vue'

provide(/* clé */ 'message', /* valeur */ 'hello!')
</script>

import { provide } from 'vue'

export default {
  setup() {
    provide(/* clé */ 'message', /* valeur */ 'hello!')
  }
}

import { ref, provide } from 'vue'

const count = ref(0)
provide('key', count)

export default {
  provide: {
    message: 'hello!'
  }
}

export default {
  data() {
    return {
      message: 'hello!'
    }
  },
  provide() {
    // utiliser la syntaxe avec une fonction afin de pouvoir accéder à `this`
    return {
      message: this.message
    }
  }
}

Provide au niveau de l'application #

En plus de fournir des données dans un composant, nous pouvons également fournir des données au niveau de l'application :

import { createApp } from 'vue'

const app = createApp({})

app.provide(/* clé */ 'message', /* valeur */ 'hello!')

Les données fournies au niveau de l'application sont disponibles pour tous les composants rendus dans l'application. Ceci est particulièrement utile lors de l'écriture de plugins, car les plugins ne seraient généralement pas en mesure de fournir des valeurs à l'aide de composants.

Inject #

<script setup>
import { inject } from 'vue'

const message = inject('message')
</script>

import { inject } from 'vue'

export default {
  setup() {
    const message = inject('message')
    return { message }
  }
}

export default {
  inject: ['message'],
  created() {
    console.log(this.message) // valeur injectée
  }
}

export default {
  inject: ['message'],
  data() {
    return {
      // données initiales basées sur la valeur injectée
      fullMessage: this.message
    }
  }
}

export default {
  inject: {
    /* clé locale */ localMessage: {
      from: /* clé d'injection */ 'message'
    }
  }
}

Valeurs par défaut lors de l'injection #

Par défaut, inject suppose que la clé injectée est fournie quelque part dans la chaîne de composants parents. Dans le cas où la clé n'est pas fournie, il y aura un message d'avertissement lors de l'exécution.

Si nous voulons faire fonctionner une propriété injectée avec des fournisseurs facultatifs, nous devons déclarer une valeur par défaut, de la même manière qu'avec les props :

// `value` sera "default value"
// si aucune donnée correspondant à la clé "message" n'a été fournie
const value = inject('message', 'default value')

const value = inject('key', () => new ExpensiveClass())

export default {
  // la syntaxe utilisant un objet est requise
  // lors de la déclaration des valeurs par défaut pour les injections
  inject: {
    message: {
      from: 'message', // ceci est facultatif si vous utilisez la même clé pour l'injection
      default: 'default value'
    },
    user: {
      // utiliser une fonction factory pour les valeurs non primitives coûteuse
      // à créer, ou celles qui doivent être uniques par instance de composant.
      default: () => ({ name: 'John' })
    }
  }
}

Injections réactives #

<!-- à l'intérieur du composant fournisseur -->
<script setup>
import { provide, ref } from 'vue'

const location = ref('North Pole')

function updateLocation() {
  location.value = 'South Pole'
}

provide('location', {
  location,
  updateLocation
})
</script>

<!-- dans le composant injecteur -->
<script setup>
import { inject } from 'vue'

const { location, updateLocation } = inject('location')
</script>

<template>
  <button @click="updateLocation">{{ location }}</button>
</template>

<script setup>
import { ref, provide, readonly } from 'vue'

const count = ref(0)
provide('read-only-count', readonly(count))
</script>

import { computed } from 'vue'

export default {
  data() {
    return {
      message: 'hello!'
    }
  },
  provide() {
    return {
      // fournir explicitement une propriété calculée
      message: computed(() => this.message)
    }
  }
}

Injection avec des Symbols en tant que clés #

Jusqu'à présent, nous avons utilisé dans les exemples des clés d'injection qui étaient des chaînes de caractères. Si vous travaillez dans une application de taille importante avec de nombreux fournisseurs de dépendances, ou si vous créez des composants qui seront utilisés par d'autres développeurs, il est préférable d'utiliser des clés d'injection utilisant des Symbols pour éviter les collisions potentielles.

Il est recommandé d'exporter les Symbols dans un fichier dédié :

// keys.js
export const myInjectionKey = Symbol()

// dans le composant fournisseur
import { provide } from 'vue'
import { myInjectionKey } from './keys.js'

provide(myInjectionKey, {
  /* données à fournir */
})

// dans le composant injecteur
import { inject } from 'vue'
import { myInjectionKey } from './keys.js'

const injected = inject(myInjectionKey)

// dans le composant fournisseur
import { myInjectionKey } from './keys.js'

export default {
  provide() {
    return {
      [myInjectionKey]: {
        /* données à fournir */
      }
    }
  }
}

// dans le composant injecteur
import { myInjectionKey } from './keys.js'

export default {
  inject: {
    injected: { from: myInjectionKey }
  }
}