إدخال المهام التابعة باستخدام Hilt

‫Hilt هي مكتبة لحقن التبعية في Android تقلّل من الرموز المتكررة الناتجة عن حقن التبعية يدويًا في مشروعك. يتطلب إجراء حقن التبعية اليدوي إنشاء كل فئة وتبعياتها يدويًا، واستخدام الحاويات لإعادة استخدام التبعيات وإدارتها.

توفّر Hilt طريقة عادية لاستخدام حقن التبعية في تطبيقك من خلال توفير حاويات لكل فئة Android في مشروعك وإدارة مراحل نشاطها تلقائيًا. تم إنشاء Hilt استنادًا إلى مكتبة حقن التبعية الشهيرة Dagger للاستفادة من صحة وقت التجميع وأداء وقت التشغيل وقابلية التوسع ودعم استوديو Android الذي توفره Dagger. لمزيد من المعلومات، يُرجى الاطّلاع على Hilt وDagger.

يشرح هذا الدليل المفاهيم الأساسية لـ Hilt والحاويات التي ينشئها. ويتضمّن أيضًا عرضًا توضيحيًا لكيفية تشغيل تطبيق حالي لاستخدام Hilt.

إضافة التبعيات

أولاً، أضِف المكوّن الإضافي hilt-android-gradle-plugin إلى ملف build.gradle الجذر لمشروعك:

Kotlin

plugins {
  ...
  id("com.google.dagger.hilt.android") version "2.57.1" apply false
}

أنيق

plugins {
  ...
  id 'com.google.dagger.hilt.android' version '2.57.1' apply false
}

بعد ذلك، طبِّق المكوّن الإضافي لنظام Gradle وأضِف هذه التبعيات في ملف app/build.gradle:

Kotlin

plugins {
  id("com.google.devtools.ksp")
  id("com.google.dagger.hilt.android")
}

android {
  ...
}

dependencies {
  implementation("com.google.dagger:hilt-android:2.57.1")
  ksp("com.google.dagger:hilt-android-compiler:2.57.1")
}

أنيق

...
plugins {
  id 'com.google.devtools.ksp'
  id 'com.google.dagger.hilt.android'
}

android {
  ...
}

dependencies {
  implementation "com.google.dagger:hilt-android:2.57.1"
  ksp "com.google.dagger:hilt-compiler:2.57.1"
}

للتأكّد من ضبط مشروعك على Java 17، وهو الإصدار المطلوب من قِبل Jetpack Compose وHilt، أضِف ما يلي إلى ملف app/build.gradle:

Kotlin

android {
  ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
  }
}

أنيق

android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
  }
}

فئة تطبيق Hilt

يجب أن تحتوي جميع التطبيقات التي تستخدم Hilt على فئة Application تم التعليق عليها باستخدام @HiltAndroidApp.

يؤدي استخدام @HiltAndroidApp إلى إنشاء رمز Hilt، بما في ذلك صنف أساسي لتطبيقك يعمل كحاوية تبعية على مستوى التطبيق.

@HiltAndroidApp
class ExampleApplication : Application() { ... }

يتم إرفاق مكوّن Hilt الذي تم إنشاؤه بمراحل نشاط عنصر Application ويوفّر له التبعيات. بالإضافة إلى ذلك، هو المكوّن الرئيسي للتطبيق، ما يعني أنّ المكوّنات الأخرى يمكنها الوصول إلى التبعيات التي يوفّرها.

حقن التبعيات في فئات Android

بعد إعداد Hilt في فئة Application وإتاحة مكوّن على مستوى التطبيق، يمكن لـ Hilt توفير التبعيات لفئات Android الأخرى التي تحتوي على التعليق التوضيحي @AndroidEntryPoint:

@AndroidEntryPoint
class ExampleActivity : ComponentActivity() { ... }

تتوافق Hilt حاليًا مع فئات Android التالية:

• ‫Application (باستخدام @HiltAndroidApp)
• ‫ViewModel (باستخدام @HiltViewModel)
• Activity
• Service
• BroadcastReceiver

في Compose، لست بحاجة إلى إضافة تعليقات توضيحية إلى الدوال المركّبة الفردية. بدلاً من ذلك، يمكنك إضافة تعليق توضيحي إلى جذر ComponentActivity باستخدام @AndroidEntryPoint. وهي بمثابة نقطة دخول واحدة لحقن التبعية في التسلسل الهرمي لواجهة المستخدم بالكامل، ما يتيح لك الوصول إلى ViewModels التي تم حقنها باستخدام Hilt مباشرةً داخل الدوال المركّبة.

