使用 Hilt 插入依附元件

Hilt 是 Android 的依附元件插入程式庫，可減少在專案中手動插入依附元件的樣板。手動插入依附元件時，您必須手動建構每個類別及其依附元件，並透過容器，重複使用及管理依附元件。

Hilt 提供在應用程式使用 DI 的標準做法，為專案的每個 Android 類別提供容器，並自動管理其生命週期。Hilt 是以熱門 DI 程式庫為基礎建構而成 Dagger 可享有以下好處： 編譯時間正確性、執行階段效能、擴充性和 Android Studio 支援團隊 提供的抽象化機制詳情請參閱「Hilt 和 Dagger」。

本指南說明 Hilt 的基本概念及其產生的容器。並包括示範如何啟動現有應用程式，以使用 Hilt。

新增依附元件

首先，請將 hilt-android-gradle-plugin 外掛程式新增至專案的根層級 build.gradle 檔案：

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

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

接著，套用 Gradle 外掛程式，並在 app/build.gradle 檔案中新增以下依附元件：

...
plugins {
  id 'kotlin-kapt'
  id 'com.google.dagger.hilt.android'
}

android {
  ...
}

dependencies {
  implementation "com.google.dagger:hilt-android:2.44"
  kapt "com.google.dagger:hilt-compiler:2.44"
}

// Allow references to generated code
kapt {
  correctErrorTypes true
}

plugins {
  id("kotlin-kapt")
  id("com.google.dagger.hilt.android")
}

android {
  ...
}

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

// Allow references to generated code
kapt {
  correctErrorTypes = true
}

Hilt 使用 Java 8 功能。如要在專案中啟用 Java 8，請在 app/build.gradle 檔案中新增以下內容：

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

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

Hilt 應用程式類別

使用 Hilt 的所有應用程式都必須包含以 @HiltAndroidApp 加註的 Application 類別。

@HiltAndroidApp 會觸發 Hilt 的程式碼產生器，包括做為應用程式層級依附元件容器的應用程式基礎類別。

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

@HiltAndroidApp
public class ExampleApplication extends Application { ... }

產生的 Hilt 元件會附加至 Application 物件的生命週期，並為其提供依附元件。此外，因其是應用程式的父項元件，這表示其他元件可以存取其提供的依附元件。

將依附元件插入 Android 類別

在 Application 類別和應用程式層級中設定 Hilt 後 有可用的元件，Hilt 就可以為其他 Android 類別提供依附元件 具有 @AndroidEntryPoint 註解：

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

@AndroidEntryPoint
public class ExampleActivity extends AppCompatActivity { ... }

Hilt 目前支援下列 Android 類別：

• Application (使用 @HiltAndroidApp)
• ViewModel (使用 @HiltViewModel)
• Activity
• Fragment
• View
• Service
• BroadcastReceiver

使用 @AndroidEntryPoint 為 Android 類別加上註解時，您也必須 為相依的 Android 類別加上註解例如，如果您為片段加上註解，則必須為使用該片段的任何活動加上註解。

@AndroidEntryPoint 會針對專案中的每個 Android 類別產生個別 Hilt 元件。如元件階層所述，這些元件可以從其各自的父項類別接收依附元件。

如要取得元件的依附元件，請使用 @Inject 註解來執行欄位插入：

@AndroidEntryPoint
class ExampleActivity : AppCompatActivity() {

  @Inject lateinit var analytics: AnalyticsAdapter
  ...
}

@AndroidEntryPoint
public class ExampleActivity extends AppCompatActivity {

  @Inject
  AnalyticsAdapter analytics;
  ...
}

Hilt 植入的類別，也可能有其他使用插入功能的基本類別。如果這些類別屬於抽象，則不需要 @AndroidEntryPoint 註解。

如要進一步瞭解 Android 類別插入哪一個生命週期回呼，請參閱「元件生命週期」。

定義 Hilt 繫結

如要執行欄位插入作業，Hilt 必須知道如何從對應的元件提供必要依附元件的執行個體。「繫結」包含提供類型執行個體做為依附元件所需的資訊。

向 Hilt 提供繫結資訊的其中一種方法是「建構函式插入」。請使用類別建構函式上的 @Inject 註解，告知 Hilt 如何提供該類別的例項：

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

public class AnalyticsAdapter {

  private final AnalyticsService service;

  @Inject
  AnalyticsAdapter(AnalyticsService service) {
    this.service = service;
  }
  ...
}

