準備要發布的程式庫

本頁說明如何使用 Android Gradle 外掛程式 (AGP) 設定所需屬性和選項，以便發布 Android 程式庫專案。即使您剛開始建立程式庫時就已經設定好某些屬性，請參閱以下指引，以便改善您的設定。

選擇命名空間

Android 程式庫必須宣告命名空間，才能在編譯資源時產生不重複的 R 類別。該命名空間應與程式庫的根類別套件高度吻合，以免使用者從程式庫匯入一般類別與其 R 類別時產生混淆。

從 AGP 7.0 開始，您可以在應用程式的 build.gradle 檔案中設定命名空間，如以下程式碼範例所示：

Groovy

android {
  namespace = 'com.example.library'
}

Kotlin

android {
  namespace = "com.example.library"
}

命名空間是向開發人員顯示的程式庫屬性，這和使用 applicationId 屬性設定的應用程式身分完全無關。

在先前的 AGP 版本中，應用程式的 applicationId 屬性和程式庫的 namespace 屬性都能透過資訊清單的 package 屬性進行設定，因而造成混淆。

選擇 minSdkVersion 值

在程式庫發布程序中，選取程式庫的 minSdkVersion 值是相當重要的環節。minSdkVersion 值應反映程式碼可支援的最低 Android 版本。

選擇 minSdkVersion 值時，請注意下列事項：

  • 一般而言，選擇較低的 minSdkVersion 值可讓程式庫的發布範圍更廣泛。

    通常只有在應用程式明確呼叫程式庫的情況下，系統才會執行程式庫的程式碼。如果程式庫不是應用程式核心功能的關鍵要素，您還是可以在低於程式庫依附元件要求的 Android 版本上執行應用程式，只要在呼叫程式庫前完成執行階段檢查即可。因此，為程式庫設定夠低的 minSdkVersion 值，以便將程式庫嵌入應用程式並盡可能呼叫，可能有助於您觸及更多使用者。

  • 選擇較高的 minSdkVersion 值可能會導致應用程式無法納入程式庫。

    資訊清單合併工具是 AGP 的其中一個步驟，可合併應用程式與其依附元件中的資訊清單檔案，強制確保所有依附元件的 minSdkVersion 值皆不高於應用程式的屬性值。

  • 選擇較高的 minSdkVersion 值可能會促使應用程式開發人員停用資訊清單合併工具的安全檢查功能，導致後續的建構程序發生問題。

    使用資訊清單合併工具會導致應用程式專案無法納入 minSdkVersion 值高於應用程式的程式庫，因此應用程式開發人員可能會停用資訊清單合併工具的安全檢查功能，以盡可能減少建構錯誤。不過，這可能導致下游實際發生不相容的問題。

  • 在特殊情況下，您可能必須選擇較高的 minSdkVersion 值，例如程式庫的資訊清單包含廣播接收器或包含可自動觸發程式碼的某些其他機制等情形。

    在這種情況下，請選擇較高的 minSdkVersion 值，確保程式碼能順利執行。或者，您也可以停用自動行為，讓應用程式先完成適當的檢查再選擇執行程式庫。

請注意，如要嵌入應用程式，程式庫應使用 RequiresApi 註解向呼叫端指示呼叫端需要執行執行階段檢查。Android Lint 會使用 RequiresApi 資訊檢查程式碼。想進一步瞭解如何使用註解改善 API 和 API 程式碼檢查程序，請按這裡參閱其他資源。

設定 AAR 中繼資料

Android 程式庫以 Android ARchive (AAR) 檔案的形式封裝。AAR 中繼資料包含有助於 AGP 使用程式庫的屬性。如果使用者以不相容的設定使用程式庫，而且您已設定 AAR 中繼資料，使用者就會收到錯誤訊息，以協助他們解決問題。

選擇 minCompileSdk 值

從版本 4.1 開始，AGP 會支援 minCompileSdk，這個屬性表示使用者專案可用的最低 compileSdk。如果程式庫包含資訊清單項目或包含使用較新平台屬性的資源，您可能需要設定這個值。

您可以在模組層級 build.gradle 檔案的 defaultConfig{}、productFlavors{} 和 buildTypes{} 區塊中設定 minCompileSdk 值：

Groovy

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    foo {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

Kotlin

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    register("foo") {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

如果您在多個位置設定 minCompileSdk 值，Gradle 會在建構程序中以下列順序優先採用這些位置的設定：

  1. buildTypes{}

  2. productFlavors{}

  3. defaultConfig{}

在上述範例中，minCompileSdk 同時定義了 defaultConfig{} 和 productFlavors{}，productFlavors{} 的優先順序，而 minCompileSdk 則設定為 30。

如要進一步瞭解 Gradle 在結合程式碼和資源時採用設定的優先順序，請參閱使用來源集進行建構。

啟用測試韌體

您通常會使用測試韌體設定要測試的程式碼或協助測試元件。從版本 7.1 開始，除了應用程式和動態功能專案以外，AGP 還能為程式庫專案建立測試韌體。

發布供其他人使用的程式庫時，建議您為 API 建立測試韌體。您可以在模組層級 build.gradle 檔案中啟用測試韌體：

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

如果您啟用測試韌體，Gradle 就會自動建立 src/testFixtures 來源集讓您寫入測試韌體。

想進一步瞭解如何使用測試韌體，請參閱 Gradle 的這份說明文件。