กําหนดค่าตัวแปรสื่อเผยแพร่

ตัวแปรของสื่อเผยแพร่ช่วยให้คุณสร้างประสบการณ์การใช้งานที่ปรับแต่งได้มากขึ้นสำหรับผู้ใช้ การกำหนดค่าตัวแปรการเผยแพร่ช่วยให้คุณเผยแพร่ตัวแปรบิลด์ต่างๆ ได้ โดยแต่ละตัวแปรจะมีแอตทริบิวต์ของตัวเอง

การเผยแพร่ตัวแปรบิลด์หลายรายการของไลบรารีช่วยให้ผู้ใช้เลือกฟีเจอร์ที่เหมาะสมกับความต้องการของตนได้ เช่น คุณสามารถเผยแพร่อาร์ติแฟกต์ที่แตกต่างกันสำหรับประเภทบิลด์แก้ไขข้อบกพร่องเทียบกับบิลด์ที่เผยแพร่ อาร์ติแฟกต์การเผยแพร่การแก้ไขข้อบกพร่องอาจมีโค้ดการบันทึกเพิ่มเติมและการขึ้นต่อกันที่แตกต่างกันเพื่อเปิดใช้การบันทึกเพิ่มเติมนี้

โปรดตรวจสอบว่าคุณได้เตรียมคลังสำหรับการเผยแพร่แล้วก่อนดำเนินการต่อ

ใช้ข้อมูลเมตาของโมดูล Gradle

หากต้องการเผยแพร่ตัวแปรของไลบรารี คุณต้องใช้ข้อมูลเมตาของโมดูล Gradle (GMM) GMM จะอธิบายการเผยแพร่และรักษาการจัดการทรัพยากร Dependency ที่รับรู้ตัวแปร ระบบจะเผยแพร่ GMM พร้อมกับคลังของคุณโดยค่าเริ่มต้น

ประโยชน์ของการใช้ GMM มีดังนี้

  • หากใช้ GMM กับ Gradle 6.0 ขึ้นไป คุณจะเผยแพร่ตัวแปรการเผยแพร่หลายรายการหรืออาร์ติแฟกต์หลายรายการได้ โดยแต่ละรายการจะมีแอตทริบิวต์และการขึ้นต่อกันของตัวเอง หากใช้ไฟล์ POM ของ Maven แทน GMM คุณจะเผยแพร่อาร์ติแฟกต์ได้เพียงรายการเดียว หากใช้ไฟล์ POM คุณจะเผยแพร่อาร์ติแฟกต์เพิ่มเติมได้โดยใช้ตัวแยกประเภท แต่อาร์ติแฟกต์เพิ่มเติมจะไม่มีทรัพยากร Dependency ของตนเอง
  • Gradle จะสร้างตัวแปร 1 รายการสำหรับการคอมไพล์และ 1 รายการสำหรับรันไทม์โดยอัตโนมัติ โดยแต่ละรายการจะมีการขึ้นต่อกันของตัวเอง คุณอาจเผยแพร่ตัวแปรหนึ่งสำหรับการคอมไพล์และอีกตัวแปรหนึ่งสำหรับรันไทม์ เพื่อให้ผู้บริโภคเลือกได้ตามเวลาที่ใช้ไลบรารีของคุณ GMM ช่วยให้ผู้บริโภคเห็นทรัพยากร Dependency ต่างๆ สำหรับการคอมไพล์และรันไทม์ โดยอิงตามการใช้งาน api, implementation หรือ compileOnly/runtimeOnly ของไลบรารีที่เผยแพร่ ดูรายการทรัพยากร Dependency ทั้งหมดได้ที่การกำหนดค่าทรัพยากร Dependency ซึ่งจะใช้ได้แม้ว่าคุณจะเผยแพร่ตัวแปรสื่อเผยแพร่เพียงรายการเดียวก็ตาม
  • เมื่อใช้ฟิกซ์เจอร์ทดสอบ คุณสามารถเผยแพร่ตัวแปรเพิ่มเติมที่มีข้อมูลเมตาหรือความสามารถพิเศษที่ช่วยให้ผู้บริโภคเลือกตัวแปรดังกล่าวได้ ซึ่งจะใช้ได้แม้ว่าคุณจะเผยแพร่ตัวแปรการเผยแพร่รายการเดียวก็ตาม

ทำความเข้าใจตัวแปรของสื่อเผยแพร่