類別中加註建構函式的參數是 該類別。在這個範例中，AnalyticsAdapter 有 AnalyticsService 做為依附元件。因此，Hilt 也必須瞭解如何提供 AnalyticsService 的執行個體。

Hilt 模組

有時類型無法插入建構函式。導致這種情況的原因有很多。舉例來說，您無法使用建構函式插入介面。此外，您也無法透過建構函式插入非自己擁有的類型，例如外部程式庫的類別。在這種情況下，您可以為 Hilt 提供繫結資訊 Hilt 模組。

Hilt 模組是加上 @Module 註解的類別。像 Dagger 遊戲 模組 告知 Hilt 如何提供特定類型的執行個體。與 Dagger 模組不同，您必須使用 @InstallIn 為 Hilt 模組加上註解，以告訴 Hilt 每個模組將使用或安裝的 Android 類別。

您在 Hilt 模組中提供的依附元件，可用於所有產生的 安裝 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
}

public interface AnalyticsService {
  void analyticsMethods();
}

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

@Module
@InstallIn(ActivityComponent.class)
public abstract class AnalyticsModule {

  @Binds
  public abstract AnalyticsService bindAnalyticsService(
    AnalyticsServiceImpl analyticsServiceImpl
  );
}

Hilt 模組 AnalyticsModule 以 @InstallIn(ActivityComponent.class) 加註，因為您希望 Hilt 將該依附元件插入 ExampleActivity。此註解代表 AnalyticsModule 中的所有依附元件都適用於應用程式的所有活動。

使用 @Provides 插入執行個體

介面不一定是建構函式插入類型的唯一案例。如果發生以下情況，也無法插入建構函式：您不是類別的擁有者，因為該類別是來自外部資程式庫 (例如 Retrofit、OkHttpClient 或 Room 資料庫等類別)；或者必須使用建構工具模式建立例項。

請參考上一個範例。如果您並非 AnalyticsService 直接的擁有者 類別，您可以藉由建立 函式，並使用 @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)
  }
}

@Module
@InstallIn(ActivityComponent.class)
public class AnalyticsModule {

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

為相同類型提供多個繫結

如果您需要 Hilt 來提供與依附元件相同的不同類型實作，則必須提供多個繫結給 Hilt。您可以使用「限定詞」定義相同類型的多個繫結。

限定詞是一種註解，當類型定義了多個繫結時，您可以使用該註解來識別類型的特定繫結。

以範例為例。如果需要攔截對 AnalyticsService 的呼叫，可以將 OkHttpClient 物件與攔截器搭配使用。對於其他服務，您可能需要以不同的方式攔截呼叫。在這種情況下，您必須向 Hilt 提供兩種 OkHttpClient 的不同實作方式。

首先，請定義您要為 @Binds 或 @Provides 方法加上註解的限定詞：

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

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

@Qualifier
@Retention(RetentionPolicy.RUNTIME)
private @interface AuthInterceptorOkHttpClient {}

@Qualifier
@Retention(RetentionPolicy.RUNTIME)
private @interface OtherInterceptorOkHttpClient {}

接著，Hilt 需要瞭解如何提供與每個限定詞對應的類型執行個體。在這種情況下，您可以使用 @Provides 搭配 Hilt 模組。這兩種方法的傳回類型皆相同，但限定詞會將兩種方法分別標示為 不同的繫結：

@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()
  }
}

@Module
@InstallIn(ActivityComponent.class)
public class NetworkModule {

  @AuthInterceptorOkHttpClient
  @Provides
  public static OkHttpClient provideAuthInterceptorOkHttpClient(
    AuthInterceptor authInterceptor
  ) {
      return new OkHttpClient.Builder()
                   .addInterceptor(authInterceptor)
                   .build();
  }

