設定發布項目變數

發布項目變數可讓您為使用者打造更貼近個人需求的體驗。 您可以透過設定發布項目變數發布不同的建構變數。 並有各自的屬性

透過發布多個程式庫的建構變數，使用者就能選擇 符合需求的功能舉例來說，您可以用不同的版本 建立 Deployment 偵錯與發布 建構類型偵錯用的發布項目成果可能具有多餘的記錄程式碼和 進而啟用這項額外記錄功能

繼續操作之前，請務必 為程式庫做好發布準備。

使用 Gradle Module Metadata

如要發布程式庫的變化版本，您必須使用 Gradle Module Metadata (GMM)。 GMM 可描述您的出版品並維護 可辨識變化版本的依附元件管理。 根據預設，GMM 會和程式庫一起發布。

使用 GMM 的好處包括：

• 如果您透過 Gradle 6.0 以上版本使用 GMM，就可以發布多個發布項目 變化版本或多個構件 - 每個構件都有專屬的屬性和依附元件。 如果您使用 Maven 的 POM 檔案 除了 GMM 外，您只能發布一個成果。如果使用 POM 檔案，你 可以使用分類器發布其他成果，但額外成果 但不能有專屬的依附元件
• Gradle 會自動建立編譯用和執行階段用的變數 每個物件都有各自的依附元件您可以發布一個編譯用的變數 還有一個用於執行階段，讓取用者根據自己使用 媒體庫GMM 可讓消費者看到編譯和編譯的不同依附元件 根據已發布程式庫的用量計算 api、implementation 或 compileOnly/runtimeOnly。詳情請見 依附元件設定 查看完整的依附元件清單即使您只是發布單曲 發布項目變數。
• 使用測試固件時，您可以另外發布含有特殊測試項目的變化版本 中繼資料或 功能 讓消費者選擇該產品即使您是已發布的 一個發布項目變數。

瞭解發布項目變數

如要瞭解發布項目變數的運作方式，建議你先熟悉 Gradle 基本發布步驟。 以下列舉幾項有關發布的重要概念：

• 建構變數：Gradle 用於建構程式庫的設定。 是建構類型和變種版本的交叉乘積如要進一步瞭解 Android 建構詞彙，請參閱這個部分的說明。
• 成果： 建構所產生的檔案或目錄。在程式庫發布程序中，成果通常是 JAR 或 AAR 檔案。
• 發布項目變數：包含關聯屬性、功能和依附元件的成果。注意事項 Gradle 將發布項目變數稱為「變數」。但這些方法稱為 出版品變數，以便區分 建構變數。
• 屬性： Gradle 會利用屬性來識別及選取發布項目變數 (如果有的話) 提供多種選項舉例來說，org.gradle.usage=java-api 和 org.gradle.jvm.version=11 都是變數屬性。
• 軟體元件： 可保存一或多個發布項目變數且已發布的 Gradle 物件 轉換為一組 Maven 座標 (groupdId:artifactId:version)。是 會在 Gradle 的 DSL 中顯示 Project.getComponents()。
• 出版品： 發布至存放區供取用者使用的內容。出版品包含 可讓您瞭解容器本身 (groupId:artifactId:version)。

Android Gradle 外掛程式 (AGP) 7.1 推出了 網域專屬語言 (DSL)，控管用於建構變數的建構變數 以及忽略哪些出版品DSL 可讓您建立 含有下列任一項目的 SoftwareComponent：

• 單一建構變數中的一個發布項目變數。
• 多個建構變數中的多個發布項目變數。

如果您建立具有多個發布項目變數的軟體元件，AGP 組合 新增每個子類的屬性，讓消費者能選取 合適的變化版本這些屬性皆直接取自版本 和變種版本建立 一個發布項目變數的元件不需要屬性，因為 不需要特別區分

建立只含一個發布項目變數的軟體元件

下列程式碼片段會為軟體元件設定單一出版品 透過 release 建構變數建立的變化版本，並將來源 JAR 新增為 次要構件：

android {
  publishing {
    singleVariant("release") {
        withSourcesJar()
    }
  }
}

android {
  publishing {
    singleVariant('release') {
        withSourcesJar()
    }
  }
}

您可以建立多個元件，每個元件設定單一發布項目變數。 分散在不同 Maven 座標下在本例中 尚未在發布項目變數中設定。你無法分辨這個出版品 變數來自 release 建構變數，方法是查看發布項目 中繼資料。由於只有一個發布項目變數，因此不需要 以便釐清狀況

建立具有多個發布項目變數的軟體元件

您可以選擇將全部或部分的建構變數放入軟體元件。AGP 會自動使用建構類型名稱與變種版本 名稱和變種版本維度名稱來建立屬性 可區分不同的專案

如要發布單一元件中的所有建構變數，請在模組層級 build.gradle 檔案中的 multipleVariants{} 區塊指定 allVariants()：

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

這會建立一個名為「default」的單一元件。如要重新命名元件，請使用 multipleVariants({name})。在這種情況下，所有的建構類型和變種版本維度都會當做屬性使用。

你也可以使用 includeBuildTypeValues() 和 includeFlavorDimensionAndValues()：

android {
  publishing {
    multipleVariants("custom") {
      includeBuildTypeValues("debug", "release")
      includeFlavorDimensionAndValues(
        dimension = "color",
        values = arrayOf("blue", "pink")
      )
        includeFlavorDimensionAndValues(
          dimension = "shape",
          values = arrayOf("square")
      )
    }
  }
}

android {
  publishing {
    multipleVariants('custom') {
      includeBuildTypeValues('debug', 'release')
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'color',
        /*values =*/ 'blue', 'pink'
      )
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'shape',
        /*values =*/ 'square'
      )
    }
  }
}

在以上範例中，自訂元件包含下列程式碼的所有組合：建構類型的 (debug、release)、維度 color 的 (blue、pink) 和維度 shape 的 (square)。

您必須列出所有版本維度，即使您只發布一個值也一樣 ，這樣 AGP 才能知道每個維度要使用的值。

下表列出產生的發布項目變數和 相關的屬性

在實務上會發布更多的變化版本。舉例來說： 每個上述變數都發布兩次，一次用於編譯，另一次則針對 依附元件則不同 (取決於宣告的依附元件 請使用 implementation 或 api)，並為屬性使用不同的值 org.gradle.Usage。不過，這兩個變數的成果 (AAR 檔案) 是相同的。

詳情請參閱 publishing API 說明文件。

發布多變種程式庫時的相容性問題

使用 AGP 7.0 以下版本的專案無法使用已發布的多變種程式庫 搭配 AGP 7.1 以上版本。這是因屬性變更而導致的已知問題 從「dimensionName」到「變種版本」的變種版本維度名稱 AGP 7.1 中的 com.android.build.api.attributes.ProductFlavor:dimensionName。 視專案設定而定，您可以在以下位置使用 missingDimensionStrategy： 舊的變化版本 API 運作 更多相關資訊

舉例來說，假設您的應用程式專案只有版本產品 版本維度：

android {
    applicationVariants.forEach { variant ->
        val flavor = variant.productFlavors[0].name
        val attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        val dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}

android {
    applicationVariants.forEach { variant ->
        def flavor = variant.getProductFlavors()[0].name
        def attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        def dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}