建立 Android 程式庫

Android 程式庫的結構與 Android 應用程式模組相同，其中包含建構應用程式需要的所有內容，包括原始碼、資源檔案和 Android 資訊清單。

不過，Android 程式庫不會編譯至在裝置上執行的 APK，而是會編譯至 Android ARchive (AAR) 檔案，用來做為 Android 應用程式模組的依附元件。與 JAR 檔案不同，AAR 檔案為 Android 應用程式提供下列功能：

  • AAR 檔案可包含 Android 資源和資訊清單檔案，因此除了 Kotlin 或 Java 類別和方法之外，您還可以將共用資源 (例如版面配置和可繪項目) 封裝。
  • AAR 檔案可以包含 C/C++ 程式庫，供應用程式模組的 C/C++ 程式碼使用。

程式庫模組在下列情況中非常實用：

  • 建構使用部分相同元件 (例如活動、服務或 UI 版面配置) 的多個應用程式
  • 建構的應用程式有多個共用核心元件的 APK 變化版本 (例如免費版和付費版)

無論是何種情況，只要將想重複使用的檔案移至程式庫模組，然後將程式庫新增為每個應用程式模組的依附元件即可。

本頁面將說明如何建立及使用 Android 程式庫模組。如需發布程式庫的操作指引，請參閱「發布程式庫」。

建立程式庫模組

如要在專案中建立新的程式庫模組，請按照下列步驟操作：

  1. 依序點選「File」>「New」>「New Module」。
  2. 在隨即顯示的「Create New Module」對話方塊中，依序點選「Android Library」和「Next」。

    您也可以選擇建立能建構傳統 JAR 檔案 的 Kotlin 或 Java 程式庫。雖然 JAR 檔案對許多專案非常實用 (特別是想與其他平台分享程式碼時)，不過，JAR　檔案不允許加入 Android 資源或資訊清單檔案，而這對在 Android 專案中重複使用程式碼非常有用。因此，本指南著重於講解如何建立 Android 程式庫。

  3. 為程式庫命名，並在程式庫中選取該程式碼的最低 SDK 版本，然後按一下「Finish」。

Gradle 專案同步處理完成後，程式庫模組會顯示在「Project」窗格中。如果沒有看到新的模組資料夾，請確認該窗格顯示的是 Android 檢視畫面。

將應用程式模組轉換為程式庫模組

如果現有的應用程式模組中有您要重複使用的程式碼，可以按照下列步驟，將其轉換為程式庫模組：

  1. 如果使用的是 Groovy，請開啟模組層級的 build.gradle 檔案；如果使用的是 Kotlin 指令碼，請開啟 build.gradle.kts 檔案。
  2. 刪除 applicationId 這一行。只有 Android 應用程式模組可以定義該行。
  3. 在檔案頂端找到「plugins」區塊，內容大致如下：

    Groovy

      plugins {
      id 'com.android.application'
  }

    Kotlin

      plugins {
      id("com.android.application")
  }

    將其變更為以下程式碼：

    Groovy

      plugins {
      id 'com.android.library'
  }

    Kotlin

      plugins {
      id("com.android.library")
  }
  4. 儲存檔案，然後依序點選「File」>「Sync Project with Gradle Files」。

模組的結構將維持不變，但現在是以 Android 程式庫的形式運作。建構作業會建立 AAR 檔案，而非 APK。

如要建構 AAR 檔案，請在「Project」視窗中選取程式庫模組，然後依序點選「Build」>「Build APK」。

利用「Project Structure」對話方塊新增依附元件

您可以使用「Project Structure」對話方塊，將依附元件新增至專案中。以下章節說明如何使用對話方塊新增依附元件。

在相同專案中使用程式庫

如要在相同專案的其他應用程式或程式庫模組中使用新的 Android 程式庫程式碼，請新增專案層級的依附元件：

  1. 依序點選「File」>「Project Structure」>「Dependencies」。
  2. 選取要新增程式庫的模組。
  3. 在「Declared Dependencies」分頁中，按一下 圖示，然後從選單中選取「Module Dependency」。

  4. 在「Add Module Dependency」對話方塊中，選取程式庫模組。

    在「Project Structure」對話方塊中新增模組依附元件

  5. 選取需要這項依附元件的設定，如果元件適用於所有設定，則請選取「implementation」，然後按一下「OK」。

Android Studio 會編輯模組的 build.gradle 或 build.gradle.kts 檔案，透過下列格式新增依附元件：

Groovy

  implementation project(path: ":example-library")

Kotlin

  implementation(project(":example-library"))

在其他專案中使用程式庫

