設定應用程式模組

本頁說明模組層級 build.gradle.kts 檔案中的實用應用程式設定。除了概略瞭解 build.gradle.kts 檔案中設定的重要屬性,您也可以瞭解如何執行下列操作:

  • 變更不同建構設定的應用程式 ID。
  • 根據應用程式 ID 安全地調整命名空間。

設定應用程式 ID

每個 Android 應用程式都有專屬的應用程式 ID,看起來像 Java 或 Kotlin 套件名稱,例如 com.example.myapp。這組 ID 可明確識別裝置和 Google Play 商店中的應用程式。

應用程式 ID 是由模組 build.gradle.kts 檔案中的 applicationId 屬性定義,如下所示。將 com.example.myapp 替換成您的應用程式 ID,即可更新 applicationId 的值:

Kotlin

android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 15
        targetSdk = 24
        versionCode = 1
        versionName = "1.0"
    }
    ...
}

Groovy

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 15
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }
    ...
}

雖然應用程式 ID 看起來類似傳統的 Kotlin 或 Java 套件名稱,但應用程式 ID 的命名規則比較嚴格:

  • 必須包含至少兩個區隔 (一或多個點)。
  • 每個區隔的開頭都必須是英文字母。
  • 所有字元都必須為英數字元或底線 [a-zA-Z0-9_]。

您在 Android Studio 中建立新專案時,系統會自動將 applicationId 指派給您在設定期間所選的套件名稱。您可以從技術上獨立切換這兩項屬性,但我們不建議這麼做。

設定應用程式 ID 時,建議您執行下列操作:

  • 讓應用程式 ID 與命名空間相同。如果這兩項屬性有所差異,可能會令人有點困惑,但只要兩者保持一致,您就不需要擔心。
  • 發布應用程式後,請勿變更應用程式 ID。如果您做出變更,Google Play 商店會將後續上傳資料視為新的應用程式。
  • 明確定義應用程式 ID。如果未使用 applicationId 屬性明確定義應用程式 ID,則系統會自動採用與命名空間相同的值。這表示變更命名空間會變更應用程式 ID,這通常不是您想要的結果。

變更測試用應用程式 ID

根據預設,建構工具會使用指定建構變化版本的應用程式 ID,在檢測設備測試 APK 中套用應用程式 ID,後方加上 .test。舉例來說,com.example.myapp.free 建構變數的測試 APK 的應用程式 ID 為 com.example.myapp.free.test

如要變更應用程式 ID (這應該並非必要),您可以在 defaultConfigproductFlavor 區塊中定義 testApplicationId 屬性。

設定命名空間

每個 Android 模組都有一個命名空間,做為所產生 RBuildConfig 類別的 Kotlin 或 Java 套件名稱。

命名空間是由模組 build.gradle.kts 檔案中的 namespace 屬性定義,如以下程式碼片段所示。namespace 最初會設為您在建立專案時選擇的套件名稱。

Kotlin

android {
    namespace = "com.example.myapp"
    ...
}

Groovy

android {
    namespace "com.example.myapp"
    ...
}

將應用程式建構成最終的應用程式套件 (APK) 時,Android 建構工具會使用命名空間做為應用程式所產生 R 類別的命名空間,該類別的用途是存取應用程式資源。例如,在上述建構檔案中,R 類別是在 com.example.myapp.R 建立。

您為 build.gradle.kts 檔案設定的 namespace 屬性設定的名稱必須與專案的基本套件名稱相同,也就是您的活動和其他應用程式程式碼。您可以在專案中有其他子套件,但這些檔案必須使用 namespace 屬性的命名空間匯入 R 類別。

為了簡化工作流程,請讓命名空間與應用程式 ID 保持相同 (如同預設)。

變更命名空間

在多數情況下,您應保持命名空間和應用程式 ID 相同,如同預設的一樣。不過,如果您打算重新編寫程式碼,或是想要避免命名空間衝突,有時可能需要變更命名空間。

在這些情況下,無論應用程式 ID 為何,您都可以更新模組 build.gradle.kts 檔案中的 namespace 屬性,藉此變更命名空間。在開始之前,請確保已明確定義應用程式 ID,這樣變更命名空間並不會同時變更應用程式 ID。如要進一步瞭解命名空間對應用程式 ID 可能造成的影響,請參閱「設定應用程式 ID」。

如果 namespace 和 Gradle applicationId 的名稱不同,建構工具會在建構作業結束時,將應用程式 ID 複製到應用程式的最終資訊清單檔案中。因此,如果您在建構後檢查 AndroidManifest.xml 檔案,package 屬性會設為應用程式 ID。合併資訊清單的 package 屬性是 Google Play 商店和 Android 平台用來識別您應用程式的位置。

變更測試用的命名空間

androidTesttest 來源集的預設命名空間為主要命名空間,而且會在結尾加上 .test。舉例來說,如果 build.gradle 檔案中的 namespace 屬性為 com.example.myapp,則測試命名空間預設為 com.example.myapp.test。如要變更測試用命名空間,請使用 testNamespace 屬性,如以下程式碼片段所示:

Kotlin

android {
    namespace = "com.example.myapp"
    testNamespace = "com.example.mytestapp"
    ...
}

Groovy

android {
    namespace "com.example.myapp"
    testNamespace "com.example.mytestapp"
    ...
}

注意:請勿將 testNamespacenamespace 設為相同的值,否則命名空間會發生衝突。

如要進一步瞭解測試,請參閱「在 Android 上測試應用程式」一文。