ملاحظة: لا تتوافق أداة Hilt إلا مع الأنشطة التي تمدّد ComponentActivity، مثل AppCompatActivity.

تنشئ @AndroidEntryPoint مكوّن Hilt فرديًا لكل فئة Android في مشروعك. يمكن لهذه المكوّنات تلقّي التبعيات من الفئات الرئيسية الخاصة بها كما هو موضّح في التسلسل الهرمي للمكوّنات.

للحصول على التبعيات من أحد المكوّنات، استخدِم التعليق التوضيحي @Inject لإجراء الحقن المباشر في المتغيرات:

@AndroidEntryPoint
class ExampleActivity : ComponentActivity() {

  @Inject lateinit var analytics: AnalyticsAdapter
  ...
}

ملاحظة: لا يمكن أن تكون الحقول التي يتم حقنها من خلال Hilt خاصة. وستؤدي محاولة إدخال حقل خاص باستخدام Hilt إلى حدوث خطأ في التجميع.

يمكن أن تحتوي الفئات التي يحقنها Hilt على فئات أساسية أخرى تستخدم أيضًا الحقن. لا تحتاج هذه الفئات إلى التعليق التوضيحي @AndroidEntryPoint إذا كانت مجرّدة.

لمزيد من المعلومات حول الاستدعاء في إحدى مراحل النشاط الذي يتم حقن فئة Android فيه، يُرجى الاطّلاع على فترات نشاط المكوّنات.

تحديد عمليات ربط Hilt

لإجراء الحقن المباشر في المتغيرات، يجب أن يعرف Hilt كيفية توفير نُسخ من التبعيات اللازمة من المكوّن المقابل. يحتوي الربط على المعلومات اللازمة لتوفير مثيلات من نوع معيّن كعنصر تابع.

إحدى طرق تقديم معلومات الربط إلى Hilt هي الحقن عبر المنشئ. استخدِم التعليق التوضيحي @Inject في الدالة الإنشائية لفئة معيّنة لإعلام Hilt بكيفية تقديم نُسخ من هذه الفئة:

class AnalyticsAdapter @Inject constructor(
  private val service: AnalyticsService
) { ... }

تُعدّ معلمات الدالة الإنشائية التي تمّت إضافة تعليقات توضيحية إليها في فئة معيّنة هي تبعيات تلك الفئة. في المثال، يحتوي AnalyticsAdapter على AnalyticsService كعنصر تابع. لذلك، يجب أن يعرف Hilt أيضًا كيفية تقديم نُسخ من AnalyticsService.

ملاحظة: في وقت الإنشاء، تنشئ Hilt مكوّنات Dagger لفئات Android. بعد ذلك، يتصفّح Dagger الرمز البرمجي وينفّذ الخطوات التالية:

• ينشئ الرسوم البيانية التبعية ويتحقّق من صحتها، ما يضمن عدم وجود تبعيات غير مستوفاة وعدم وجود دورات تبعية.
• تنشئ الفئات التي تستخدمها في وقت التشغيل لإنشاء العناصر الفعلية وتبعياتها.

وحدات Hilt

في بعض الأحيان، لا يمكن حقن نوع عبر المنشئ. يمكن أن يحدث هذا لعدة أسباب. على سبيل المثال، لا يمكنك حقن واجهة عبر المنشئ. لا يمكنك أيضًا الحقن عبر المنشئ لنوع لا تملكه، مثل فئة من مكتبة خارجية. في هذه الحالات، يمكنك تزويد Hilt بمعلومات الربط باستخدام وحدات Hilt.

وحدة Hilt هي فئة تمّت إضافة التعليق التوضيحي @Module إليها. وتوفّر هذه الوحدة لـ Hilt تعليمات حول كيفية إنشاء نُسخ من الأنواع التي لا يمكن توفيرها من خلال الحقن عبر المنشئ، مثل الواجهات أو فئات الجهات الخارجية. يجب أيضًا إضافة تعليقات توضيحية إلى كل وحدة باستخدام @InstallIn لإعلام Hilt بفئة Android التي سيتم استخدام كل وحدة أو تثبيتها فيها.

ملاحظة: تختلف وحدات Hilt عن وحدات Gradle.

