了解 Android API 级别

Xamarin.Android 有多个 Android API 级别设置,用于确定应用与多个版本的 Android 的兼容性。 本指南介绍这些设置的含义、如何配置这些设置,以及这些设置对应用运行时的影响。

快速入门

Xamarin.Android 公开三个 Android API 级别的项目设置:

  • 目标 框架 - 指定在生成应用程序时使用的框架。 Xamarin.Android在编译时会使用此 API 级别。

  • 最低 Android 版本 – 指定希望应用支持的最旧的 Android 版本。 此 API 级别由 Android 运行时使用。

  • 目标 Android 版本 – 指定要运行应用的 Android 版本。 此 API 级别由 Android 运行时使用。

必须先安装该 API 级别的 SDK 平台组件,然后才能为项目配置 API 级别。 有关下载和安装组件Android SDK,请参阅 Android SDK 安装程序

注意

从 2020 年 8 月开始,Google Play 控制台要求新应用面向 Android 10.0 (29 或更高版本) API 级别。 从 2020 年 11 月开始,现有应用需要面向 API 级别 29 或更高版本。 有关详细信息,请参阅 Play 控制台文档中的"创建和设置应用"中的 Play 控制台的目标 API 级别要求。

通常,所有三个 Xamarin.Android API 级别都设置为相同的值。 在"应用程序"页上,将"使用 Android 版本 (目标框架) 进行编译"设置为最新的稳定 API 版本 (,或者至少设置为 Android 版本,该版本具有所需的所有) 。 在下面的屏幕截图中,目标框架设置为 Android 7.1 (API 级别 25 - Nougat) :

目标框架版本默认为使用 Android 版本进行编译

"Android 清单"页上,将"最低 Android 版本"设置为"使用 SDK 编译"版本,将"目标 Android 版本"设置为与以下屏幕截图中的目标框架版本 (相同的值,"目标 Android Framework"设置为 Android 7.1 (Nougat) ) :

将

如果要保持与早期版本的 Android 的向后兼容性,请设置"最低 Android 版本",以面向希望应用支持的最早 Android 版本。 (请注意,API 级别 14 是应用程序服务和 Firebase支持 .Google Play所需的最低 API ) 以下示例配置支持从 API 级别 14 到 API 级别 25 的 Android 版本:

使用 API 级别 25 Nougat 进行编译,最低 Android 版本设置为 API 级别 14

如果应用支持多个 Android 版本,则代码必须包含运行时检查,以确保应用使用"最低 Android 版本"设置 (请参阅下面的 Android 版本的运行时检查,了解) 。 如果使用或创建库,请参阅下面的 API 级别和库,了解为库配置 API 级别设置时最佳做法。

Android 版本和 API 级别

随着 Android 平台的发展和新的 Android 版本发布,每个 Android 版本都分配有一个唯一的整数标识符,称为 API 级别。 因此,每个 Android 版本对应于单个 Android API 级别。 由于用户在较旧版本和最新版本的 Android 上安装应用,因此实际 Android 应用必须设计为使用多个 Android API 级别。

Android 版本

每个 Android 版本都有多个名称:

  • Android 版本,例如 Android 9.0
  • 一个 (或) 名称的代码,例如 Pie
  • 相应的 API 级别,例如 API 级别 28

Android 代码名称可能对应于多个版本和 API 级别 (如下表所示,) 每个 Android 版本只对应一个 API 级别。

此外,Xamarin.Android 定义 映射到 当前已知 Android API 级别的生成版本代码。 下表可帮助你在 API 级别、Android 版本、代码名称和 Xamarin.Android 生成版本代码之间转换 (版本代码在命名空间中 Android.OS) :