หากต้องการทำความเข้าใจวิธีการทำงานของตัวแปรการเผยแพร่ คุณควรทำความคุ้นเคยกับขั้นตอนการเผยแพร่พื้นฐานของ Gradle แนวคิดหลักบางประการเกี่ยวกับสื่อเผยแพร่มีดังนี้

  • ตัวแปรบิลด์: การกำหนดค่าที่ Gradle ใช้เพื่อสร้างไลบรารี ซึ่งเป็นผลคูณไขว้ของประเภทบิลด์และเวอร์ชันผลิตภัณฑ์ ดูข้อมูลเพิ่มเติมได้ที่อภิธานศัพท์เกี่ยวกับบิลด์ของ Android
  • อาร์ติแฟกต์: ไฟล์หรือไดเรกทอรีที่บิลด์สร้างขึ้น ในบริบทของการเผยแพร่ไลบรารี อาร์ติแฟกต์มักจะเป็นไฟล์ JAR หรือ AAR
  • ตัวแปรการเผยแพร่: อาร์ติแฟกต์ที่มีแอตทริบิวต์ ฟีเจอร์ และทรัพยากร Dependency ที่เกี่ยวข้อง โปรดทราบว่า Gradle เรียกตัวแปรการเผยแพร่ว่าตัวแปร อย่างไรก็ตาม ในเอกสารเหล่านี้จะเรียกว่าตัวแปรการเผยแพร่เพื่อแยกความแตกต่างจากตัวแปรบิลด์
  • แอตทริบิวต์: Gradle ใช้แอตทริบิวต์เพื่อระบุและเลือกตัวแปรการเผยแพร่เมื่อมีหลายตัวเลือก เช่น org.gradle.usage=java-api และ org.gradle.jvm.version=11 เป็นแอตทริบิวต์รายละเอียดปลีกย่อย
  • คอมโพเนนต์ซอฟต์แวร์: ออบเจ็กต์ Gradle ที่มีตัวแปรการเผยแพร่ได้ตั้งแต่ 1 รายการขึ้นไป และเผยแพร่ไปยังพิกัด Maven ชุดเดียว (groupId:artifactId:version) โดยจะแสดงใน DSL ของ Gradle ผ่าน Project.getComponents()
  • Publication: สิ่งที่เผยแพร่ไปยังที่เก็บและผู้บริโภคใช้ Publications ประกอบด้วยคอมโพเนนต์ซอฟต์แวร์ 1 รายการและข้อมูลเมตาของคอมโพเนนต์นั้น เช่น ข้อมูลประจำตัว (groupId:artifactId:version)

ปลั๊กอิน Android Gradle (AGP) 7.1 เปิดตัวภาษาเฉพาะโดเมน (DSL) เพื่อควบคุมว่าจะใช้ตัวแปรบิลด์ใดในระหว่างการเผยแพร่และจะละเว้นตัวแปรใด DSL ช่วยให้คุณสร้างอินสแตนซ์ของ SoftwareComponent ที่มีสิ่งใดสิ่งหนึ่งต่อไปนี้ได้

  • ตัวแปรการเผยแพร่ 1 รายการจากตัวแปรบิลด์ 1 รายการ
  • ตัวแปรการเผยแพร่หลายรายการจากตัวแปรบิลด์หลายรายการ

เมื่อสร้างคอมโพเนนต์ซอฟต์แวร์ที่มีตัวแปรการเผยแพร่หลายรายการ AGP จะตั้งค่าแอตทริบิวต์ในตัวแปรแต่ละรายการเพื่อให้ผู้ใช้เลือกตัวแปรที่เหมาะสมตามต้องการได้ แอตทริบิวต์เหล่านี้มาจากประเภทบิลด์และ Flavor ที่ใช้สร้างตัวแปรบิลด์โดยตรง การสร้างคอมโพเนนต์ที่มีตัวแปรสิ่งพิมพ์รายการเดียวไม่จำเป็นต้องใช้แอตทริบิวต์เนื่องจากไม่จำเป็นต้องแยกความแตกต่าง

สร้างคอมโพเนนต์ซอฟต์แวร์ที่มีตัวแปรการเผยแพร่รายการเดียว

ข้อมูลโค้ดต่อไปนี้จะกำหนดค่าคอมโพเนนต์ซอฟต์แวร์ที่มีตัวแปรการเผยแพร่รายการเดียวที่สร้างจากตัวแปรบิลด์ release และเพิ่ม JAR ต้นทางเป็นอาร์ติแฟกต์รอง

Kotlin

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

ดึงดูด

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

คุณสามารถสร้างคอมโพเนนต์ได้หลายรายการ โดยแต่ละรายการจะมีตัวแปรการเผยแพร่รายการเดียว และเผยแพร่ภายใต้พิกัด Maven ที่แตกต่างกัน ในกรณีนี้ ระบบจะไม่ตั้งค่าแอตทริบิวต์ในตัวแปรของสื่อเผยแพร่ คุณไม่สามารถบอกได้ว่าตัวแปรการเผยแพร่นี้มาจากตัวแปรบิลด์ release โดยดูจากข้อมูลเมตาของการเผยแพร่ เนื่องจากมีตัวแปรสิ่งพิมพ์ที่เกี่ยวข้องเพียงรายการเดียว จึงไม่จำเป็นต้องแก้ความกำกวม

สร้างคอมโพเนนต์ซอฟต์แวร์ที่มีตัวแปรการเผยแพร่หลายรายการ

