Android Gradle 插件 API 更新

此页面跟踪 Android Gradle 插件 (AGP) API 的弃用和移除，并提供有关如何相应更新代码的信息。

API 弃用和移除跟踪器

下表汇总了 AGP API 在 AGP 版本方面何时弃用和移除。

API	在 AGP 版本中弃用	从 AGP 版本中移除
`Component.setAsmFramesComputationMode`	7.2
`Component.transformClassesWith`	7.2
RenderScript	7.2
Transform	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 使用。

支持转换字节码

要转换字节码，请使用 Instrumentation API。对于库，您只能为本地项目类注册 Instrumentation；对于应用和测试，您可以选择仅为本地类或所有类（包括本地和远程依赖项）注册 Instrumentation。要使用此 API，Instrumentation 会独立运行在每个类上，并且对类路径中其他类的访问权限有限（有关更多信息，请参阅 createClassVisitor()）。此限制提高了完整构建和增量构建的性能，并使 API 表面保持简单。每个库在准备好后会立即并行执行 Instrumentation，而不是在所有编译完成后再执行。此外，单个类的更改意味着在增量构建中只需重新执行受影响类的 Instrumentation。有关如何使用 Instrumentation API 的示例，请参阅使用 ASM 转换类 AGP 食谱。

支持将生成的类添加到您的应用

要将其他生成的类添加到应用，请使用 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 引入了 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,
    )

请参阅 modifyProjectClasses 示例，了解如何使用此 API，以及 customizeAgpDsl 示例，了解如何向 Android 构建类型注册自定义扩展。

如果您的用例未被任何 AndroidComponents API 涵盖，请提交错误报告。

一些常用的插件已经迁移到使用这些新 API，包括 Firebase 性能监控插件（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 迁移。

`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
          )
      })
  }