  @OtherInterceptorOkHttpClient
  @Provides
  public static OkHttpClient provideOtherInterceptorOkHttpClient(
    OtherInterceptor otherInterceptor
  ) {
      return new 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: AppCompatActivity() {

  @AuthInterceptorOkHttpClient
  @Inject lateinit var okHttpClient: OkHttpClient
}

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

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

// As a dependency of a constructor-injected class.
public class ExampleServiceImpl ... {

  private final OkHttpClient okHttpClient;

  @Inject
  ExampleServiceImpl(@AuthInterceptorOkHttpClient OkHttpClient okHttpClient) {
    this.okHttpClient = okHttpClient;
  }
}

// At field injection.
@AndroidEntryPoint
public class ExampleActivity extends AppCompatActivity {

  @AuthInterceptorOkHttpClient
  @Inject
  OkHttpClient okHttpClient;
  ...
}

最佳做法是，如果您將限定詞加入類型，請將限定詞新增至所有提供該依附元件的方法。離開基地或屬於普通人 沒有限定詞的實作容易出錯，且可能導致 Hilt 插入錯誤的依附元件

Hilt 中的預先定義限定詞

Hilt 提供部分預先定義的限定詞。例如，您可能需要應用程式或活動中的 Context 類別，因此 Hilt 提供了 @ApplicationContext 和 @ActivityContext 限定詞。

假設範例中的 AnalyticsAdapter 類別需要活動的內容。以下程式碼示範了如何向 AnalyticsAdapter 提供活動內容：

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

public class AnalyticsAdapter {

  private final Context context;
  private final AnalyticsService service;

  @Inject
  AnalyticsAdapter(
    @ActivityContext Context context,
    AnalyticsService service
  ) {
    this.context = context;
    this.service = service;
  }
}

如要瞭解 Hilt 中其他預先定義的繫結，請參閱「元件預設繫結」。

為 Android 類別產生的元件

針對可執行欄位插入的每個 Android 類別，@InstallIn 註解中都有可供參照的相關 Hilt 元件。各個 Hilt 元件會負責將其繫結插入至對應的 Android 類別。

以上範例示範如何在 Hilt 模組中使用 ActivityComponent。

Hilt 提供下列元件：

元件生命週期

Hilt 會根據對應 Android 類別的生命週期，自動建立並刪除產生的元件類別執行個體。

元件範圍

根據預設，Hilt 中的所有繫結都「未限定範圍」。這意味著 應用程式要求繫結，Hilt 會建立所需類型的新執行個體。

在本範例中，每次 Hilt 提供 AnalyticsAdapter 做為依附元件時 另一種類型或透過欄位插入 (如 ExampleActivity 中所示)，Hilt 提供 AnalyticsAdapter 的新例項。

然而，Hilt 也允許繫結限定至特定元件。Hilt 只會為每個元件例項建立一次限定範圍的繫結 (此元件即為該繫結的限定範圍)，而且針對該繫結的所有要求都會共用同一例項。

下表列出每個產生元件的範圍註解：

在本範例中，如果您將 AnalyticsAdapter 的範圍限定為 ActivityComponent Hilt 使用 @ActivityScoped 提供同一個 AnalyticsAdapter 例項。 在相應活動的效期內：

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

@ActivityScoped
public class AnalyticsAdapter {

  private final AnalyticsService service;

  @Inject
  AnalyticsAdapter(AnalyticsService service) {
    this.service = service;
  }
  ...
}

假設 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)
  }
}

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

  @Singleton
  @Binds
  public abstract AnalyticsService bindAnalyticsService(
    AnalyticsServiceImpl analyticsServiceImpl
  );
}

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

  @Singleton
  @Provides
  public static AnalyticsService provideAnalyticsService() {
      return new Retrofit.Builder()
               .baseUrl("https://example.com")
               .build()
               .create(AnalyticsService.class);
  }
}

如要進一步瞭解 Hilt 元件範圍，請參閱「在 Android 和 Hilt 中設定範圍」。

元件階層

將模組安裝至元件中，其繫結就能以 該元件或下方任何子元件中其他繫結的依附元件 加入元件階層：

元件預設繫結

每個 Hilt 元件都提供一組預設繫結，讓 Hilt 能夠插入為 將依附元件嵌入自訂繫結請注意，這些繫結對應到一般活動和片段類型，而非任何特定子類別。這是因為 Hilt 使用單一活動元件定義來插入所有活動。每個活動都有這個元件的不同執行個體。

應用程式結構定義繫結也可以使用 @ApplicationContext。例如：

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

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

public class AnalyticsServiceImpl implements AnalyticsService {

  private final Context context;

  @Inject
  AnalyticsAdapter(@ApplicationContext Context context) {
    this.context = context;
  }
}

// The Application binding is available without qualifiers.
public class AnalyticsServiceImpl implements AnalyticsService {

  private final Application application;

  @Inject
  AnalyticsAdapter(Application application) {
    this.application = application;
  }
}

活動內容繫結也可以使用 @ActivityContext。舉例來說：

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

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