名称 版本 API 级别 Released(已释放) 生成版本代码
Q 10.0 29 2020 年 8 月 BuildVersionCodes.Q
Pie 9.0 28 2018 年 8 月 BuildVersionCodes.P
Oreo 8.1 27 2017 年 12 月 BuildVersionCodes.OMr1
Oreo 8.0 26 2017 年 8 月 BuildVersionCodes.O
Nougat 7.1 25 2016 年 12 月 BuildVersionCodes.NMr1
Nougat 7.0 24 2016 年 8 月 BuildVersionCodes.N
Marshmallow 6.0 23 Aug 2015 BuildVersionCodes.M
Lollipop 5.1 22 Mar 2015 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 2014 年 11 月 BuildVersionCodes.Lollipop
Kitkat 监视 4.4W 20 2014 年 6 月 BuildVersionCodes.KitKatWatch
Kitkat 4.4 19 2013 年 10 月 BuildVersionCodes.KitKat
Jelly Bean 4.3 18 2013 年 7 月 BuildVersionCodes.JellyBeanMr2
Jelly Bean 4.2-4.2.2 17 2012 年 11 月 BuildVersionCodes.JellyBeanMr1
Jelly Bean 4.1-4.1.1 16 2012 年 6 月 BuildVersionCodes.JellyBean
冰淇淋三明治 4.0.3-4.0.4 15 2011 年 12 月 BuildVersionCodes.IceCreamSandwichMr1
冰淇淋三明治 4.0-4.0.2 14 2011 年 10 月 BuildVersionCodes.IceCreamSandwich
蜂窝 3.2 13 2011 年 6 月 BuildVersionCodes.HoneyCombMr2
蜂窝 3.1.x 12 2011 年 5 月 BuildVersionCodes.HoneyCombMr1
蜂窝 3.0.x 11 2011 年 2 月 BuildVersionCodes.HoneyComb
姜 饼 2.3.3-2.3.4 10 2011 年 2 月 BuildVersionCodes.GingerBreadMr1
姜 饼 2.3-2.3.2 9 2010 年 11 月 BuildVersionCodes.GingerBread
Froyo 2.2.x 8 2010 年 6 月 BuildVersionCodes.Froyo
Eclair 2.1.x 7 2010 年 1 月 BuildVersionCodes.EclairMr1
Eclair 2.0.1 6 2009 年 12 月 BuildVersionCodes.Eclair01
Eclair 2.0 5 2009 年 11 月 BuildVersionCodes.Eclair
圆环图 1.6 4 2009 年 9 月 BuildVersionCodes.Donut
蛋糕 1.5 3 2009 年 5 月 BuildVersionCodes.Cupcake
基本 1.1 2 2009 年 2 月 BuildVersionCodes.Base11
基本 1.0 1 2008 年 10 月 BuildVersionCodes.Base

如下表所示,新的 Android 版本经常发布 - 有时每年发布多个版本。 因此,可能运行应用的 Android 设备包括各种较旧和较新的 Android 版本。 如何保证应用在许多不同的 Android 版本上一致且可靠地运行? Android 的 API 级别可帮助你管理此问题。

Android API 级别

每个 Android 设备在一 API 级别运行 – 每个 Android 平台版本保证此 API 级别是唯一的。 API 级别精确标识应用可以调用的 API 集的版本;它标识作为开发人员编码的清单元素、权限等的组合。 Android 的 API 级别系统可帮助 Android 在设备上安装应用程序之前确定应用程序是否与 Android 系统映像兼容。

生成应用程序时,它包含以下 API 级别信息:

  • 生成应用以运行的目标 Android API 级别。

  • Android设备运行应用所需的最低 Android API 级别。

这些设置用于确保在安装时 Android 设备上提供正确运行应用所需的功能。 如果没有,则阻止应用在该设备上运行。 例如,如果 Android 设备的 API 级别低于为应用指定的最低 API 级别,则 Android 设备将阻止用户安装应用。

Project API 级别设置

以下部分说明如何使用 SDK 管理器 为要面向的 API 级别准备开发环境,然后详细说明如何在 Xamarin.Android 中配置目标 框架、最低 Android版本 和目标 Android 版本 设置。

Android SDK平台

在 Xamarin.Android 中选择目标或最低 API 级别之前,必须安装Android SDK API 级别对应的平台版本。 "目标框架"、"最低 Android 版本"和"目标 Android 版本"的可用选项Android SDK安装的版本范围。 可以使用 SDK 管理器 来验证是否安装了Android SDK版本,并使用它来添加应用所需的任何新 API 级别。 如果你不熟悉如何安装 API 级别,请参阅 Android SDK 安装程序

目标 Framework

目标框架 (也称为 ) 是特定 Android FRAMEWORK 版本 (API 级别) 在生成时编译应用。 此设置指定应用程序在运行时 预期 使用的 api,但它不会影响在安装应用程序时实际可使用的 api。 因此,更改目标框架设置不会更改运行时行为。

目标框架标识应用程序链接到的库版本–此设置确定可在应用中使用的 Api。 例如,如果要使用 Android 5.0 棒糖形中引入的 NotificationBuilder. SetCategory 方法,则必须将目标框架设置为 API 级别 21 (棒糖形) 或更高版本。 如果将项目的目标框架设置为 API 级别(如 Api 级别19) (KitKat) 并尝试 在代码中调用该方法,则会出现编译错误。

