Android Gradle 外掛程式 API 更新

本頁面會追蹤 Android Gradle 外掛程式 (AGP) API 的淘汰與移除情形,並提供如何更新相應程式碼的資訊。

API 淘汰與移除追蹤工具

下表以 AGP 版本為準,簡要列出 AGP 的 API 淘汰和移除時的影響。

API 已從 AGP 版本淘汰 已從 AGP 版本移除
Component.setAsmFramesComputationMode 7.2
Component.transformClassesWith 7.2
RenderScript 7.2
轉換 7.2 8.0

AGP 8.0

以下是 AGP 8.0 的重要 API 更新。

Transform API 已移除

從 AGP 8.0 開始,不再有Transform API。也就是說,com.android.build.api.transform 套件中所有類別都會遭到移除。

移除 Transform API 是為了提升建構效能。使用 Transform API 的專案會強制將 AGP 用於最佳化效果不充分的建構流程,進而在建構時間產生大型迴歸問題。使用 Transform API 並與其他 Gradle 功能結合使用也相當困難;替換的 API 可讓您在不導入效能或建構正確性問題的情況下,輕鬆擴充 AGP。

替代 API

Transform API 無法完全取代;每種用途都有新的目標 API。所有替換 API 都位於 androidComponents {} 區塊中。上述 API 均可由 AGP 7.2 使用。

支援轉換位元碼

如要轉換位元碼,請使用 檢測 API。以程式庫來說,您只能註冊本機專案類別的檢測;針對應用程式和測試,您則可以選擇只註冊本機類別或所有類別,包括本機和遠端依附元件。如要使用這個 API,檢測作業在每個類別獨立執行,且僅具備類別路徑中其他類別的有限存取權 (詳情請參閱 createClassVisitor())。這項限制可改善完整和漸進式建構作業的效能,並讓 API 途徑保持簡單。每個程式庫在準備就緒後就會平行檢測,而非所有編譯完成後。此外,單一類別的變更代表只有受影響的類別才必須以漸進式建構方式進行重新檢測。如需檢測 API 的使用範例,請參閱使用 ASM 轉換類別 AGP 方案。

支援將產生的類別新增至應用程式

如要將其他產生的類別新增至應用程式,請搭配使用 Artifacts API 和 MultipleArtifact.ALL_CLASSES_DIRS。具體來說,請使用

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

MultipleArtifact.ALL_CLASSES_DIRS 將已產生的其他目錄附加至專案類別。成果 API 會自動選取獨特位置,以便輸出自訂工作。如需此 API 的使用範例,請參閱 addToAllClasses 方案

支援以完整程式分析為基礎的轉換作業

如要根據整個程式分析實作轉換作業,所有類別都可以在單一工作中一起轉換。您應謹慎使用這個方法,因為建構效能成本比使用檢測 API 高得多。如果您的外掛程式使用這個 API,建議您為各個建構類型選擇採用轉換功能,讓應用程式開發人員能夠將其停用以進行開發建構。以下程式碼示範如何註冊可一同轉換所有類別的工作。

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

搭配 MultipleArtifact.ALL_CLASSES_DIRSMultipleArtifact.ALL_CLASSES_JARS 使用,可將所有必要的輸入和輸出連接到自訂工作。關於 Android 建構類型,如需如何使用這個 API 的範例,請參閱 ModifyAllClasses 方案;如需如何註冊自訂擴充功能的範例,請參閱 customizeAgpDsl 方案

如果您的用途不適用於任何 AndroidComponents API,請回報錯誤

有些常用的外掛程式已遷移完畢,可用於使用這些新的 API,包括 Firebase Performance Monitoring 外掛程式 (1.4.1 與 AGP 8.0 相容),以及 Hilt Gradle 外掛程式 (2.40.1 與 AGP 8.0 相容)。AGP 升級輔助程式也可協助專案開發人員視需要升級常用的外掛程式。

如果您透過第三方外掛程式使用 Transform API,請通知作者其外掛程式必須更新,才能搭配 AGP 8.0 適用的新版 API。

AGP 7.2

以下是 AGP 7.2 的重要 API 更新。

RenderScript 已淘汰

自 AGP 7.2 開始,已淘汰 RenderScript API。這些函式仍會繼續運作,但會叫用警示,並於日後的 AGP 版本中完全移除。如要瞭解如何從 RenderScript 轉換,請參閱「從 RenderScript 遷移」(Migrate from RenderScript)

Component.transformClassesWith」和「Component.setAsmFramesComputationMode」已淘汰

自 AGP 7.2 開始,類別位元碼檢測工具 API Component.transformClassesWithComponent.setAsmFramesComputationMode 已被淘汰。他們已移至新的區塊 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
          )
      })
  }