建立 Android 程式庫

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

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

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

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

建立程式庫模組

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

  1. 依序點選「File」>「New」>「New Module」
  2. 在出現的「Create New Module」視窗中,依序按一下「Android Library」和「Next」

    您也可以選擇建立 Java 程式庫,藉此建構傳統的 JAR 檔案。JAR 檔案對於許多專案非常實用 (尤其是您想與其他平台共用程式碼時),您將無法加入 Android 資源或資訊清單檔案,這對於程式碼重複使用而言非常實用。因此本指南著重於建立 Android 程式庫。

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

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

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

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

  1. 開啟模組層級 build.gradle 檔案。
  2. 刪除 applicationId 的這一行。 只有 Android 應用程式模組可以定義這項資訊,
  3. 檔案頂端應該會顯示以下內容:

    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」

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

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

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

使用相同專案中的程式庫

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

  1. 依序前往「File」>「Project Structure」>,然後選取「Dependencies」
  2. 選取要在當中使用程式庫的模組。
  3. 在「Declared Dependencies」分頁中,按一下 並在下拉式選單中選取「Module Dependency」

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

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

  5. 選取需要這項依附元件的設定;如果要套用到所有設定請選取「implementation」,然後按一下「OK」。

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

implementation(project(path: ":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 檔案 dependencyResolutionManagement { repositories {...}} 區塊中指定的存放區。

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

  4. 選取需要這項依附元件的設定;如果要套用到所有設定請選取「implementation」。

  5. 查看應用程式的 build.gradle 檔案,確認類似下列宣告 (視您選取的建構設定而定):

    implementation 'com.example:examplelibrary:1.0.0'

新增 AAR 或 JAR 做為依附元件

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

  1. 依序前往「File」>「Project Structure」>「Dependencies」
  2. 在「Declared Dependencies」分頁中,按一下 ,然後在下拉式選單中選取「Dependency」

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

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

  4. 查看應用程式的 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_namemylib_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 檔案可能包含下列一或多個選用項目: