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.8

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

资源配置已弃用

资源配置已自 AGP 8.8 起弃用。之所以这样做，是因为 AGP 不再支持不同的资源密度，并且 Google Play Console 现在要求将应用发布为应用包。对于语言配置，您可以使用指定您的应用支持的语言环境，使用localeFilters DSL 将语言环境配置映射到相应的资源。

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,
    )

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

如果您的用例未被任何 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 开始，类字节码 instrumentation API Component.transformClassesWith 和 Component.setAsmFramesComputationMode 已弃用。它们已移动到新的代码块 Component.instrumentation 中，其中包含与配置 instrumentation 过程相关的所有 API。要继续使用这些 instrumentation 功能，请改用新代码块中的相应 API，如下面的代码片段所示

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