تتوفّر التبعيات التي تقدّمها في وحدات Hilt في جميع المكوّنات التي تم إنشاؤها والمرتبطة بفئة Android التي تثبّت فيها وحدة Hilt.

ملاحظة: بما أنّ إنشاء الرموز البرمجية في Hilt يتطلّب الوصول إلى جميع وحدات Gradle التي تستخدم Hilt، يجب أن تتضمّن وحدة Gradle التي تُجمِّع فئة Application أيضًا جميع وحدات Hilt والفئات التي تم حقنها عبر المنشئ في تبعياتها الانتقالية.

حقن مثيلات الواجهة باستخدام ‎ @Binds

لنأخذ مثالاً على ذلك AnalyticsService. إذا كان AnalyticsService واجهة، لا يمكنك حقنه عبر المنشئ. بدلاً من ذلك، يمكنك تزويد Hilt بمعلومات الربط من خلال إنشاء دالة مجرّدة تتضمّن التعليق التوضيحي @Binds داخل وحدة Hilt.

يخبر التعليق التوضيحي @Binds Hilt بالتنفيذ الذي يجب استخدامه عندما يحتاج إلى توفير مثيل لواجهة.

توفّر الدالة التي تم التعليق عليها المعلومات التالية لـ Hilt:

• يخبر نوع القيمة التي تم إرجاعها من الدالة Hilt بالواجهة التي توفر الدالة مثيلات لها.
• تُعلم مَعلمة الدالة Hilt بالتنفيذ الذي يجب توفيره.

interface AnalyticsService {
  fun analyticsMethods()
}

// Constructor-injected, because Hilt needs to know how to
// provide instances of AnalyticsServiceImpl, too.
class AnalyticsServiceImpl @Inject constructor(
  ...
) : AnalyticsService { ... }

@Module
@InstallIn(ActivityComponent::class)
abstract class AnalyticsModule {

  @Binds
  abstract fun bindAnalyticsService(
    analyticsServiceImpl: AnalyticsServiceImpl
  ): AnalyticsService
}

تمت إضافة التعليق التوضيحي @InstallIn(ActivityComponent.class) إلى وحدة Hilt‏ AnalyticsModule لأنّك تريد أن يحقن Hilt هذه التبعية في ExampleActivity. يعني هذا التعليق التوضيحي أنّ جميع التبعيات في AnalyticsModule متاحة في جميع أنشطة التطبيق.

حقن النُسخ باستخدام ‎ @Provides

الواجهات ليست الحالة الوحيدة التي لا يمكنك فيها حقن نوع عبر المنشئ. لا يمكن أيضًا استخدام الحقن عبر المنشئ إذا لم تكن تملك الفئة لأنّها تأتي من مكتبة خارجية (فئات مثل Retrofit أو OkHttpClient أو قواعد بيانات Room)، أو إذا كان يجب إنشاء المثيلات باستخدام نمط المنشئ.

لنفترض المثال السابق. إذا لم تكن تملك فئة AnalyticsService مباشرةً، يمكنك إخبار Hilt بكيفية توفير مثيلات من هذا النوع من خلال إنشاء دالة داخل وحدة Hilt وإضافة تعليق توضيحي إلى هذه الدالة باستخدام @Provides.

توفّر الدالة التي تم التعليق عليها المعلومات التالية لـ Hilt:

• يخبر نوع القيمة التي تم إرجاعها من الدالة Hilt بنوع الدالة التي توفر مثيلات لها.
• تُعلم مَعلمات الدالة Hilt بتبعيات النوع المقابل.
• يخبر نص الدالة Hilt بكيفية توفير مثيل للنوع المقابل. ينفّذ Hilt نص الدالة في كل مرة يحتاج فيها إلى تقديم مثيل من هذا النوع.

@Module
@InstallIn(ActivityComponent::class)
object AnalyticsModule {

  @Provides
  fun provideAnalyticsService(
    // Potential dependencies of this type
  ): AnalyticsService {
      return Retrofit.Builder()
               .baseUrl("https://example.com")
               .build()
               .create(AnalyticsService::class.java)
  }
}

توفير عمليات ربط متعددة للنوع نفسه

في الحالات التي تحتاج فيها إلى أن توفّر Hilt عمليات تنفيذ مختلفة من النوع نفسه كعناصر تابعة، يجب أن توفّر لـ Hilt عمليات ربط متعددة. يمكنك تحديد عمليات ربط متعددة للنوع نفسه باستخدام المؤهلات.

