เขียนปลั๊กอิน Gradle

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

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

วงจรการใช้งาน AGP API

AGP ทำตามวงจรฟีเจอร์ของ Gradle เพื่อกำหนดสถานะของ API ดังนี้

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

นโยบายการเลิกใช้งาน

AGP กำลังพัฒนาไปพร้อมกับการเลิกใช้งาน API เก่าและ การแทนที่ด้วย API ใหม่ที่เสถียรและ Domain Specific Language (DSL) ใหม่ การเปลี่ยนแปลงนี้จะครอบคลุม AGP หลายรุ่น และคุณสามารถดูข้อมูลเพิ่มเติมได้ ที่ไทม์ไลน์การย้ายข้อมูล AGP API/DSL

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

หากต้องการดูตัวอย่าง API ใหม่ที่ใช้ในการปรับแต่งบิลด์ทั่วไป โปรดดูสูตรปลั๊กอิน Android Gradle โดยจะแสดงตัวอย่างการปรับแต่งบิลด์ที่พบบ่อย นอกจากนี้ คุณยังดูรายละเอียดเพิ่มเติมเกี่ยวกับ API ใหม่ได้ในเอกสารอ้างอิง

ข้อมูลพื้นฐานเกี่ยวกับการสร้าง Gradle

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

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

อภิธานศัพท์ประเภท Lazy ของ Gradle

Gradle มีหลายประเภทที่ทำงานแบบ "เลื่อนเวลา" หรือช่วยเลื่อนการคำนวณที่ซับซ้อนหรือTask การสร้างไปยังระยะต่อๆ ไปของการสร้าง ประเภทเหล่านี้เป็นหัวใจสำคัญของ API ของ Gradle และ AGP หลายรายการ รายการต่อไปนี้มีประเภท Gradle หลักๆ ที่เกี่ยวข้อง ในการดำเนินการแบบเลื่อนเวลาและเมธอดหลักของประเภทเหล่านั้น

Provider<T>

ระบุค่าประเภท T (โดยที่ "T" หมายถึงประเภทใดก็ได้) ซึ่งอ่านได้ ในระยะการดำเนินการโดยใช้ get() หรือแปลงเป็น Provider<S> ใหม่ (โดยที่ "S" หมายถึงประเภทอื่นๆ) โดยใช้วิธี map(), flatMap() และ zip() โปรดทราบว่าไม่ควรเรียกใช้ get() ในระหว่างขั้นตอนการกำหนดค่า

map(): รับ Lambda และสร้าง Provider ประเภท S, Provider<S> อาร์กิวเมนต์ lambda ของ map() รับค่า T และสร้างค่า S Lambda จะไม่ทำงานทันที แต่จะเลื่อนการทำงาน ไปจนกว่าจะมีการเรียกใช้ get() ใน Provider<S> ที่ได้ ซึ่งทำให้ทั้งเชนทำงานแบบเลื่อนเวลา
flatMap(): รับ Lambda และสร้าง Provider<S> ได้เช่นกัน แต่ Lambda จะรับค่า T และสร้าง Provider<S> (แทนที่จะสร้างค่า S โดยตรง) ใช้ flatMap() เมื่อไม่สามารถกำหนด S ได้ในเวลา กำหนดค่า และคุณรับได้เฉพาะ Provider<S> ในทางปฏิบัติ หากคุณใช้ map() และได้ผลลัพธ์เป็นประเภท Provider<Provider<S>> นั่นอาจหมายความว่าคุณควรใช้ flatMap() แทน
zip(): ช่วยให้คุณรวมอินสแตนซ์ Provider 2 รายการเพื่อสร้าง Provider ใหม่ โดยมีค่าที่คำนวณโดยใช้ฟังก์ชันที่รวมค่าจากอินสแตนซ์ Providers 2 รายการที่ป้อน

Property<T>

