建立 Android 程式庫

Android 程式庫的結構與 Android 應用程式模組相同。其中包含建構應用程式所需的一切，包括原始碼、資源檔案和 Android 資訊清單。不過，Android 程式庫會編譯成 Android 封存 (AAR) 檔案，做為 Android 應用程式模組的依附元件，而非編譯在裝置上執行的 APK。與 JAR 檔案不同，AAR 檔案為 Android 應用程式提供下列功能：

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

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

如要建構多個使用部分相同元件 (例如活動、服務或 UI 版面配置) 的應用程式。
當您建構的應用程式有多個 APK 版本 (例如免費版和付費版)，而且兩者都需要相同的核心元件。

無論是哪一種情況，只要將您要重複使用的檔案移至程式庫模組，然後將程式庫新增為個別應用程式模組的依附元件即可。本頁會說明如何進行這兩種工具。

建立程式庫模組

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

依序點選「File」>「New」>「New Module」。
在出現的「Create New Module」視窗中，依序按一下「Android Library」和「Next」。
您也可以選擇建立 Java 程式庫，藉此建構傳統的 JAR 檔案。JAR 檔案對於許多專案非常實用 (尤其是您想與其他平台共用程式碼時)，您將無法加入 Android 資源或資訊清單檔案，這對於程式碼重複使用而言非常實用。因此本指南著重於建立 Android 程式庫。
為程式庫命名，然後在程式庫中選取該程式碼的最低 SDK 版本，然後按一下「Finish」。

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

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

如果現有的應用程式模組包含您要重複使用的所有程式碼，則可以按照下列方式將其轉換為程式庫模組：

開啟模組層級 build.gradle 檔案。
刪除 applicationId 的這一行。只有 Android 應用程式模組可以定義這項資訊，

檔案頂端應該會顯示以下內容：

Groovy

  plugins {
    id 'com.android.application'
  }

Kotlin

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

變更為：

Groovy

  plugins {
      id 'com.android.library'
  }

Kotlin

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

儲存檔案，然後依序點選「File」>「Sync Project with Gradle」。

就行了！這個模組的整體結構會維持不變，但現在是以 Android 程式庫的形式運作，而建構作業現在會建立 AAR 檔案，而非 APK。

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

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

使用相同專案中的程式庫

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

依序前往「File」>「Project Structure」>，然後選取「Dependencies」。
選取要在當中使用程式庫的模組。
在「Declared Dependencies」分頁中，按一下圖示並在下拉式選單中選取「Module Dependency」。
在「Add Module Dependency」對話方塊中，選取程式庫模組。
選取需要這項依附元件的設定；如果要套用到所有設定請選擇「implementation」，然後按一下「OK」。

Studio 會編輯模組的 build.gradle 檔案，以下列形式新增依附元件：

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

在其他專案中使用程式庫

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

將 Android 程式庫發布至 Maven 存放區時，中繼資料會納入程式庫的依附元件，進而當讓程式庫被使用在多個地點時，會自動複製。

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

依序前往「File」>「Project Structure」>「Dependencies」。
在「Declared Dependencies」分頁中，按一下圖示，然後在下拉式選單中選取「Library Dependency」。
在「Add Library Dependency」對話方塊中，使用搜尋框找出要新增的程式庫。此表單會搜尋 settings.gradle 檔案 dependencyResolutionManagement { repositories {...}} 區塊中指定的存放區。
選取需要這項依附元件的設定；如果要套用到所有設定請選擇「implementation」。
查看應用程式的 build.gradle 檔案，確認類似下列宣告 (視您選取的建構設定而定)：

    implementation 'com.example:examplelibrary:1.0.0'

新增 AAR 或 JAR 做為依附元件

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

依序前往「File」>「Project Structure」>「Dependencies」。
在「Declared Dependencies」分頁中，按一下圖示，然後在下拉式選單中選取「Dependency」。
在「Add Jar/Aar Dependency」對話方塊中，先輸入 .aar 或 .jar 檔案的路徑，然後選取要套用依附元件的設定。如果程式庫適用於所有設定，請選取「implementation」設定。
查看應用程式的 build.gradle 檔案，確認類似下列宣告 (視您選取的建構設定而定)：
```
  implementation files('my_path/my_lib.aar')
```

或者，如果您是在 Android Studio 以外的地方執行 Gradle 建構作業，則可在應用程式的 build.gradle 檔案中新增依附元件的路徑，以匯入依附元件。例如：

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

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

選擇要公開的資源

程式庫中的所有資源預設為公開。如要讓所有資源以不公開的方式提供，您必須將至少一個特定屬性定義為公開。資源包含您的專案 res/ 目錄中的所有檔案，例如圖片。為避免程式庫使用者存取僅限內部使用的資源，請宣告一或多項公開資源，藉此使用這個自動標示為不公開的機制。或者，您也可以新增一個空白 <public /> 標籤，將所有資源設為不公開，藉此將所有資源設為不公開，讓所有內容 (所有資源) 不對外公開。

如要宣告公開資源，請將 <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>

建議您視需要公開資源，讓使用您程式庫的開發人員有瀏覽權限。

如果只是單純將屬性設為私人，不僅程式庫的使用者就看不到內部程式庫資源提供的程式碼完成建議，您也可以重新命名或移除私人資源，而不會中斷程式庫的用戶端。私人資源會從程式碼完成被過濾掉，而當您嘗試參照私人資源時，Lint 也會顯示警告訊息。

建構程式庫時，Android Gradle 外掛程式會取得公開資源定義，並解壓縮到 public.txt 檔案中，再將其轉換為 AAR 檔案。

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

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

將程式庫模組的參照新增至 Android 應用程式模組後，即可設定其模組的優先順序。在建構過程中，系統會將程式庫與應用程式一一合併，從最低優先順序到最高。

資源合併衝突

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

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

為了避免一般資源 ID 發生資源衝突，請考慮使用獨有的前置字串或其他一致的命名配置 (或在所有專案模組中則不得重複)。
在多模組建構作業中，JAR 依附元件被視為傳輸依附元件

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

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

由本機 JAR 依附元件造成的 Java 資源衝突必須在使用程式庫的應用程式模組中解決。
程式庫模組可以依賴外部 JAR 程式庫

您可以開發依賴外部程式庫的程式庫模組。(例如 Google 地圖外部程式庫)。在這種情況下，相依應用程式必須建構包含外部程式庫的目標 (例如 Google API 外掛程式)。另請注意，程式庫模組和相依應用程式必須在資訊清單檔案中，在 <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 檔案的 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 檔案可能包含下列一或多個選用項目：

/classes.jar
/res/
/R.txt
/public.txt
/assets/
/libs/name.jar
/jni/abi_name/name.so (其中 abi_name 是 Android 支援的 ABI 的其中一個)
/proguard.txt
/lint.jar
/api.jar
/prefab/ 用於匯出原生程式庫