Gradle 版本目錄可讓您以靈活擴充的方式新增及維護依附元件和外掛程式。如果您有多個模組，不妨使用 Gradle 版本目錄輕鬆管理依附元件和外掛程式。與其在個別建構檔案中對依附元件名稱和版本進行硬式編碼，或在需要升級依附元件時逐一更新項目，不如建立一份集中收錄依附元件的「版本目錄」。這樣一來，各模組即可以類型安全的方式參照該目錄，同時享有 Android Studio 協助。
您可以透過本頁提供的基本資訊，瞭解如何將 Android 應用程式遷移至版本目錄。詳情請參閱「新增建構依附元件」和 Gradle 說明文件。
建立版本目錄檔案
首先，我們來建立版本目錄檔案。在根專案的 gradle 資料夾中，建立名為 libs.versions.toml 的檔案。根據預設，Gradle 會在 libs.versions.toml 檔案中尋找目錄，因此建議您使用這個預設名稱。
在您的 libs.versions.toml 檔案中新增以下區段：
[versions]
[libraries]
[plugins]
這些區段的用途如下：
- 在
versions區塊中，定義保留依附元件和外掛程式版本的變數。您可以在後續區塊 (libraries和plugins區塊) 中使用這些變數。 - 在
libraries區塊中定義依附元件。 - 在
plugins區塊中定義外掛程式。
遷移步驟
建議您依照所列出的順序執行以下步驟。建構作業可能會同時耗用建構指令碼和目錄中的依附元件和外掛程式，因此請花一些時間個別遷移依附元件和外掛程式。
遷移程序如下：
- 將新項目新增至目錄。
- 同步處理 Android 專案。
- 將先前的字串宣告替換為目錄類型安全存取子。
遷移依附元件
在 libs.versions.toml 檔案的 versions 和 libraries 區段中，為每個依附元件都新增一個項目。接著同步處理專案，然後將以上項目在建構檔案中的宣告內容替換為相應的目錄名稱。
以下是 build.gradle.kts 檔案在移除依附元件前的程式碼片段：
Kotlin
dependencies {
implementation("androidx.core:core-ktx:1.9.0")
}
Groovy
dependencies {
implementation 'androidx.core:core-ktx:1.9.0'
}
下列程式碼片段說明如何在版本目錄檔案中定義依附元件：
[versions]
ktx = "1.9.0"
[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }
為目錄中的依附元件區塊命名時，建議採用烤肉串式命名法 (例如 androidx-ktx)，以便在建構檔案中享有更優異的協助完成程式碼功能。
接著在需要依附元件的各模組中找到 build.gradle.kts 檔案，並在該檔案中定義依附元件，別忘了以 TOML 檔案中定義的名稱做為依據。
Kotlin
dependencies {
implementation(libs.androidx.ktx)
}
Groovy
dependencies {
implementation libs.androidx.ktx
}
遷移外掛程式
在 libs.versions.toml 檔案的版本和外掛程式區段中，為每個外掛程式都新增一個項目。接著同步處理專案，然後在建構檔案的 plugins{} 區塊中，將以上項目的宣告內容替換為相應的目錄名稱。
以下是 build.gradle.kts 檔案在移除外掛程式前的程式碼片段：
Kotlin
// Top-level `build.gradle.kts` file
plugins {
id("com.android.application") version "7.4.1" apply false
}
// Module-level `build.gradle.kts` file
plugins {
id("com.android.application")
}
Groovy
// Top-level `build.gradle` file
plugins {
id 'com.android.application' version '7.4.1' apply false
}
// Module-level `build.gradle` file
plugins {
id 'com.android.application'
}
下列程式碼片段說明如何在版本目錄檔案中定義外掛程式：
[versions]
androidGradlePlugin = "7.4.1"
[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }
和依附元件一樣，設定 plugins 區塊目錄項目的格式時，建議採用烤肉串式命名法 (例如 android-application)，以便在建構檔案中享有更優異的協助完成程式碼功能。
以下程式碼展示如何在頂層和模組層級的 build.gradle.kts 檔案中定義 com.android.application 外掛程式。請將 alias 用於版本目錄檔案中的外掛程式，id則用於慣例外掛程式這類非版本目錄檔案中的外掛程式。
Kotlin
// Top-level build.gradle.kts
plugins {
alias(libs.plugins.android.application) apply false
}
// module build.gradle.kts
plugins {
alias(libs.plugins.android.application)
}
Groovy
// Top-level build.gradle
plugins {
alias libs.plugins.android.application apply false
}
// module build.gradle
plugins {
alias libs.plugins.android.application
}
瞭解詳情
如要進一步瞭解設定版本目錄的其他方式，請參閱下列資源：
- 版本目錄 TOML 檔案格式：列有設定目錄檔案的其他方式。
- Now in Android：這是使用版本目錄的範例應用程式。
已知問題
Gradle 版本目錄仍處於開發階段。如要進一步瞭解系統尚未支援哪些功能，請參閱已知問題和限制。