ใช้ Provider<T> จึงให้ค่าประเภท T ด้วย คุณยังตั้งค่าสำหรับ Property<T> ได้ด้วย ซึ่งต่างจาก Provider<T> ที่เป็นแบบอ่านอย่างเดียว ซึ่งทำได้ 2 วิธีดังนี้

ตั้งค่าประเภท T โดยตรงเมื่อพร้อมใช้งานโดยไม่ต้อง ใช้การคำนวณที่เลื่อนออกไป
ตั้งค่า Provider<T> อื่นเป็นแหล่งที่มาของค่า Property<T> ในกรณีนี้ ค่า T จะแสดงเมื่อมีการเรียกใช้ Property.get() เท่านั้น

TaskProvider

ใช้งาน Provider<Task> หากต้องการสร้าง TaskProvider ให้ใช้ tasks.register() แทน tasks.create() เพื่อให้มั่นใจว่าระบบจะสร้างอินสแตนซ์ของงานแบบเลื่อนเวลาเมื่อจำเป็นเท่านั้น คุณใช้ flatMap() เพื่อเข้าถึงเอาต์พุตของ Task ก่อนที่จะสร้าง Task ได้ ซึ่งอาจเป็นประโยชน์หากคุณต้องการใช้ เอาต์พุตเป็นอินพุตไปยังอินสแตนซ์ Task อื่นๆ

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

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

ต่อไปนี้เป็นตัวอย่างการลงทะเบียนงาน 2 รายการ ได้แก่ GitVersionTask และ ManifestProducerTask ขณะที่เลื่อนการสร้างอินสแตนซ์ Task จนกว่าจะ จำเป็นต้องใช้จริง ระบบจะตั้งค่าอินพุต ManifestProducerTask เป็น a Provider ที่ได้จากเอาต์พุตของ GitVersionTask ดังนั้น ManifestProducerTask จึงขึ้นอยู่กับ GitVersionTask โดยนัย

// Register a task lazily to get its TaskProvider.
val gitVersionProvider: TaskProvider =
    project.tasks.register("gitVersionProvider", GitVersionTask::class.java) {
        it.gitVersionOutputFile.set(
            File(project.buildDir, "intermediates/gitVersionProvider/output")
        )
    }

...

/**
 * Register another task in the configuration block (also executed lazily,
 * only if the task is required).
 */
val manifestProducer =
    project.tasks.register(variant.name + "ManifestProducer", ManifestProducerTask::class.java) {
        /**
         * Connect this task's input (gitInfoFile) to the output of
         * gitVersionProvider.
         */
        it.gitInfoFile.set(gitVersionProvider.flatMap(GitVersionTask::gitVersionOutputFile))
    }

ระบบจะเรียกใช้งาน 2 งานนี้ก็ต่อเมื่อมีการขออย่างชัดเจนเท่านั้น ซึ่งอาจเกิดขึ้นเป็นส่วนหนึ่งของการเรียกใช้ Gradle เช่น หากคุณเรียกใช้ ./gradlew debugManifestProducer หรือหากเอาต์พุตของ ManifestProducerTask เชื่อมต่อกับงานอื่นและค่าของเอาต์พุตนั้นกลายเป็นค่าที่จำเป็น

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

ขั้นตอนการบิลด์ Gradle

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

หากต้องการใช้การเพิ่มประสิทธิภาพบางอย่างเหล่านี้ สคริปต์และปลั๊กอิน Gradle ต้องปฏิบัติตามกฎที่เข้มงวดในแต่ละขั้นตอนการสร้าง Gradle ที่แตกต่างกัน ได้แก่ การเริ่มต้น การกำหนดค่า และการดำเนินการ ในคู่มือนี้ เราจะมุ่งเน้นไปที่ ขั้นตอนการกำหนดค่าและการดำเนินการ ดูข้อมูลเพิ่มเติมเกี่ยวกับทุกขั้นตอนได้ในคู่มือวงจรการสร้าง Gradle

ระยะการกำหนดค่า

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

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

ระยะการดำเนินการ