public class AnalyticsAdapter {

  private final Context context;

  @Inject
  AnalyticsAdapter(@ActivityContext Context context) {
    this.context = context;
  }
}

// The Activity binding is available without qualifiers.
public class AnalyticsAdapter {

  private final FragmentActivity activity;

  @Inject
  AnalyticsAdapter(FragmentActivity activity) {
    this.activity = activity;
  }
}

在 Hilt 不支援的類別中插入依附元件

Hilt 提供支援最常見的 Android 類別。但是，您可能需要在 Hilt 不支援的類別中執行欄位插入。

在這種情況下，您可以使用 @EntryPoint 註解來建立進入點。進入點是 Hilt 管理程式碼和非 Hilt 管理程式碼之間的邊界。也就是程式碼首次進入 Hilt 管理的物件圖形中的點。進入點可讓 Hilt 使用非 Hilt 管理的程式碼來提供依附元件圖表中的依附元件。

舉例來說，Hilt 無法直接支援內容供應器。如果希望內容 但如要透過 Hilt 取得某些依附元件，您需要定義介面 並為每種繫結類型加上 @EntryPoint 註解， 加入限定詞然後新增 @InstallIn 以指定安裝進入點的元件，如下所示：

class ExampleContentProvider : ContentProvider() {

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

  ...
}

public class ExampleContentProvider extends ContentProvider {

  @EntryPoint
  @InstallIn(SingletonComponent.class)
  interface ExampleContentProviderEntryPoint {
    public AnalyticsService analyticsService();
  }
  ...
}

如要存取進入點，請使用 EntryPointAccessors 提供的適當靜態方法。參數應為元件執行個體或做為元件持有者的 @AndroidEntryPoint 物件。請確認 您將其做為參數傳遞的元件以及 EntryPointAccessors 靜態值 方法都符合 @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()
    ...
  }
}

public class ExampleContentProvider extends ContentProvider {

  @Override
  public Cursor query(...) {
    Context appContext = getContext().getApplicationContext();
    ExampleContentProviderEntryPoint hiltEntryPoint =
      EntryPointAccessors.fromApplication(appContext, ExampleContentProviderEntryPoint.class);
    AnalyticsService analyticsService = hiltEntryPoint.analyticsService();
  }
}

在本範例中，由於進入點會安裝在 SingletonComponent 中，因此您必須使用 ApplicationContext 擷取進入點。如果您要擷取的繫結位於 ActivityComponent 中，請改用 ActivityContext。

Hilt 和 Dagger

Hilt 是以「Dagger」架構為基礎 依附元件插入程式庫，提供整合 Dagger 的標準做法 轉換為 Android 應用程式

關於 Dagger，Hilt 的目標如下：

• 簡化 Android 應用程式的 Dagger 相關基礎架構。
• 建立在應用程式間的一組標準的元件和範圍，方便您設定、可讀性、共用代碼。
• 提供輕鬆為各種建構類型 (例如測試、偵錯或發布) 佈建不同繫結的簡單方法。

因為 Android 作業系統會將自身的許多架構執行個體化 類別，因此您必須在 Android 應用程式中使用 Dagger 實際數量Hilt 會減少在 Android 應用程式中使用 Dagger 時使用的樣板程式碼。Hilt 會自動產生並提供下列資訊：

• 整合 Android 架構類別的元件與原本必須手動建立的 Dagger。
• 範圍註解，可與 Hilt 自動產生的元件搭配使用。
• 預先定義的繫結，代表例如 Application 或 Activity 等 Android 類別。
• 預先定義的限定詞，代表 @ApplicationContext 和 @ActivityContext。

Dagger 和 Hilt 程式碼可以在同一個程式碼集中共存。不過在大部分的情況下 建議您使用 Hilt 來管理 Android 中所有的 Dagger 使用情形。如要將使用 Dagger 的專案遷移至 Hilt，請參閱「遷移指南」和「將 Dagger 應用程式遷移至 Hilt 程式碼研究室」。

其他資源

如要進一步瞭解 Hilt，請參閱下列其他資源：

範例

程式碼研究室

• 在 Android 應用程式中使用 Hilt
• 將 Dagger 應用程式遷移至 Hilt

網誌

• 透過 Hilt 在 Android 中插入依附元件
• 在 Android 和 Hilt 中設定範圍
• 將元件新增至 Hilt 階層
• 將 Google I/O 應用程式遷移至 Hilt