为什么要迁移?
现在是时候从使用Android支持库迁移到AndroidX。这背后有四个原因:
- Android支持库已不在维护更新。28.0.0 是Android支持名称空间的最新版本,并且不再维护该名称空间。因此,如果您想要以前在支持库中获得的错误修复或新功能,则需要迁移到AndroidX。
- 更好的包装管理。使用AndroidX,您可以获得标准化和独立的版本控制,以及更好的标准化命名和更频繁的发行。
- 其他库已迁移为使用AndroidX名称空间库,包括Google Play服务,Firebase,Butterknife,Mockito 2和SQLDelight等。
- 所有新的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 工件和类的正确映射:
4. API 参考文档
有关 androidx
命名空间中的所有软件包和类,请参阅 AndroidX 参考文档部分。