ในระยะการดำเนินการ ระบบจะดำเนินการกับงานที่ขอและงานที่ขึ้นอยู่กับงานนั้น กล่าวคือ ระบบจะเรียกใช้เมธอดของคลาส Task ที่ทำเครื่องหมายด้วย @TaskAction ในระหว่างการดำเนินการงาน คุณจะได้รับอนุญาตให้อ่านจากอินพุต (เช่น ไฟล์) และแก้ไขผู้ให้บริการแบบเลซีโดยการเรียก Provider<T>.get() การแก้ไข Lazy Provider ด้วยวิธีนี้จะเริ่มลำดับการเรียก map() หรือ flatMap() ที่เป็นไปตามข้อมูลทรัพยากร Dependency ของงานที่อยู่ใน Provider ระบบจะเรียกใช้งาน งานแบบเลื่อนเวลาเพื่อสร้างค่าที่จำเป็น

API ของตัวแปร อาร์ติแฟกต์ และงาน

Variant API เป็นกลไกการขยายในปลั๊กอิน Android Gradle ที่ช่วยให้คุณ จัดการตัวเลือกต่างๆ ซึ่งโดยปกติจะตั้งค่าโดยใช้ DSL ในไฟล์ การกำหนดค่าบิลด์ที่มีผลต่อบิลด์ Android นอกจากนี้ Variant API ยังให้สิทธิ์เข้าถึงอาร์ติแฟกต์ระดับกลางและขั้นสุดท้ายที่สร้างขึ้นโดยการบิลด์ เช่น ไฟล์คลาส, ไฟล์ Manifest ที่ผสานแล้ว หรือไฟล์ APK/AAB

ขั้นตอนการสร้าง Android และจุดขยาย

เมื่อโต้ตอบกับ AGP ให้ใช้จุดขยายที่สร้างขึ้นมาเป็นพิเศษแทน การลงทะเบียนการเรียกกลับวงจรการทำงานของ Gradle ทั่วไป (เช่น afterEvaluate()) หรือ การตั้งค่าการขึ้นต่อกันของ Task ที่ชัดเจน งานที่ AGP สร้างขึ้นถือเป็น รายละเอียดการติดตั้งใช้งานและไม่ได้เปิดเผยเป็น API สาธารณะ คุณต้องหลีกเลี่ยง การพยายามรับอินสแตนซ์ของออบเจ็กต์ Task หรือการคาดเดาชื่อ Task และ การเพิ่มการเรียกกลับหรือการอ้างอิงไปยังออบเจ็กต์ Task เหล่านั้นโดยตรง

AGP จะทำตามขั้นตอนต่อไปนี้เพื่อสร้างและเรียกใช้อินสแตนซ์ Task ซึ่งจะสร้างอาร์ติแฟกต์บิลด์ ขั้นตอนหลักที่เกี่ยวข้องกับการสร้างออบเจ็กต์ Variant จะตามด้วย Callback ที่ช่วยให้คุณทำการเปลี่ยนแปลงออบเจ็กต์บางอย่าง ที่สร้างขึ้นเป็นส่วนหนึ่งของบิลด์ได้ โปรดทราบว่าการเรียกกลับทั้งหมดจะเกิดขึ้นในขั้นตอนการกำหนดค่า (อธิบายไว้ในหน้านี้) และต้องทำงานอย่างรวดเร็ว โดยเลื่อนงานที่ซับซ้อนไปทำในอินสแตนซ์ Task ที่เหมาะสมในขั้นตอนการดำเนินการแทน

