تزويد / حقن ​

لقراءة هذه الصفحة يجب عليك أولا الاطلاع على أساسيات المُكونات . ثم العودة إلى هنا.

التمرير العميق للخاصيات ​

عادةً , عندما نحتاج إلي تمرير بيانات من المُكون الأب إلي المُكون الإبن . نستخدم الخاصيات (Props). لكن تخيل اننا لدينا شجرة كبيرة من المُكونات , و المُكون الحفيد يحتاج إلي بيانات من المُكون الجد الأعلي منه . بإستخدام الخاصيات (Props) فقط , سوف نتمكن من تمرير نفس الخاصية إلي سلسلة الآباء كاملةً لكي ننقلها من المُكون الجد إلي المُكون الحفيد

لاحظ ان علي الرغم من ان المُكون <Footer> لا يحتاج هذه الخاصيات علي الإطلاق , ولكن لا يزال بحاجة إلي تعريفها و تمريرها حتي يتمكن المُكون <DeepChild> من الوصول إليها . إذا كان هناك سلسلة من الآباء أطول مُكونات اكثر سيتم تمرير الخاصيات إليها و هي ليس بحاجة لها . و هذا يسمي "التمرير العميق للخاصيات" وبالتأكيد ليس من الجيد فعله

يمكننا حل مشكلة التمرير العميق للخاصيات (Props Drilling) عن طريق إستخدام التزويد و الحقن provide و inject . ان يكون المُكون الأب هو مُزود التبعية (dependency provider) لكل المُكونات الأحفاد له . يمكن ان يتم حقن inject أي مُكون في شجرة الأحفاد و الأبناء بغض النظر عن مدي عمق هذا المُكون بالتباعيات المقدمة من المُكونات الأعلي (الآباء او الجدود) في هذه السلسلة

التزويد ​

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

provide(/* المفتاح */ 'message', /* القيمة */ 'hello!')
</script>

import { provide } from 'vue'

export default {
  setup() {
    provide(/* المفتاح */ 'message', /* القيمة */ '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() {
    // `this` عند استخدام صيغة الدالة يمكننا استخدام 
    return {
      message: this.message
    }
  }
}

التزويد علي مستوى التطبيق ​

بالإضافة إلي تزويد البيانات إلي المُكونات , يمكن ايضاً تزويدها علي مستوي التطبيق:

import { createApp } from 'vue'

const app = createApp({})

app.provide(/* المفتاح */ 'message', /* القيمة */ 'hello!')

التزويد علي مستوي التطبيق يكون متاح لجميع المُكونات التي تم عرضها (Rendered components) في التطبيق . هذا الشكل مفيد خاصةً في حالة إنشاء إضافات, لأن الإضافات عادةً لن تكون قادرة علي تزويد القيم بإستخدام المُكونات

الحقن ​

<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) // القيمة التي تم حقنها
  }
}

export default {
  inject: ['message'],
  data() {
    return {
      // القيمة الإبتدائية إعتماداُ علي القيمة التي تم حقنها
      fullMessage: this.message
    }
  }
}

export default {
  inject: {
    /* المفتاح المحلي */ localMessage: {
      from: /* مفتاح الحقن */ 'message'
    }
  }
}

القيم الإفتراضية للحقن ​

بشكل أفتراضي , يفترض inject ان المفتاح المحقون تم تزويده في مكانً ما في سلسلة الاَباء . لذالك في حالة عدم تزويده سيتم إظهار رسالة تحذير وقت التشغيل

في حالة اننا نريد ان نجعل خاصية الحقن تعمل بشكل اختياري في حالة تم تزويدها أو لا . يجب تعريف قيمة إبتدائية مثل التي في الخاصيات (Props):

// 'default value' سوف تكون قيمتها `value`
// "message" في حالة عدم تزويد خاصية بإسم 
const value = inject('message', 'default value')

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

export default {
  // (inject object) هيئة الكائن مطلوبة
  // عند تعريف قيم إفتراضية للحقن
  inject: {
    message: {
      from: 'message', //  اختياري في حالة استخدام نفس اسم مفتاح الحقن
      default: 'default value'
    },
    user: {
      // (non-primitive values) استخدم دالة المصنع للقيم الغير بدائية 
      // لإنشاء , أو التي يجب ان تكون غير متكررة لكل نسخة مُكون
      default: () => ({ name: 'John' })
    }
  }
}

استخدام الصيغ التفاعلية ​

<!-- داخل مُكون التزويد-->
<script setup>
import { provide, ref } from 'vue'

const location = ref('North Pole')

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

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

<!-- داخل مُكون الحقن -->
<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 {
      // بشكل مباشر (computed property) تزويد خاصية محسوبة  
      message: computed(() => this.message)
    }
  }
}

استخدام المفاتيح الرموز Symbols Keys ​

حتي الأن , لقد قمنا بإستخدام مفاتيح الحقن النصية في الأمثلة السابقة . إذا كنت تعمل علي تطبيق كبير مع العديد من مُزودي التباعية (dependency providers) , أو انت مسؤول عن مُكونات سيتم إستخدامها من قبل مُطورين أخرين , من الأفضل إستخدام مفاتيح الحقن الرموز (Symbol injection keys) لتجنب الصدامات المحتملة

من الأفضل إستخراج الرموز من ملف مخصوص لها:

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

// في مُكون التزويد
import { provide } from 'vue'
import { myInjectionKey } from './keys.js'

provide(myInjectionKey, {
  /* البيانات المُراد تزويدها */
})

// في مُكون الحقن
import { inject } from 'vue'
import { myInjectionKey } from './keys.js'

const injected = inject(myInjectionKey)

// في مُكون التزويد
import { myInjectionKey } from './keys.js'

export default {
  provide() {
    return {
      [myInjectionKey]: {
         /* البيانات المُراد تزويدها */
      }
    }
  }
}

// في مُكون الحقن
import { myInjectionKey } from './keys.js'

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