建议始终使用 最新 的可用目标框架版本进行编译。 这样做会为你的代码所调用的任何已弃用的 Api 提供有用的警告消息。 使用最新的支持库版本时,使用最新的目标 Framework 版本尤为重要,即每个库都希望在支持库的最小 API 级别或更高版本上编译应用。

若要访问 Visual Studio 中的 "目标框架" 设置,请在解决方案资源管理器中打开项目属性,然后选择 "应用程序" 页:

项目属性的应用程序页

设置目标框架,方法是在 " 使用 Android 版本编译 " 下的下拉菜单中选择一个 API 级别,如下所示。

最低 Android 版本

最低 android 版本 (也称为 ) 是最早版本的 android OS (即,可以安装和运行应用程序) 最低的 API 级别。 默认情况下,应用只能安装在匹配目标框架设置或更高版本的设备上;如果 "最低 Android 版本" 设置 低于 " 目标框架" 设置,你的应用也可以在早期版本的 Android 上运行。 例如,如果将 "目标框架" 设置为 " android 7.1 (Nougat") 并将 "最低 android 版本" 设置为 " Android 4.0.3 (冰淇淋三明治) ",则可以将应用安装在 API 级别15到 api 级别为25(含)的任何平台上。

虽然你的应用程序可能会在此范围的平台上成功生成并安装,但这并不能保证在所有这些平台上都能成功 运行 。 例如,如果你的应用安装在 android 5.0 (棒糖形) 上,并且你的代码调用仅在 Android 7.1 (Nougat) 和更高版本中提供的 API,你的应用程序将会收到运行时错误,可能会崩溃。 因此,你的代码必须确保在运行时,它只调用运行它的 Android 设备所支持的 Api。 换句话说,你的代码必须包括显式运行时检查,以确保你的应用程序仅在最新的设备上使用较新的 Api 以支持它们。 本指南后面的针对 Android 版本的运行时检查介绍了如何将这些运行时检查添加到你的代码中。

若要在 Visual Studio 中访问 "最低 Android 版本" 设置,请在解决方案资源管理器中打开项目属性,然后选择 " Android 清单" 页。 在 " 最低 android 版本 " 下的下拉菜单中,可以选择应用程序的最低 android 版本:

最小 Android 目标选项设置为使用 SDK 版本进行编译

如果选择 " 使用 SDK 版本的编译",则最低 Android 版本将与目标框架设置相同。

目标 Android 版本

目标 Android 版本 (也称为 ) 是应用预期运行的 ANDROID 设备的 API 级别。 Android 使用此设置来确定是否启用任何兼容行为–这可确保应用继续按预期方式工作。 Android 使用您的应用程序的 "目标 Android 版本" 设置来确定哪些行为更改可以应用于您的应用程序,而不会中断应用程序 (这是 Android 如何提供向前兼容性) 。

目标框架和目标 Android 版本虽然具有非常相似的名称,但并不相同。 目标框架设置将目标 API 级别信息传递给 Xamarin 以便在 编译时使用,而目标 Android 版本将目标 api 级别信息传递到 android 以在 运行时 使用 (在) 设备上安装并运行该应用时。

若要在 Visual Studio 中访问此设置,请在解决方案资源管理器中打开项目属性,然后选择 " Android 清单" 页。 在 " 目标 android 版本 " 下的下拉菜单中,可以选择应用程序的目标 Android 版本:

目标 Android 版本设置为使用 SDK 版本进行编译

建议你将目标 Android 版本显式设置为你用来测试应用程序的最新版本的 Android。 理想情况下,它应设置为最新的 Android SDK 版本–这使你可以在处理行为更改之前使用新 Api。 对于大多数开发人员,我们 建议将目标 Android 版本设置为 使用 SDK 版本的编译

通常,目标 Android 版本应受最低 Android 版本和目标框架的限制。 即:

最低 Android 版本 = 目标 Android 版本 < = 目标框架

有关 SDK 级别的详细信息,请参阅 Android 开发人员 使用-SDK 文档。

Android 版本的运行时检查

发布每个新版本的 Android 时,会更新框架 API 以提供新功能或替代功能。 在少数例外情况下,早期 Android 版本中的 API 功能将在不进行修改的情况下转发到较新的 Android 版本。 因此,如果你的应用程序在特定的 Android API 级别上运行,则该应用程序通常能够在更高版本的 Android API 级别上运行而无需修改。 但如果你还想要在较早版本的 Android 上运行你的应用,该怎么办?