การแยกวิเคราะห์ DSL: ขั้นตอนนี้จะเกิดขึ้นเมื่อมีการประเมินสคริปต์บิลด์ และเมื่อมีการสร้าง และตั้งค่าพร็อพเพอร์ตี้ต่างๆ ของออบเจ็กต์ Android DSL จากบล็อก android ระบบจะลงทะเบียนการเรียกกลับของ Variant API ที่อธิบายไว้ในส่วนต่อไปนี้ในระหว่างขั้นตอนนี้ด้วย
finalizeDsl(): การเรียกกลับที่ช่วยให้คุณเปลี่ยนออบเจ็กต์ DSL ก่อนที่จะ ล็อกเพื่อสร้างคอมโพเนนต์ (ตัวแปร) VariantBuilder จะสร้างออบเจ็กต์ ตามข้อมูลที่มีอยู่ในออบเจ็กต์ DSL
การล็อก DSL: ตอนนี้ DSL ล็อกอยู่และเปลี่ยนแปลงไม่ได้อีกต่อไป
beforeVariants(): การเรียกกลับนี้สามารถส่งผลต่อคอมโพเนนต์ที่จะสร้าง และพร็อพเพอร์ตี้บางอย่างของคอมโพเนนต์ผ่าน VariantBuilder แต่ยังคงอนุญาตให้แก้ไขโฟลว์การสร้างและอาร์ติแฟกต์ที่สร้างขึ้น
การสร้างรูปแบบ: รายการคอมโพเนนต์และอาร์ติแฟกต์ที่จะสร้างเสร็จสมบูรณ์แล้วและไม่สามารถเปลี่ยนแปลงได้
onVariants(): ในการเรียกกลับนี้ คุณจะได้รับสิทธิ์เข้าถึงออบเจ็กต์ Variant ที่สร้างขึ้น และสามารถตั้งค่าหรือผู้ให้บริการสำหรับค่า Property ที่ออบเจ็กต์เหล่านั้นมีอยู่ เพื่อให้ระบบคำนวณค่าแบบเลื่อนเวลา
การล็อกตัวแปร: ตอนนี้ออบเจ็กต์ตัวแปรจะล็อกไว้และไม่สามารถเปลี่ยนแปลงได้อีก
งานที่สร้างขึ้น: ระบบจะใช้ออบเจ็กต์ Variant และค่า Property ของออบเจ็กต์เหล่านั้นเพื่อสร้างอินสแตนซ์ Task ที่จำเป็นต่อการสร้างบิลด์

AGP ขอแนะนำ AndroidComponentsExtension ที่ช่วยให้ คุณลงทะเบียนการเรียกกลับสำหรับ finalizeDsl(), beforeVariants() และ onVariants() ได้ ส่วนขยายนี้พร้อมให้ใช้งานในสคริปต์บิลด์ผ่านบล็อก androidComponents ดังนี้

// This is used only for configuring the Android build through DSL.
android { ... }

// The androidComponents block is separate from the DSL.
androidComponents {
   finalizeDsl { extension ->
      ...
   }
}

อย่างไรก็ตาม เราขอแนะนำให้ใช้สคริปต์บิลด์สำหรับการกำหนดค่าแบบประกาศเท่านั้นโดยใช้ DSL ของบล็อก Android และย้ายตรรกะแบบคำสั่งที่กำหนดเองไปยัง buildSrc หรือปลั๊กอินภายนอก นอกจากนี้ คุณยังดูbuildSrc ตัวอย่างในที่เก็บ GitHub ของสูตร Gradle เพื่อดูวิธีสร้างปลั๊กอินในโปรเจ็กต์ได้ด้วย ตัวอย่างการลงทะเบียนการเรียกกลับจากโค้ดปลั๊กอินมีดังนี้

abstract class ExamplePlugin: Plugin<Project> {

    override fun apply(project: Project) {
        val androidComponents = project.extensions.getByType(AndroidComponentsExtension::class.java)
        androidComponents.finalizeDsl { extension ->
            ...
        }
    }
}

มาดูรายละเอียดของฟังก์ชันเรียกกลับที่มีอยู่และประเภทกรณีการใช้งาน ที่ปลั๊กอินรองรับในแต่ละฟังก์ชันกัน

`finalizeDsl(callback: (DslExtensionT) -> Unit)`

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