共用依附元件 (JAR 和 AAR) 的建議方法是使用 Maven 存放區 (可能由 Maven Central 這類服務代管，或是以目錄結構的形式存於本機磁碟上)。如要進一步瞭解如何使用 Maven 存放區，請參閱「遠端存放區」一節。

將 Android 程式庫發布至 Maven 存放區時，中繼資料會包含在內，因此程式庫的依附元件會納入正在使用的版本中，以便在多個位置使用程式庫時自動刪除重複訊息。

如要在不同專案的其他應用程式模組中使用 Android 程式庫的程式碼，請按照下列步驟操作：

  1. 依序點選「File」>「Project Structure」>「Dependencies」。
  2. 在「Declared Dependencies」分頁中，按一下 ，然後在選單中選取「Library Dependency」。

  3. 在「Add Library Dependency」對話方塊中，使用搜尋框找出要新增的程式庫。此表單會搜尋 settings.gradle 或 settings.gradle.kts 檔案的 dependencyResolutionManagement { repositories {...}} 區塊中指定的存放區。

    在「Project Structure」對話方塊中新增程式庫依附元件

  4. 選取需要這項依附元件的設定，如果元件適用於所有設定，則請選取「implementation」，然後按一下「OK」。

查看應用程式的 build.gradle 或 build.gradle.kts 檔案，確認宣告類似以下內容 (視您選取的建構設定而定)：

Groovy

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

  implementation("com.example:examplelibrary:1.0.0")

新增 AAR 或 JAR 做為依附元件

如要在其他應用程式模組中使用 Android 程式庫的程式碼，請按照下列步驟操作：

  1. 依序點選「File」>「Project Structure」>「Dependencies」。
  2. 在「Declared Dependencies」分頁中，按一下 ，然後在選單中選取「Jar Dependency」。

  3. 在「Add Jar/Aar Dependency」對話方塊中，輸入 AAR 或 JAR 檔案的路徑，然後選取要套用依附元件的設定。如果程式庫應適用於所有設定，請選取「implementation」設定。

    在「Project Structure」對話方塊中新增 AAR 依附元件

    查看應用程式的 build.gradle 或 build.gradle.kts 檔案，確認宣告類似以下內容 (視您選取的建構設定而定)：

    Groovy

      implementation files('my_path/my_lib.aar')

    Kotlin

      implementation(files("my_path/my_lib.aar"))

如要匯入在 Android Studio 以外執行的 Gradle 建構作業的依附元件，請在應用程式的 build.gradle 或 build.gradle.kts 檔案中新增依附元件的路徑。例如：

Groovy

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

Kotlin

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

如要進一步瞭解如何新增 Gradle 依附元件，請參閱「新增建構依附元件」一文。

宣告公開資源

資源包含您專案 res/ 目錄中的所有檔案，例如圖片。程式庫中的所有資源皆預設為公開。如要讓所有資源以不公開的方式提供，您必須將至少一個特定屬性定義為公開。

如要宣告公開資源，請將 <public> 宣告新增至程式庫的 public.xml 檔案。如果您未曾新增公開資源，需在程式庫的 res/values/ 目錄中建立 public.xml 檔案。

下列程式碼範例會建立兩個名為 mylib_app_name 和 mylib_public_string 的公開字串資源：

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

為避免程式庫使用者存取僅限內部使用的資源，請宣告一或多項公開資源，藉此使用這個自動標示為不公開的機制。或者，您也可以新增一個空白的 <public /> 標記，將所有資源設為不公開。這樣並不會將任何項目設為公開，而是會將所有資源設為不公開。

提醒您，凡是要讓使用您程式庫的開發人員看到的資源，皆應設為公開。

只要將屬性設為不公開，您的程式庫使用者就不會收到內部程式庫資源提供的程式碼完成建議，也能讓使用者重新命名或移除不公開資源，而不破壞程式庫的用戶端。不公開的資源會從程式碼完成建議中篩除，而當您嘗試參照這類資源時，Lint 工具也會顯示警告訊息。

建構程式庫時，Android Gradle 外掛程式會取得公開資源定義，並擷取至 public.txt 檔案中，該檔案會封裝至 AAR 檔案中。

程式庫模組的開發注意事項