如果选择的最低 Android 版本低于 " 目标框架" 设置,则在运行时应用程序可能无法使用某些 api。 但是,你的应用程序仍然可以在以前的设备上运行,但功能会降低。 对于与最低 Android 版本设置相对应的 Android 平台上不可用的每个 API,你的代码必须显式检查属性的值, Android.OS.Build.VERSION.SdkInt 以确定运行应用的平台的 API 级别。 如果 API 级别低于支持 你想要调用的 Api 的最低 Android 版本,则你的代码必须找出一种正确工作方式,而无需进行此 api 调用。

例如,假设我们想要在android 5.0 棒糖 (和更) 高版本上运行时,使用SetCategory方法对通知进行分类,但我们仍希望应用程序在早期版本的 android 上运行,例如android 4.1 Jelly Bean (其中 ,) 不可用。 参考本指南开头的 Android 版本表,可以看到 android 5.0 棒糖形 的生成版本代码是 。 为了支持较早版本的 Android (在中不可 SetCategory 用),我们的代码可以在运行时检测到 api 级别,并 SetCategory 仅在 API 级别大于或等于棒糖版本代码时进行条件调用:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

在此示例中,我们的应用程序的目标框架设置为 android 5.0 (Api 级别 21) 并且其最低 android 版本设置为 ANDROID 4.1 (API level 16) 。 由于 SetCategory 在 api 级别 Android.OS.BuildVersionCodes.Lollipop 和更高版本中可用,因此此示例代码 SetCategory 仅在实际可用时才会调用SetCategorySetCategory 当 API 级别为16、17、18、19或20时,它不会尝试调用。 此功能在早期的 Android 版本中减少了,但通知未正确排序 (因为未按类型) 分类,但仍会发布通知以提醒用户。 应用仍可正常工作,但其功能略有降低。

通常情况下,生成版本检查可帮助代码在运行时决定是否在新的方式与旧方法之间执行操作。 例如:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

如果在旧的 Android 版本(缺少一个或多个 Api)上运行,则不能通过快速且简单的规则来减少或修改应用程序的功能。 在某些情况下 (如上面的 SetCategory 示例所示) ,当 API 调用不可用时,可以将其省略。 但在其他情况下,如果 Android.OS.Build.VERSION.SdkInt 检测到的时间小于应用程序提供其最佳体验所需的 API 级别,则可能需要实现替代功能。

API 级别和库

创建 Xamarin 类库项目 (例如类库或绑定库) 时,你只能配置目标框架设置–最低 Android 版本和目标 Android 版本设置不可用。 这是因为没有 Android 清单 页:

只有

最小 Android 版本和目标 Android 版本设置不可用,因为生成的库不是独立应用程序-库可以在任何 Android 版本上运行,具体取决于打包时使用的应用程序。 您可以指定如何 编译库,但无法预测库将运行的平台 API 级别。 考虑到这一点,在使用或创建库时应遵循以下最佳做法:

  • 使用 android 库时 –如果要在应用程序中使用 android 库,请确保将应用程序的 "目标框架" 设置设为至少与库的 "目标框架" 设置 相同 的 API 级别。

  • 创建 android 库时 –如果要创建一个 android 库供其他应用程序使用,请确保将其 "目标框架" 设置设置为编译所需的最小 API 级别。

建议使用这些最佳做法来帮助防止库尝试调用在运行时不可用的 API (这可能会导致应用崩溃) 。 如果你是库开发人员,应尽量将 API 调用的使用限制为整个 API 图面面积的一小部分且已建立良好的子集。 这样做有助于确保库可在更广泛的 Android 版本中安全地使用。

总结

本指南介绍了如何使用 Android API 级别来管理不同版本的 Android 的应用兼容性。 它提供了配置 Xamarin.Android 目标框架最低 Android版本 和目标 Android 版本项目设置的详细 步骤。 其中介绍了如何使用 Android SDK 管理器 安装 SDK 包,包括有关如何编写代码以在运行时处理不同 API 级别的示例,并说明了在创建或使用 Android 库时如何管理 API 级别。 它还提供了一个综合列表,将 API 级别与 Android 版本号 (例如 Android 4.4) 、Android 版本名称 (例如 Kitkat) 和 Xamarin.Android 生成版本代码关联。