abstract class ExamplePlugin: Plugin<Project> {

    override fun apply(project: Project) {
        val androidComponents = project.extensions.getByType(AndroidComponentsExtension::class.java)
        androidComponents.finalizeDsl { extension ->
            extension.buildTypes.create("extra").let {
                it.isJniDebuggable = true
            }
        }
    }
}

`beforeVariants()`

ในขั้นตอนนี้ของการบิลด์ คุณจะได้รับสิทธิ์เข้าถึงออบเจ็กต์ VariantBuilder ซึ่งกำหนดตัวแปรที่จะสร้างและพร็อพเพอร์ตี้ของตัวแปรเหล่านั้น เช่น คุณสามารถปิดใช้รูปแบบบางอย่าง การทดสอบ หรือเปลี่ยนค่าของพร็อพเพอร์ตี้ (เช่น minSdk) โดยอัตโนมัติสำหรับรูปแบบที่เลือกเท่านั้น คล้ายกับ finalizeDsl() ค่าทั้งหมดที่คุณระบุต้องได้รับการแก้ไขในเวลาที่กำหนดค่า และไม่ขึ้นอยู่กับอินพุตภายนอก VariantBuilder ต้องไม่ได้รับการแก้ไขเมื่อการเรียกกลับ beforeVariants() เสร็จสิ้น

androidComponents {
    beforeVariants { variantBuilder ->
        variantBuilder.minSdk = 23
    }
}

beforeVariants() Callback จะรับ VariantSelector โดยไม่บังคับ ซึ่งคุณจะรับได้ผ่านเมธอด selector() ใน androidComponentsExtension คุณสามารถใช้เพื่อกรองคอมโพเนนต์ที่เข้าร่วมการเรียกใช้ Callback ตามชื่อ ประเภทบิลด์ หรือเวอร์ชันผลิตภัณฑ์

androidComponents {
    beforeVariants(selector().withName("adfree")) { variantBuilder ->
        variantBuilder.minSdk = 23
    }
}

`onVariants()`

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

// onVariants also supports VariantSelectors:
onVariants(selector().withBuildType("release")) { variant ->
    // Gather the output when we are in single mode (no multi-apk).
    val mainOutput = variant.outputs.single { it.outputType == OutputType.SINGLE }

    // Create version code generating task
    val versionCodeTask = project.tasks.register("computeVersionCodeFor${variant.name}", VersionCodeTask::class.java) {
        it.outputFile.set(project.layout.buildDirectory.file("${variant.name}/versionCode.txt"))
    }
    /**
     * Wire version code from the task output.
     * map() will create a lazy provider that:
     * 1. Runs just before the consumer(s), ensuring that the producer
     * (VersionCodeTask) has run and therefore the file is created.
     * 2. Contains task dependency information so that the consumer(s) run after
     * the producer.
     */
    mainOutput.versionCode.set(versionCodeTask.map { it.outputFile.get().asFile.readText().toInt() })
}

มีส่วนร่วมในแหล่งข้อมูลที่สร้างขึ้นในการสร้าง

ปลั๊กอินของคุณสามารถมีส่วนร่วมกับแหล่งที่มาที่สร้างขึ้นได้ 2-3 ประเภท เช่น

โค้ดของแอปพลิเคชันในไดเรกทอรี java
ทรัพยากร Android ในไดเรกทอรี res
แหล่งข้อมูล Java ในไดเรกทอรี resources
ชิ้นงาน Android ในไดเรกทอรี assets

ดูรายการแหล่งที่มาทั้งหมดที่คุณเพิ่มได้ที่ API ของแหล่งที่มา

ข้อมูลโค้ดนี้แสดงวิธีเพิ่มโฟลเดอร์แหล่งที่มาที่กำหนดเองชื่อ ${variant.name} ลงในชุดซอร์สของ Java โดยใช้ฟังก์ชัน addStaticSourceDirectory() จากนั้น Toolchain ของ Android จะประมวลผลโฟลเดอร์นี้

