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

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

เครื่องมือติดตามการเลิกใช้งานและการนำ 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 นี้ และสูตร "customizeAgpDsl" เพื่อดูตัวอย่างวิธีลงทะเบียนส่วนขยายที่กำหนดเองกับประเภทบิลด์ของ Android

หากกรณีการใช้งานของคุณไม่ครอบคลุมโดย 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
          )
      })
  }