工具和程式庫的相互依附

建構依附元件是指建構專案時所需的外部元件。建構作業可以依賴程式庫、外掛程式、子專案、Android SDK、工具 (例如 Kotlin 和 Java 編譯器)、開發環境 (例如 Android Studio) 和 Gradle 本身。

每個依附元件本身可能需要其他依附元件。我們稱這些為遞移依附元件，可迅速增加應用程式使用的整體依附元件。無論是程式庫、工具或 Android SDK，只要您想升級依附元件，升級作業就會依序進行，升級許多其他依附元件。

這通常不會造成問題，因為許多程式庫遵循名為語意化版本的配置。這些程式庫會限制所做的變更類型，以便與舊版相容。

語意版本管理採用 major.minor.patch 格式。舉例來說，在版本號碼 4.8.3 中，4 是 major 版本，8 是 minor 版本，而 3 是 patch 號碼。當 major 部分變更時，程式庫的 API 或行為可能會發生重大變更。這可能會影響您的建構或應用程式行為。

當 minor (新功能) 或 patch (錯誤修正) 部分變更時，程式庫開發人員會告知您，程式庫仍相容，且不會影響您的應用程式。

因此，您必須留意這類變更，而多種依附元件升級工具可提供協助。

建構內容中的關係

Android 版本包含以下項目之間的關係：

• 原始碼：由您控管的程式碼和資源
• 程式庫依附元件：專案和子專案在建構時所包含的外部程式庫或模組
• 工具：編譯器、外掛程式和 SDK，可將來源轉譯為應用程式或程式庫

原始碼

原始碼是您在應用程式或程式庫中編寫的 Kotlin 或 Java 程式碼。(如要進一步瞭解使用 C++，請參閱 Android NDK)。

原始碼會依賴程式庫 (包括 Kotlin 和 Java 執行階段程式庫) 和 Android SDK，並需要對應的 Kotlin 或 Java 編譯器。

部分原始碼包含需要額外處理的註解。舉例來說，如果您要編寫 Jetpack Compose 程式碼，您可以新增需要由 Compose Kotlin 編譯器外掛程式處理的註解，例如 @Composable。其他註解可由 Kotlin 符號處理器 (KSP) 或獨立的註解處理工具處理。

程式庫依附元件

程式庫包含應用程式所擷取的位元組碼。可以是 Java JAR、Android 程式庫 (AAR) 或建構作業中的子專案。許多程式庫都會遵循語意化版本管理，有助您瞭解升級時是否仍相容 (或無法運作)。

程式庫可能會依附其他可重複使用的程式庫，稱為「轉介依附元件」。這會減少必須明確管理的依附元件；您可以指定直接使用的依附元件，Gradle 會連同這些遞移依附元件一起提取依附元件。請注意，當您升級直接依附元件時，他們可能會升級這些遞移依附元件。

有時，程式庫可能會在執行階段 (minSdk) 或編譯期間 (compileSdk) 要求 Android SDK 的最低版本。如果程式庫使用 Android SDK 或其提供的 JDK API 中的函式，就必須這樣做。應用程式的有效 minSdk 是應用程式和所有直接和遞移的程式庫依附元件所要求的最高 minSdk。

使用某些程式庫時，可能需要使用特定的 Gradle 外掛程式。這些輔助外掛程式通常會安裝 Kotlin 符號處理器或其他註解處理器，以產生程式碼或修改來源編譯內容，以便您使用程式庫功能。舉例來說，Jetpack Room 包含註解和 KSP，可將註解和 KSP 轉換為產生的程式碼，以便在資料庫中擷取及修改資料。Jetpack Compose 需要 Compose 編譯器外掛程式，修改加註的函式，以管理重新執行該函式的方式和時間。

工具

Gradle 範圍

Gradle 會將程式庫依附元件分組至不同的範圍 (在 Gradle API 中稱為「設定」)，讓您指定在建構作業的不同部分中要使用的不同程式庫依附元件組合。舉例來說，您可能不想在已發布的應用程式或程式庫中加入 JUnit 等測試程式庫，但在建構及執行單元測試時，您可能會需要這些程式庫。您也可以使用範圍新增符號或註解處理程序，以便分析程式碼。

舉例來說，AGP 定義了 implementation 和 api 範圍，讓您指定是否應向子專案使用者公開依附元件。如要瞭解在 Android 建構中使用的這些和其他範圍，請參閱「設定依附元件」。

在建構檔案的 dependencies 區塊中新增程式庫依附元件，可做為 group:artifact:version 字串：

// In a module-level build script
// explicit dependency strings ("group:artifact:version")
dependencies {
    implementation("com.example:library1:1.2.3")
    api("com.example:library2:1.1.1")
}

// In a module-level build script
// explicit dependency strings ("group:artifact:version")
dependencies {
    implementation 'com.example:library1:1.2.3'
    api 'com.example:library2:1.1.1'
}

或在版本目錄中：

# Version catalog - gradle/libs.versions.toml
[versions]
exampleLib = "1.2.3"
examplePlugin = "2.3.4"

[libraries]
example-library = { group = "com.example", name = "library", version.ref = "exampleLib" }

[plugins]
example-plugin = { id = "com.example.plugin", version.ref = "examplePlugin" }

並在建構檔案中指定產生的變數：

// In a module-level build script
// Using a version catalog
plugins {
    alias(libs.plugins.example.plugin)
}

dependencies {
    implementation(libs.example.library)
}

// In a module-level build script
// Using a version catalog
plugins {
    alias(libs.plugins.example.plugin)
}

dependencies {
    implementation libs.example.library
}