onVariants { variant ->
    variant.sources.java?.let { java ->
        java.addStaticSourceDirectory("custom/src/kotlin/${variant.name}")
    }
}

ดูรายละเอียดเพิ่มเติมได้ที่สูตร addJavaSource

ข้อมูลโค้ดนี้แสดงวิธีเพิ่มไดเรกทอรีที่มีทรัพยากร Android ที่สร้างจากงานที่กำหนดเองไปยังชุดซอร์ส res โดยกระบวนการจะคล้ายกันสำหรับ แหล่งที่มาประเภทอื่นๆ

onVariants(selector().withBuildType("release")) { variant ->
    // Step 1. Register the task.
    val resCreationTask =
       project.tasks.register<ResCreatorTask>("create${variant.name}Res")

    // Step 2. Register the task output to the variant-generated source directory.
    variant.sources.res?.addGeneratedSourceDirectory(
       resCreationTask,
       ResCreatorTask::outputDirectory)
    }

...

// Step 3. Define the task.
abstract class ResCreatorTask: DefaultTask() {
   @get:OutputFiles
   abstract val outputDirectory: DirectoryProperty

   @TaskAction
   fun taskAction() {
      // Step 4. Generate your resources.
      ...
   }
}

ดูรายละเอียดเพิ่มเติมได้ที่สูตรการเพิ่มชิ้นงานที่กำหนดเอง

เข้าถึงและแก้ไขอาร์ติแฟกต์

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

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

Cardinality

Cardinality ของ Artifact แสดงถึงจำนวนอินสแตนซ์ของ FileSystemLocation หรือจำนวนไฟล์หรือไดเรกทอรีของประเภทอาร์ติแฟกต์ คุณดูข้อมูลเกี่ยวกับคาร์ดินาลิตีของอาร์ติแฟกต์ได้โดยตรวจสอบคลาสหลักของอาร์ติแฟกต์นั้น อาร์ติแฟกต์ที่มี FileSystemLocation เดียวจะเป็นคลาสย่อยของ Artifact.Single ส่วนอาร์ติแฟกต์ที่มีอินสแตนซ์ FileSystemLocation หลายรายการจะเป็น คลาสย่อยของ Artifact.Multiple

ประเภท `FileSystemLocation`

คุณตรวจสอบได้ว่า Artifact แสดงถึงไฟล์หรือไดเรกทอรีโดยดูที่FileSystemLocationประเภทที่มีพารามิเตอร์ ซึ่งอาจเป็น RegularFile หรือ Directory

การดำเนินการที่รองรับ

Artifact คลาสทุกคลาสสามารถใช้หนึ่งในอินเทอร์เฟซต่อไปนี้เพื่อระบุการดำเนินการที่รองรับ

Transformable: อนุญาตให้ใช้ Artifact เป็นอินพุตไปยัง Task ที่ ทำการเปลี่ยนรูปแบบที่กำหนดเองกับอินพุตนั้น และเอาต์พุตเป็น Artifact เวอร์ชันใหม่
Appendable: ใช้กับอาร์ติแฟกต์ที่เป็นคลาสย่อยของ Artifact.Multiple เท่านั้น ซึ่งหมายความว่าสามารถต่อท้าย Artifact ได้ นั่นคือ Task ที่กำหนดเองสามารถสร้างอินสแตนซ์ใหม่ของประเภท Artifact นี้ ซึ่งจะเพิ่มลงในรายการที่มีอยู่
Replaceable: ใช้กับอาร์ติแฟกต์ที่เป็นคลาสย่อยของ Artifact.Single เท่านั้น Artifact ที่แทนที่ได้จะแทนที่ด้วยอินสแตนซ์ใหม่ทั้งหมด ซึ่งสร้างขึ้นเป็นเอาต์พุตของ Task