المؤهِّل هو تعليق توضيحي يُستخدَم لتحديد ربط معيّن لنوع ما عندما يكون لهذا النوع عمليات ربط متعددة محدّدة.

لنأخذ المثال التالي. إذا كنت بحاجة إلى اعتراض المكالمات إلى AnalyticsService، يمكنك استخدام عنصر OkHttpClient مع معترِض. بالنسبة إلى الخدمات الأخرى، قد تحتاج إلى اعتراض المكالمات بطريقة مختلفة. في هذه الحالة، عليك إخبار Hilt بكيفية توفير طريقتَي استخدام مختلفتَين لـ OkHttpClient.

أولاً، حدِّد المؤهلات التي ستستخدمها لإضافة تعليقات توضيحية إلى الطريقتَين @Binds أو @Provides:

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class AuthInterceptorOkHttpClient

@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class OtherInterceptorOkHttpClient

بعد ذلك، يجب أن يعرف Hilt كيفية توفير مثيل للنوع الذي يتوافق مع كل معرّف. في هذه الحالة، يمكنك استخدام وحدة Hilt مع @Provides. تستخدم كلتا الطريقتين نوع القيمة التي تم إرجاعها نفسه، ولكن تضع المُحدِّدات تصنيفًا لهما كعمليتَي ربط مختلفتَين:

@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

  @AuthInterceptorOkHttpClient
  @Provides
  fun provideAuthInterceptorOkHttpClient(
    authInterceptor: AuthInterceptor
  ): OkHttpClient {
      return OkHttpClient.Builder()
               .addInterceptor(authInterceptor)
               .build()
  }

  @OtherInterceptorOkHttpClient
  @Provides
  fun provideOtherInterceptorOkHttpClient(
    otherInterceptor: OtherInterceptor
  ): OkHttpClient {
      return OkHttpClient.Builder()
               .addInterceptor(otherInterceptor)
               .build()
  }
}

يمكنك إدخال النوع المحدّد الذي تريده من خلال إضافة تعليق توضيحي إلى الحقل أو المَعلمة باستخدام المؤهِّل المقابل:

// As a dependency of another class.
@Module
@InstallIn(ActivityComponent::class)
object AnalyticsModule {

  @Provides
  fun provideAnalyticsService(
    @AuthInterceptorOkHttpClient okHttpClient: OkHttpClient
  ): AnalyticsService {
      return Retrofit.Builder()
               .baseUrl("https://example.com")
               .client(okHttpClient)
               .build()
               .create(AnalyticsService::class.java)
  }
}

// As a dependency of a constructor-injected class.
class ExampleServiceImpl @Inject constructor(
  @AuthInterceptorOkHttpClient private val okHttpClient: OkHttpClient
) : ...

// At field injection.
@AndroidEntryPoint
class ExampleActivity: ComponentActivity() {

  @AuthInterceptorOkHttpClient
  @Inject lateinit var okHttpClient: OkHttpClient
}

كأفضل ممارسة، إذا أضفت مؤهلاً إلى نوع، فأضف مؤهلات إلى جميع الطرق الممكنة لتوفير هذه التبعية. إنّ ترك التنفيذ الأساسي أو الشائع بدون معرِّف يكون عرضة للخطأ وقد يؤدي إلى حقن Hilt للتبعية الخاطئة.

المؤهلات المحدّدة مسبقًا في Hilt

توفّر Hilt بعض المُحدِّدات المحدّدة مسبقًا. على سبيل المثال، قد تحتاج إلى فئة Context من التطبيق أو النشاط، لذا يوفّر Hilt معرّفَي @ApplicationContext و@ActivityContext.

لنفترض أنّ فئة AnalyticsAdapter من المثال تحتاج إلى سياق النشاط. يوضّح الرمز التالي كيفية توفير سياق النشاط إلى AnalyticsAdapter:

class AnalyticsAdapter @Inject constructor(
    @ActivityContext private val context: Context,
    private val service: AnalyticsService
) { ... }

للاطّلاع على عمليات الربط الأخرى المحدّدة مسبقًا والمتاحة في Hilt، يمكنك مراجعة عمليات الربط التلقائية للمكوّنات.

المكوّنات التي تم إنشاؤها لفئات Android

لكل فئة Android يمكنك فيها إجراء الحقن المباشر في المتغيرات، يتوفّر مكوّن Hilt مرتبط يمكنك الرجوع إليه في التعليق التوضيحي @InstallIn. يكون كل مكوّن من مكوّنات Hilt مسؤولاً عن حقن عمليات الربط في فئة Android المقابلة.

أوضحت الأمثلة السابقة استخدام ActivityComponent في وحدات Hilt.

توفّر Hilt المكوّنات التالية:

مكوّن Hilt	حاقن لـ
SingletonComponent	Application
ActivityRetainedComponent	لا ينطبق
ViewModelComponent	ViewModel
ActivityComponent	Activity
ServiceComponent	Service

ملاحظة: لا تنشئ مكتبة Hilt مكوّنًا لأجهزة استقبال البث لأنّها تحقن أجهزة استقبال البث مباشرةً من SingletonComponent.

عمر المكوّنات

تنشئ Hilt تلقائيًا مثيلات لفئات المكوّنات التي تم إنشاؤها وتدمّرها باتّباع مراحل النشاط لفئات Android المقابلة.

المكوّن الذي تم إنشاؤه	وقت الإنشاء:	تم إتلافها في
SingletonComponent	Application#onCreate()	تم تدمير Application
ActivityRetainedComponent	Activity#onCreate()	Activity#onDestroy()
ViewModelComponent	تم إنشاء ViewModel.	تم تدمير ViewModel
ActivityComponent	Activity#onCreate()	Activity#onDestroy()
ServiceComponent	Service#onCreate()	Service#onDestroy()

ملاحظة: يستمر ActivityRetainedComponent في العمل خلال تغييرات الإعدادات، لذلك يتم إنشاؤه في أول Activity#onCreate() ويتم تدميره في آخر Activity#onDestroy().

نطاقات المكوّنات

By default, all bindings in Hilt are unscoped. هذا يعني أنّه في كل مرة يطلب فيها تطبيقك الربط، تنشئ Hilt مثيلاً جديدًا من النوع المطلوب.

في المثال، في كل مرة توفّر فيها Hilt‏ AnalyticsAdapter كعنصر تابع لنوع آخر أو من خلال الحقن المباشر في المتغيرات (كما في ExampleActivity)، توفّر Hilt مثيلاً جديدًا من AnalyticsAdapter.

ومع ذلك، تتيح Hilt أيضًا تحديد نطاق الربط بمكوّن معيّن. تنشئ Hilt عملية ربط محدودة النطاق مرة واحدة فقط لكل مثيل من المكوّن الذي يقتصر نطاق الربط عليه، وتشترك جميع طلبات الربط في المثيل نفسه.

يعرض الجدول أدناه تعليقات توضيحية للنطاق لكل مكوّن يتم إنشاؤه:

فئة Android	المكوّن الذي تم إنشاؤه	النطاق
Application	SingletonComponent	@Singleton
Activity	ActivityRetainedComponent	@ActivityRetainedScoped
ViewModel	ViewModelComponent	@ViewModelScoped
Activity	ActivityComponent	@ActivityScoped
Service	ServiceComponent	@ServiceScoped

في المثال، إذا حدّدت نطاق AnalyticsAdapter على ActivityComponent باستخدام @ActivityScoped، يوفّر Hilt المثيل نفسه من AnalyticsAdapter طوال مدة النشاط المقابل:

@ActivityScoped
class AnalyticsAdapter @Inject constructor(
  private val service: AnalyticsService
) { ... }

ملاحظة: قد يكون تحديد نطاق الربط بمكوّن معيّن مكلفًا لأنّ العنصر المقدَّم يبقى في الذاكرة إلى أن يتم تدمير هذا المكوّن. قلِّل من استخدام عمليات الربط ذات النطاق المحدود في تطبيقك. من المناسب استخدام عمليات الربط على مستوى المكوّن لعمليات الربط ذات الحالة الداخلية التي تتطلّب استخدام المثيل نفسه ضمن نطاق معيّن، أو لعمليات الربط التي تحتاج إلى مزامنة، أو لعمليات الربط التي تبيّن لك أنّ إنشاءها مكلف.

لنفترض أنّ AnalyticsService لديه حالة داخلية تتطلّب استخدام نفس المثيل في كل مرة، ليس فقط في ExampleActivity، ولكن في أي مكان في التطبيق. في هذه الحالة، من المناسب تحديد نطاق AnalyticsService إلى SingletonComponent. والنتيجة هي أنّه عندما يحتاج المكوّن إلى توفير مثيل من AnalyticsService، فإنّه يوفّر المثيل نفسه في كل مرة.

