Android Jetpack 使用 - 项目迁移到 AndroidX

为什么要迁移？

现在是时候从使用Android支持库迁移到AndroidX。这背后有四个原因：

1. Android支持库已不在维护更新。28.0.0 是Android支持名称空间的最新版本，并且不再维护该名称空间。因此，如果您想要以前在支持库中获得的错误修复或新功能，则需要迁移到AndroidX。
2. 更好的包装管理。使用AndroidX，您可以获得标准化和独立的版本控制，以及更好的标准化命名和更频繁的发行。
3. 其他库已迁移为使用AndroidX名称空间库，包括Google Play服务，Firebase，Butterknife，Mockito 2和SQLDelight等。
4. 所有新的Jetpack库都将在AndroidX名称空间中发布。因此，例如，要利用Jetpack Compose或CameraX，您需要迁移到AndroidX命名空间。

 

1. AndroidX 概览

androidx 命名空间中的工件包含 Android Jetpack库。与支持库一样，androidx 命名空间中的库与 Android 平台分开提供，并向后兼容各个 Android 版本。

AndroidX 对原始 Android 支持库进行了重大改进，后者（原始 Android 支持库）现在已不再维护。androidx 软件包完全取代了支持库，不仅提供与支持库同等的功能，而且还提供了新的库。

此外，AndroidX 还包括以下功能：

• AndroidX 中的所有软件包都使用一致的命名空间，以字符串 androidx 开头。支持库软件包已映射到对应的 androidx.* 软件包。

• 与支持库不同，androidx 软件包会单独维护和更新。从版本 1.0.0 开始，androidx 软件包使用严格的版本控制。您可以单独更新项目中的各个 AndroidX 库。

• 版本 28.0.0 是支持库的最后一个版本。我们将不再发布 android.support 库版本。 所有新功能都将在 androidx 命名空间中开发。

 

2. 在项目中使用 androidx 库

要在新项目中使用命名空间为 androidx 的库，就需要将编译 SDK 设置为 Android 9.0（API 级别 28）或更高版本，并在 gradle.properties 文件中将以下两个 Android Gradle 插件标志设置为 true。

android.useAndroidX=true  // 该标志设置为 true 时，Android 插件会使用对应的 AndroidX 库，而非支持库。如果未指定，那么该标志默认为 false。
android.enableJetifier=true // 该标志设置为 true 时，Android 插件会通过重写其二进制文件来自动迁移现有的第三方库，以使用 AndroidX 依赖项。如果未指定，那么该标志默认为 false。

 

下文介绍了如何迁移现有项目到AndroidX：

3. 迁移到 AndroidX

AndroidX 将原始支持库 API 替换为 androidx 命名空间中的软件包。只有软件包和 Maven 工件名称发生了变化；类名、方法名和字段名没有变化。

⚠️  建议在单独的分支中执行迁移。此外，还应设法避免在执行迁移时重构代码。

#1. 准备

在开始迁移到AndroidX之前，应该先备份我们的项目。

#2. 前提条件
执行迁移之前，请先将应用更新到最新版本。 我们建议您将项目更新为使用支持库的最终版本：版本 28.0.0。 这是因为，1.0.0 版本的 AndroidX 工件是与支持库 28.0.0 工件等效的二进制文件。

#3. 启用Jetifier 

将更新Java代码，XML资源和Gradle配置，以引用重构的类和Maven工件。

Jetifier帮助迁移第三方依赖项以使用AndroidX。Jetifier将更改这些依赖项的字节码，以使其与使用AndroidX的项目兼容。但是，Jetifier不会更改您的源代码或迁移您生成的代码。

要在您的应用中启用Jetifier，请在gradle.properties文件中添加以下内容：

android.useAndroidX = true
android.enableJetifier = true

现在，当代码自动完成导入库时，您将导入该库的AndroidX版本，而不是旧的支持库版本。

#4. 更新依赖关系

换由Android Gradle插件3.2.0-alpha14自动应用，该重写文件重写了JAR和AAR依赖关系（以及传递性依赖关系）的字节码和资源，以引用新androidx包装的类和工件。

在开始迁移之前，应该将每个第三方库（例如Butterknife，Glide，Mockito 2和SqlDelight）更新到该库的最新版本。否则可能导致无法解释的编译错误。
如果您使用的是代码生成库，Jetifier将不会对其进行修改。因此，您需要检查代码生成库是否与AndroidX兼容。
 

⚠️ 如果您考虑跳过步骤3和4，则可能会遇到一些错误：

• 您使用的第三方代码与AndroidX不兼容。在这种情况下，类似于下面的堆栈跟踪将向您显示它正在尝试获取旧版本的支持库：

  …
  Error : Program type already present: android.support.v4.app.INotificationSideChannel$Stub$Proxy |
  Reason: Program type already present: android.support.v4.app.INotificationSideChannel$Stub$Proxy
  …

   

• 如果您有部分迁移的项目，则可能会收到重复的类错误，该错误试图从支持库和AndroidX提取相同的代码。堆栈跟踪将显示如下内容：

  …
  Duplicate class android.support.v4.app.INotificationSideChannel found in modules classes.jar (androidx.core:core:1.0.0) and classes.jar (com.android.support:support-compat:28.0.0)
  …

   

#5. 更新原始代码

我们有3个选项来更新源代码以使用AndroidX：

• Android Studio  （推荐的方式）
• 手动更新
• Bash脚本

# 使用 Android Studio 迁移现有项目

使用 Android Studio 3.2 及更高版本，您只需从菜单栏中依次选择 Refactor > Migrate to AndroidX，即可将现有项目迁移到 AndroidX。

这是推荐的方式，因为Android Studio可以在重构时检查您的源代码以做出正确的决定。

 

⚠️ 我们在配置时可能会遇到与迁移有关的问题，因为内置的 Android Studio 迁移功能可能并不能完成所有操作。根据您的构建配置，您可能需要手动更新构建脚本和 Proguard 映射。

如果您在一个单独的构建文件中维护依赖项配置，请使用下述映射文件来检查依赖项并将其更新为对应的 AndroidX 软件包，请参考下面这些表来确定从支持库到对应 AndroidX 工件和类的正确映射：

• Maven 工件映射
• 类映射

 

4. API 参考文档

有关 androidx 命名空间中的所有软件包和类，请参阅 AndroidX 参考文档部分。