นอกจากการดำเนินการแก้ไขอาร์ติแฟกต์ 3 รายการแล้ว อาร์ติแฟกต์ทุกรายการยังรองรับการดำเนินการ get() (หรือ getAll()) ซึ่งจะแสดงผล Provider ที่มีอาร์ติแฟกต์เวอร์ชันสุดท้าย (หลังจากดำเนินการทั้งหมดกับอาร์ติแฟกต์เสร็จสิ้น)

ปลั๊กอินหลายรายการสามารถเพิ่มการดำเนินการจำนวนเท่าใดก็ได้ในอาร์ติแฟกต์ลงในไปป์ไลน์ จากonVariants()การเรียกกลับ และ AGP จะตรวจสอบว่ามีการเชื่อมโยงอย่างถูกต้อง เพื่อให้งานทั้งหมดทำงานในเวลาที่เหมาะสม และมีการสร้างและ อัปเดตอาร์ติแฟกต์อย่างถูกต้อง ซึ่งหมายความว่าเมื่อการดำเนินการเปลี่ยนเอาต์พุตโดยการต่อท้าย แทนที่ หรือแปลง การดำเนินการถัดไปจะเห็นอัปเดต ของอาร์ติแฟกต์เหล่านี้เป็นอินพุต และอื่นๆ

จุดแรกเข้าในการลงทะเบียนการดำเนินการคือคลาส Artifacts ข้อมูลโค้ดต่อไปนี้แสดงวิธีรับสิทธิ์เข้าถึงอินสแตนซ์ของ Artifacts จากพร็อพเพอร์ตี้ในออบเจ็กต์ Variant ในแฮนเดิล onVariants()

จากนั้นคุณจะส่ง TaskProvider ที่กำหนดเองเพื่อรับออบเจ็กต์ TaskBasedOperation (1) และใช้เพื่อเชื่อมต่ออินพุตและเอาต์พุตโดยใช้วิธีใดวิธีหนึ่งของ wiredWith* (2) ได้

วิธีการที่แน่นอนที่คุณต้องเลือกจะขึ้นอยู่กับจำนวนคาร์ดินาลิตีและ FileSystemLocationประเภทที่Artifactที่คุณต้องการเปลี่ยนรูปใช้

และสุดท้าย คุณจะส่งArtifactประเภทไปยังเมธอดที่แสดงการดำเนินการที่เลือกในออบเจ็กต์ *OperationRequest ที่คุณได้รับกลับมา เช่น toAppendTo() toTransform() หรือ toCreate() (3)

androidComponents.onVariants { variant ->
    val manifestUpdater = // Custom task that will be used for the transform.
            project.tasks.register(variant.name + "ManifestUpdater", ManifestTransformerTask::class.java) {
                it.gitInfoFile.set(gitVersionProvider.flatMap(GitVersionTask::gitVersionOutputFile))
            }
    // (1) Register the TaskProvider w.
    val variant.artifacts.use(manifestUpdater)
         // (2) Connect the input and output files.
        .wiredWithFiles(
            ManifestTransformerTask::mergedManifest,
            ManifestTransformerTask::updatedManifest)
        // (3) Indicate the artifact and operation type.
        .toTransform(SingleArtifact.MERGED_MANIFEST)
}

ในตัวอย่างนี้ MERGED_MANIFEST คือ SingleArtifact และเป็น RegularFile ด้วยเหตุนี้ เราจึงต้องใช้วิธี wiredWithFiles ซึ่ง ยอมรับการอ้างอิง RegularFileProperty รายการเดียวสำหรับอินพุต และ RegularFileProperty รายการเดียวสำหรับเอาต์พุต นอกจากนี้ยังมีwiredWith*เมธอดอื่นๆ ในคลาส TaskBasedOperation ที่ใช้ได้กับชุดค่าผสมอื่นๆ ของArtifact คาร์ดินาลิตีและประเภท FileSystemLocation

หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการขยาย AGP เราขอแนะนำให้อ่านส่วนต่อไปนี้ จากคู่มือระบบบิลด์ Gradle