يوضّح المثال التالي كيفية تحديد نطاق ربط بمكوّن في وحدة Hilt. يجب أن يتطابق نطاق الربط مع نطاق المكوّن الذي تم تثبيته فيه، لذا في هذا المثال، يجب تثبيت AnalyticsService في SingletonComponent بدلاً من ActivityComponent:

// If AnalyticsService is an interface.
@Module
@InstallIn(SingletonComponent::class)
abstract class AnalyticsModule {

  @Singleton
  @Binds
  abstract fun bindAnalyticsService(
    analyticsServiceImpl: AnalyticsServiceImpl
  ): AnalyticsService
}

// If you don't own AnalyticsService.
@Module
@InstallIn(SingletonComponent::class)
object AnalyticsModule {

  @Singleton
  @Provides
  fun provideAnalyticsService(): AnalyticsService {
      return Retrofit.Builder()
               .baseUrl("https://example.com")
               .build()
               .create(AnalyticsService::class.java)
  }
}

لمزيد من المعلومات حول نطاقات مكوّنات Hilt، يمكنك الاطّلاع على تحديد النطاق في Android وHilt.

ملاحظة: لمزيد من المعلومات حول الاختلافات بين تحديد النطاق باستخدام @ActivityRetainedScoped أو @ViewModelScoped، يُرجى الاطّلاع على قسم @ViewModelScoped في مستند عمليات دمج Hilt وJetpack.

التدرّج الهرمي للمكوّنات

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

الشكل 1. التسلسل الهرمي للمكوّنات التي تنشئها Hilt

عمليات الربط التلقائية للمكوّنات

يأتي كل مكوّن من مكوّنات Hilt مع مجموعة من عمليات الربط التلقائية التي يمكن لـ Hilt إدخالها كعناصر تابعة في عمليات الربط المخصّصة. يُرجى العِلم أنّ عمليات الربط هذه تتوافق مع نوع النشاط العام وليس مع أي فئة فرعية محدّدة. ويرجع ذلك إلى أنّ Hilt تستخدم تعريفًا واحدًا لمكوّن النشاط لإدخال جميع الأنشطة. يحتوي كل نشاط على مثيل مختلف لهذا المكوّن.

مكوّن Android	عمليات الربط التلقائية
SingletonComponent	Application
ActivityRetainedComponent	Application
ViewModelComponent	SavedStateHandle
ActivityComponent	Application، Activity
ServiceComponent	Application، Service

يتوفّر أيضًا ربط سياق التطبيق باستخدام @ApplicationContext. على سبيل المثال:

class AnalyticsServiceImpl @Inject constructor(
  @ApplicationContext context: Context
) : AnalyticsService { ... }

// The Application binding is available without qualifiers.
class AnalyticsServiceImpl @Inject constructor(
  application: Application
) : AnalyticsService { ... }

يتوفّر أيضًا ربط سياق النشاط باستخدام @ActivityContext. على سبيل المثال:

class AnalyticsAdapter @Inject constructor(
  @ActivityContext context: Context
) { ... }

// The Activity binding is available without qualifiers.
class AnalyticsAdapter @Inject constructor(
  activity: ComponentActivity
) { ... }

إدخال التبعيات في الفئات غير المتوافقة مع Hilt

في Compose، يتمثّل النمط العادي في حقن التبعيات في @HiltViewModel باستخدام الحقن عبر المنشئ، ثم استخدام hiltViewModel() داخل الدالة المركّبة للوصول إلى ViewModel. على الرغم من أنّ Hilt يتوافق مع فئات Android الأكثر شيوعًا، قد تواجه فئات غير متوافقة تحتاج فيها إلى إجراء عملية الحقن المباشر في المتغيرات.

في هذه الحالات، يمكنك إنشاء نقطة دخول باستخدام التعليق التوضيحي @EntryPoint. نقطة الدخول هي الحد الفاصل بين الرمز الذي تديره Hilt والرمز الذي لا تديره. وهي النقطة التي يدخل فيها الرمز لأول مرة إلى الرسم البياني للكائنات التي تديرها Hilt. تسمح نقاط الدخول لـ Hilt باستخدام الرموز البرمجية التي لا يديرها Hilt لتوفير التبعيات ضمن الرسم البياني للتبعية.

