此页面由 Cloud Translation API 翻译。

Android Gradle 插件 API 更新

本页记录了 Android Gradle 插件 (AGP) 废弃和移除情况，并说明了如何相应地更新代码。

API 废弃和移除情况跟踪说明

下表从 AGP 版本方面总结了各个 AGP API 的废弃时间和移除时间。

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 管理中心现在要求应用以 app bundle 的形式发布。对于语言配置，您可以使用 localeFilters DSL 指定应用支持的语言区域，以将语言区域配置映射到相应的资源。

AGP 8.0

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

移除了 Transform API

从 AGP 8.0 开始，Transform API 将被移除。这意味着，软件包 com.android.build.api.transform 中的所有类都会被移除。

Transform API 即将被移除，以提高 build 的性能。使用 Transform API 的项目会强制 AGP 对 build 使用优化程度不够的流程，从而导致构建时间大幅增加。同时也很难使用 Transform API 以及将其与其他 Gradle 功能结合使用；这些替代 API 可让您更轻松地扩展 AGP，而不会引起性能问题或 build 正确性问题。

替代 API

Transform API 没有单一的替代 API，每个用例都会有新的针对性 API。所有替代 API 都位于 androidComponents {} 代码块中，在 AGP 7.2 中均有提供。

支持转换字节码

如需转换字节码，请使用 Instrumentation API。对于库，您只能为本地项目类注册插桩；对于应用和测试，您既可以选择仅为本地类注册插桩，也可以选择为所有类（包括本地和远程依赖项）注册插桩。为了使用此 API，每个类上的插桩都是独立运行的，并且对类路径中其他类的访问会受到限制（如需了解详情，请参见 createClassVisitor()）。此限制提高了完整 build 和增量 build 的性能，并使得 API Surface 变得简单。每个库一旦准备就绪，即会进行并行插桩；而不是在所有编译完成后进行插桩。此外，如果是在单个类中做出更改，则意味着只有受影响的类必须在增量 build 中重新进行插桩。如需查看 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，建议您按 build 类型选择启用转换，以便应用开发者针对开发 build 停用该转换。

为了注册可将所有类一起转换的任务，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 build 类型注册自定义扩展程序的示例，请参阅 customizeAgpDsl 配方。

如果您的用例不在任何 AndroidComponents API 的涵盖范围内，请提交 bug。

一些常用插件已转变为使用这些新 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 迁移。

废弃了 `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
          )
      })
  }