開發程式庫模組和依附應用程式時，請留意下列行為和限制。

  • 程式庫會依優先順序合併。

    將程式庫模組的參照新增至 Android 應用程式模組後，即可設定模組的相對優先順序。程式庫會在建構期間與應用程式逐一合併，從最低優先順序開始。

    程式庫中的資源參照會參照合併的資源，但不一定是程式庫資源。如果有同名的資源，程式庫模組就無法強制使用自己的資源，而非應用程式或其他程式庫的資源。

  • 避免資源合併衝突。

    建構工具會將程式庫模組中的資源，與依附應用程式模組的資源合併。如果兩個模組都定義了特定的資源名稱，系統會使用應用程式的資源。

    如果多個 AAR 程式庫之間發生衝突，系統會採用依附元件清單 (位於 dependencies 區塊頂端附近) 所列出第一個程式庫的資源。

    為了避免資源衝突，請考慮使用獨有的前置字串或其他一致的命名配置 (或在所有專案模組中則不得重複)。

  • 在多模組建構作業中，JAR 依附元件會視為遞移依附元件。

    將 JAR 依附元件新增至輸出 AAR 的程式庫專案時，JAR 會由程式庫模組處理，並與該模組的 AAR 一併封裝。

    不過請注意，如果專案含有由應用程式模組使用的程式庫模組，該應用程式模組會將程式庫的本機 JAR 依附元件視為遞移依附元件。在這種情況下，本機 JAR 會由使用該元件的應用程式模組處理，而不是由程式庫模組處理。這會加快因變更程式庫程式碼造成的漸進式建構作業。

    凡是由本機 JAR 依附元件造成的 Java 資源衝突，都必須在使用程式庫的應用程式模組中解決。

  • 程式庫模組可以依附外部 JAR 程式庫。

    您可以開發依附外部程式庫的程式庫模組。在這種情況下，依附的模組必須根據包含外部程式庫的目標進行建構。

    請注意，不論是程式庫模組還是依附的應用程式，都必須在相應資訊清單檔案的 <uses-library> 元素中宣告外部程式庫。

  • 應用程式模組的 minSdkVersion 必須等於或大於程式庫定義的版本。

    程式庫會編譯成依附應用程式模組的一部分，因此程式庫模組使用的 API 必須與應用程式模組支援的平台版本相容。

  • 每個程式庫模組都會建立自己的 R 類別。

    建構依附的應用程式模組時，程式庫模組會編譯成 AAR 檔案，然後新增至應用程式模組中。因此，每個程式庫都會有自己的 R 類別，並依據程式庫的套件名稱命名。

    透過主要模組和程式庫模組產生的 R 類別會在所有需要的套件中建立，包括主要模組的套件和程式庫的套件。

  • 程式庫模組可能包含模組本身的 ProGuard 設定檔。

    如果您有用來建構並發布 AAR 的程式庫專案，可以將 ProGuard 設定檔新增至程式庫的建構設定。這樣的話，Android Gradle 外掛程式就會套用您指定的 ProGuard 規則。建構工具會將這個檔案嵌入為程式庫模組產生的 AAR 檔案。而您將程式庫新增至應用程式模組後，系統會將程式庫的 ProGuard 檔案附加到應用程式模組的 ProGuard 設定檔 (proguard.txt)。

    將 ProGuard 檔案嵌入程式庫模組後，即可確保需要依附程式庫的應用程式模組不用手動更新 ProPro 檔案，即可使用您的程式庫。Android Studio 建構系統會一併使用應用程式模組和程式庫的指令建構應用程式。因此，您不需要另外在程式庫上執行程式碼縮減器。

    如要將 ProGuard 規則新增至程式庫專案，請在程式庫 build.gradle 或 build.gradle.kts 檔案的 defaultConfig 區塊內，使用 consumerProguardFiles 屬性指定檔案名稱。

    舉例來說，下列程式碼片段會將 lib-proguard-rules.txt 設為程式庫的 ProGuard 設定檔：

    Groovy

    android {
    defaultConfig {
        consumerProguardFiles 'lib-proguard-rules.txt'
    }
    ...
}

    Kotlin

    android {
    defaultConfig {
        consumerProguardFiles("lib-proguard-rules.txt")
    }
    ...
}

    但是，如果您的程式庫模組隸屬於編譯成 APK 的多模組版本，且不會產生 AAR，請僅針對會存取程式庫的應用程式模組執行程式碼縮減作業。如要進一步瞭解 ProGuard 規則及其用途，請參閱「縮減、模糊處理及最佳化應用程式」。

  • 測試程式庫模組與測試應用程式幾乎相同。

    主要差別在程式庫及其依附元件會自動成為測試 APK 的依附元件。這表示測試 APK 不僅包含本身的程式碼，也包含程式庫的 AAR 及其所有依附元件。由於沒有測試中的獨立應用程式，因此 androidTest 工作只會安裝 (及解除安裝) 測試 APK。

    合併多個資訊清單檔案時，Gradle 會遵循預設的優先順序，將程式庫的資訊清單合併至測試 APK 的主要資訊清單。

AAR 檔案剖析

AAR 檔案的副檔名為 .aar，Maven 構件類型也是 aar。檔案本身則為 ZIP 檔案。唯一的必要項目是 /AndroidManifest.xml。

AAR 檔案也可能包含下列一或多個選用項目：