على سبيل المثال، لا تتيح Hilt استخدام أدوات توفير المحتوى بشكل مباشر. إذا أردت أن تستخدم أداة توفير المحتوى مكتبة Hilt للحصول على بعض التبعيات، عليك تحديد واجهة تتضمّن التعليق التوضيحي @EntryPoint لكل نوع ربط تريده وتضمين المؤهلات. بعد ذلك، أضِف @InstallIn لتحديد المكوّن الذي تريد تثبيت نقطة الدخول فيه على النحو التالي:

class ExampleContentProvider : ContentProvider() {

  @EntryPoint
  @InstallIn(SingletonComponent::class)
  interface ExampleContentProviderEntryPoint {
    fun analyticsService(): AnalyticsService
  }

  ...
}

للوصول إلى نقطة دخول، استخدِم الطريقة الثابتة المناسبة من EntryPointAccessors. يجب أن تكون المَعلمة إما مثيل المكوّن أو كائن @AndroidEntryPoint الذي يعمل كحامل للمكوّن. تأكَّد من أنّ المكوّن الذي يتم تمريره كمَعلمة والطريقة الثابتة EntryPointAccessors يتطابقان مع فئة Android في التعليق التوضيحي @InstallIn على واجهة @EntryPoint:

class ExampleContentProvider: ContentProvider() {
    ...

  override fun query(...): Cursor {
    val appContext = context?.applicationContext ?: throw IllegalStateException()
    val hiltEntryPoint =
      EntryPointAccessors.fromApplication(appContext, ExampleContentProviderEntryPoint::class.java)

    val analyticsService = hiltEntryPoint.analyticsService()
    ...
  }
}

في هذا المثال، يجب استخدام ApplicationContext لاسترداد نقطة الدخول لأنّ نقطة الدخول مثبَّتة في SingletonComponent. إذا كانت عملية الربط التي تريد استردادها في ActivityComponent، يمكنك استخدام ActivityContext بدلاً من ذلك.

‫Hilt وDagger

‫Hilt هي المكتبة المقترَحة رسميًا لحقن التبعية في Android. فهي توفّر طريقة موحّدة ومحدّدة وفعّالة لتنفيذ حقن التبعية في تطبيقك، وهي محسّنة خصيصًا لـ Jetpack Compose وبُنى النشاط الواحد.

أهداف Hilt هي:

• لإنشاء مجموعة معايير التعلُّم من المكوّنات والنطاقات لتسهيل عملية الإعداد والقراءة ومشاركة الرموز البرمجية بين التطبيقات.
• لتوفير طريقة سهلة لتوفير عمليات ربط مختلفة لأنواع الإصدارات المختلفة، مثل الاختبار أو تصحيح الأخطاء أو الإصدار.

بما أنّ نظام التشغيل Android ينشئ العديد من فئات إطار العمل الخاصة به، فإنّ استخدام Dagger في تطبيق Android يتطلب منك كتابة قدر كبير من الرموز النموذجية. يقلّل Hilt من الرموز البرمجية النموذجية التي يتم استخدامها في Dagger في تطبيق Android. تنشئ Hilt تلقائيًا ما يلي وتوفّره:

• مكوّنات لدمج فئات إطار عمل Android مع Dagger التي قد تحتاج إلى إنشائها يدويًا.
• التعليقات التوضيحية للنطاق لاستخدامها مع المكوّنات التي تنشئها Hilt تلقائيًا
• عمليات الربط المحدّدة مسبقًا لتمثيل فئات Android، مثل Application أو Activity
• محدِّدات مُعرَّفة مسبقًا لتمثيل @ApplicationContext و@ActivityContext

يمكن أن يتوفّر رمز Dagger ورمز Hilt في قاعدة الرموز البرمجية نفسها. ومع ذلك، في معظم الحالات، من الأفضل استخدام Hilt لإدارة جميع استخداماتك لـ Dagger على Android. لنقل مشروع يستخدم Dagger إلى Hilt، يُرجى الاطّلاع على دليل نقل البيانات.

مراجع إضافية

لمزيد من المعلومات حول Hilt، يمكنك الاطّلاع على المراجع الإضافية التالية.

نماذج

المدوّنات

• حقن التبعية على Android باستخدام Hilt
• تحديد النطاق في Android وHilt
• إضافة مكوّنات إلى التسلسل الهرمي في Hilt
• نقل تطبيق Google I/O إلى Hilt

محتوى المشاهدات

• حقن التبعية باستخدام Hilt (طرق العرض)