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，建議您為各個建構類型進行轉換，讓應用程式開發人員能夠為開發版本停用這個 API。

為了註冊一項可以同時轉換所有類別的工作，Android Gradle 外掛程式 7.4 導入了 Artifacts.forScope API。如要在目前的專案中轉換所有類別，請使用 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 方案；如需為 Android 建構類型註冊自訂擴充功能的說明範例，請參閱 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.transformClassesWith 和 Component.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
          )
      })
  }