คุณสามารถเลือกตัวแปรบิลด์ทั้งหมดหรือบางส่วนเพื่อใส่ไว้ในคอมโพเนนต์ซอฟต์แวร์เดียว AGP จะใช้ชื่อประเภทบิลด์ ชื่อเวอร์ชันผลิตภัณฑ์ และชื่อมิติข้อมูลของเวอร์ชันผลิตภัณฑ์โดยอัตโนมัติเพื่อสร้างแอตทริบิวต์เพื่อให้โปรเจ็กต์ที่ใช้แยกแยะแอตทริบิวต์เหล่านั้นได้

หากต้องการเผยแพร่ตัวแปรบิลด์ทั้งหมดในคอมโพเนนต์เดียว ให้ระบุ allVariants() ในบล็อก multipleVariants{} ในไฟล์ build.gradle ระดับโมดูล ดังนี้

Kotlin

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

ดึงดูด

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

ซึ่งจะสร้างคอมโพเนนต์เดียวที่ชื่อ default หากต้องการตั้งชื่อคอมโพเนนต์เป็นอย่างอื่น ให้ใช้ multipleVariants({name}) ในกรณีนี้ ระบบจะใช้มิติข้อมูลประเภทบิลด์และเวอร์ชันผลิตภัณฑ์ทั้งหมดเป็นแอตทริบิวต์

นอกจากนี้ คุณยังเลือกตัวแปรที่จะเผยแพร่ได้โดยใช้ includeBuildTypeValues() และ includeFlavorDimensionAndValues() ดังนี้

Kotlin

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) สำหรับประเภทบิลด์, (blue, pink) สำหรับมิติข้อมูล color และ (square) สำหรับมิติข้อมูล shape

คุณต้องระบุมิติข้อมูลของเวอร์ชันทั้งหมด แม้ว่าจะเผยแพร่เพียงค่าเดียวจากมิติข้อมูลก็ตาม เพื่อให้ AGP ทราบว่าควรใช้ค่าใดสำหรับแต่ละมิติข้อมูล

ตารางต่อไปนี้แสดงตัวแปรของสื่อเผยแพร่ที่ได้และแอตทริบิวต์ที่เกี่ยวข้อง

ตัวแปร แอตทริบิวต์
blueSquareDebug com.android.build.api.attributes.BuildTypeAttr="debug" com.android.build.api.attributes.ProductFlavorAttr:color="blue"
blueSquareRelease com.android.build.api.attributes.BuildTypeAttr="release"
com.android.build.api.attributes.ProductFlavorAttr:color="blue"
pinkSquareDebug com.android.build.api.attributes.BuildTypeAttr="debug"
com.android.build.api.attributes.ProductFlavorAttr:color="pink"
pinkSquareRelease com.android.build.api.attributes.BuildTypeAttr="release"
com.android.build.api.attributes.ProductFlavorAttr:color="pink"

ในทางปฏิบัติ ระบบจะเผยแพร่ตัวแปรมากกว่านี้ ตัวอย่างเช่น ตัวแปรแต่ละรายการก่อนหน้านี้จะเผยแพร่ 2 ครั้ง โดยครั้งหนึ่งสำหรับการคอมไพล์และอีกครั้งสำหรับรันไทม์ โดยมีทรัพยากร Dependency ที่แตกต่างกัน (ขึ้นอยู่กับว่าทรัพยากร Dependency ที่ประกาศใช้ implementation หรือ api) และมีค่าที่แตกต่างกันสำหรับแอตทริบิวต์ org.gradle.Usage อย่างไรก็ตาม อาร์ติแฟกต์ (ไฟล์ AAR) ของตัวแปรทั้ง 2 รายการนี้เหมือนกัน

ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบเกี่ยวกับ API ของ publishing

ปัญหาความเข้ากันได้สำหรับการเผยแพร่ไลบรารีหลายเวอร์ชัน

โปรเจ็กต์ที่ใช้ AGP 7.0 หรือต่ำกว่าจะไม่สามารถใช้ไลบรารีหลายเวอร์ชันที่เผยแพร่ด้วย AGP 7.1 ขึ้นไป ปัญหานี้เป็นปัญหาที่ทราบแล้วซึ่งเกิดจากการเปลี่ยนชื่อแอตทริบิวต์สำหรับมิติข้อมูลของเวอร์ชันผลิตภัณฑ์จาก dimensionName เป็น com.android.build.api.attributes.ProductFlavor:dimensionName ใน AGP 7.1 คุณสามารถใช้ missingDimensionStrategy ใน API ตัวแปรเวอร์ชันก่อนหน้าเพื่อแก้ปัญหานี้ได้ ทั้งนี้ขึ้นอยู่กับการตั้งค่าโปรเจ็กต์

ตัวอย่างเช่น สมมติว่าโปรเจ็กต์แอปพลิเคชันของคุณมีเฉพาะมิติข้อมูลของเวอร์ชันผลิตภัณฑ์ "version" ดังนี้

Kotlin

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)
    }
}