การอัปเดต API ปลั๊กอิน Android Gradle

หน้านี้จะติดตามการเลิกใช้งานและการนำ API ของปลั๊กอิน Android Gradle (AGP) ออก รวมถึงให้ข้อมูลเกี่ยวกับวิธีอัปเดตโค้ดของคุณตามความเหมาะสม

เครื่องมือติดตามการเลิกใช้งานและการนำ API ออก

ตารางต่อไปนี้สรุปการเลิกใช้งานและนํา API ของ AGP ออกตามเวอร์ชัน AGP

API	เลิกใช้งานในเวอร์ชัน AGP แล้ว	นําออกจากเวอร์ชัน AGP แล้ว
Component.setAsmFramesComputationMode	7.2
Component.transformClassesWith	7.2
RenderScript	7.2
เปลี่ยนรูปแบบ	7.2	8.0

AGP 8.8

การอัปเดต API ที่สําคัญสําหรับ AGP 8.8 มีดังนี้

เลิกใช้งานการกําหนดค่าทรัพยากรแล้ว

การกำหนดค่าทรัพยากรเลิกใช้งานแล้วใน AGP 8.8 การดำเนินการนี้เกิดขึ้นเนื่องจาก AGP ไม่รองรับความหนาแน่นของทรัพยากรที่แตกต่างกันอีกต่อไป และตอนนี้ Google Play Console กําหนดให้ต้องเผยแพร่แอปเป็น App Bundle สําหรับการกําหนดค่าภาษา คุณสามารถระบุภาษาที่แอปรองรับได้โดยใช้ localeFilters DSL เพื่อจับคู่การกําหนดค่าภาษากับทรัพยากรที่เกี่ยวข้อง

AGP 8.0

การอัปเดต API ที่สําคัญสําหรับ AGP 8.0 มีดังนี้

นํา Transform API ออกแล้ว

ตั้งแต่ AGP 8.0 เป็นต้นไป ระบบจะนำ Transform API ออก ซึ่งหมายความว่าระบบจะนำคลาสทั้งหมดในแพ็กเกจ com.android.build.api.transform ออก

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

Replacement APIs

ไม่มี API ใดมาแทนที่ Transform API โดยตรง แต่มี API ใหม่ที่มุ่งเน้นแต่ละ Use Case API ทั้งหมดที่จะแทนที่อยู่ในบล็อก androidComponents {} API เหล่านี้พร้อมใช้งานทั้งหมดใน AGP 7.2

การรองรับการเปลี่ยนรูปแบบไบต์โค้ด

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

การรองรับการเพิ่มคลาสที่สร้างขึ้นลงในแอป

หากต้องการเพิ่มคลาสที่สร้างขึ้นเพิ่มเติมลงในแอป ให้ใช้ Artifacts API กับ MultipleArtifact.ALL_CLASSES_DIRS กล่าวโดยละเอียดคือ ให้ใช้

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

ด้วย MultipleArtifact.ALL_CLASSES_DIRS เพื่อเพิ่มไดเรกทอรีที่สร้างขึ้นเพิ่มเติมลงในคลาสโปรเจ็กต์ Artifacts API จะเลือกตำแหน่งที่ไม่ซ้ำกันโดยอัตโนมัติสำหรับเอาต์พุตของงานที่กำหนดเอง ดูตัวอย่างวิธีใช้ API นี้ได้จาก สูตร addToAllClasses

รองรับการเปลี่ยนรูปแบบตามการวิเคราะห์ทั้งโปรแกรม

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

หากต้องการลงทะเบียนงานที่เปลี่ยนรูปแบบคลาสทั้งหมดพร้อมกัน ปลั๊กอิน Android Gradle 7.4 ได้เปิดตัว API Artifacts.forScope หากต้องการเปลี่ยนรูปแบบชั้นเรียนทั้งหมดในโปรเจ็กต์ปัจจุบัน ให้ใช้ Artifacts.forScope.PROJECT หากต้องการเปลี่ยนรูปแบบคลาสทั้งหมดในโปรเจ็กต์ปัจจุบัน โปรเจ็กต์ที่นำเข้า และไลบรารีภายนอกทั้งหมด ให้ใช้ Artifacts.forScope.ALL โค้ดต่อไปนี้แสดงวิธีใช้ Artifacts.forScope.ALL เพื่อลงทะเบียนงานที่เปลี่ยนรูปแบบคลาสทั้งหมดพร้อมกัน

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

ดูตัวอย่างวิธีใช้ API นี้จาก modifyProjectClasses recipe และดูตัวอย่างวิธีลงทะเบียนส่วนขยายที่กำหนดเองในประเภทบิลด์ Android จาก customizeAgpDsl recipe

หากกรณีการใช้งานของคุณไม่ครอบคลุมโดย API ของ AndroidComponents โปรดรายงานข้อบกพร่อง

ปลั๊กอินที่ใช้กันโดยทั่วไปหลายรายการได้ย้ายข้อมูลไปใช้ API ใหม่เหล่านี้แล้ว ซึ่งรวมถึงปลั๊กอินการตรวจสอบประสิทธิภาพ Firebase (1.4.1 เข้ากันได้กับ AGP 8.0) และปลั๊กอิน Hilt Gradle (2.40.1 เข้ากันได้กับ AGP 8.0) นอกจากนี้ เครื่องมือช่วยอัปเกรด AGP ยังจะช่วยนักพัฒนาโปรเจ็กต์อัปเกรดปลั๊กอินที่ใช้กันโดยทั่วไปตามความจำเป็นด้วย

หากคุณใช้ Transform API ผ่านปลั๊กอินของบุคคลที่สาม โปรดแจ้งให้นักพัฒนาซอฟต์แวร์ทราบว่าจะต้องอัปเดตปลั๊กอินให้ใช้งานกับ API ใหม่สําหรับ AGP 8.0 ได้

AGP 7.2

การอัปเดต API ที่สําคัญสําหรับ AGP 7.2 มีดังนี้

เลิกใช้งาน RenderScript แล้ว

ตั้งแต่ AGP 7.2 เป็นต้นไป เราจะเลิกใช้งาน RenderScript API ชิ้นงานเหล่านี้จะยังคงทํางานต่อไป แต่จะแสดงคําเตือนและจะถูกนําออกอย่างสมบูรณ์ใน AGP เวอร์ชันต่อๆ ไป ดูคําแนะนําเกี่ยวกับวิธีเลิกใช้ RenderScript ได้ที่หัวข้อย้ายข้อมูลจาก RenderScript

Component.transformClassesWith และ Component.setAsmFramesComputationMode เลิกใช้งานแล้ว

ตั้งแต่ AGP 7.2 เป็นต้นไป เราจะเลิกใช้งาน API เครื่องมือวัดผลไบต์โค้ดของคลาส Component.transformClassesWith และ Component.setAsmFramesComputationMode เราได้ย้าย API ดังกล่าวไปยังบล็อกใหม่ Component.instrumentation ซึ่งมี API ทั้งหมดที่เกี่ยวข้องกับการกำหนดค่ากระบวนการเครื่องมือวัด หากต้องการใช้ฟีเจอร์เครื่องมือวัดเหล่านี้ต่อไป ให้ใช้ API ที่เกี่ยวข้องในบล็อกใหม่แทน ตามที่แสดงในข้อมูลโค้ดต่อไปนี้

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }