Google Play 使用在应用清单中声明的 <uses-sdk>
属性,从不符合其平台版本要求的设备中筛选您的应用。在设置这些属性之前,请确保您了解 Google Play 过滤器。
- 语法
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- 包含在
<manifest>
- 说明
可让您通过 API 级别整数来表达应用与一个或多个 Android 平台版本的兼容性。应用表达的 API 级别会与给定 Android 系统的 API 级别进行比较,后者在不同的 Android 设备上可能有所不同。
尽管其名称如此,但此元素用于指定 API 级别,而非软件开发套件 (SDK) 或 Android 平台的版本号。API 级别始终是一个单独的整数。您无法从关联的 Android 版本号推导出 API 级别。例如,它与主版本或主版本和次版本之和不同。
另请阅读关于应用版本控制的文档。
- 属性
-
android:minSdkVersion
- 一个整数,用于指定应用运行所需的最低 API 级别。如果系统的 API 级别低于此属性中指定的值,Android 系统会阻止用户安装该应用。请务必声明此属性。
注意:如果您未声明此属性,系统会假定默认值为“1”,这表示您的应用与所有 Android 版本兼容。如果不是这样,并且您未声明正确的
minSdkVersion
,那么当应用安装在 API 级别不兼容的系统上时,尝试访问不可用的 API 会导致应用在运行时崩溃。因此,请务必在minSdkVersion
属性中声明适当的 API 级别。 android:targetSdkVersion
- 一个整数,用于指定应用的目标 API 级别。如果未设置,默认值与
minSdkVersion
给定的值相同。此属性告知系统您已针对目标版本进行了测试,系统不会启用任何兼容性行为来保持您的应用与目标版本的前向兼容性。应用仍可以在较低版本上运行(最低可到
minSdkVersion
)。随着 Android 的每个新版本不断演进,某些行为甚至外观可能会发生变化。但是,如果平台的 API 级别高于您的应用
targetSdkVersion
声明的版本,系统可以启用兼容性行为,以便您的应用继续按预期方式运行。您可以通过将targetSdkVersion
指定为与应用运行所在平台的 API 级别匹配来停用此类兼容性行为。例如,将此值设置为“11”或更高版本,可以让系统在 Android 3.0 或更高版本上运行时将 Holo 默认主题应用于您的应用,并且在较大屏幕上运行时也会停用屏幕兼容模式,因为对 API 级别 11 的支持隐式支持较大屏幕。
系统可以根据您为此属性设置的值启用许多兼容性行为。其中一些行为由
Build.VERSION_CODES
参考中对应的平台版本进行描述。为了让您的应用与每个 Android 版本保持同步,请增加此属性的值以匹配最新的 API 级别,然后彻底测试您的应用在相应平台版本上的运行情况。
引入于:API 级别 4
- 一个整数,用于指定应用设计运行的最高 API 级别。
在 Android 1.5、1.6、2.0 和 2.0.1 中,系统在安装应用时以及系统更新后重新验证应用时都会检查此属性的值。在这两种情况下,如果应用的
maxSdkVersion
属性低于系统本身的 API 级别,则系统不允许安装该应用。在系统更新后重新验证的情况下,这会有效地从设备中移除您的应用。为了说明此属性在系统更新后如何影响您的应用,请考虑以下示例
在其清单中声明
maxSdkVersion="5"
的应用已发布到 Google Play。设备运行 Android 1.6 (API 级别 4) 的用户下载并安装了该应用。几周后,该用户通过无线方式接收到 Android 2.0 (API 级别 5) 的系统更新。安装更新后,系统会检查应用的maxSdkVersion
并成功重新验证。应用正常运行。但是,一段时间后,设备收到了另一个系统更新,这次是更新到 Android 2.0.1 (API 级别 6)。更新后,系统无法再重新验证该应用,因为系统本身的 API 级别 (6) 现在高于应用支持的最高级别 (5)。系统会阻止该应用对用户可见,实际上是将其从设备中移除。
警告:我们不建议声明此属性。首先,无需将该属性设置为阻止将您的应用部署到新发布的 Android 平台版本上的方法。从设计上讲,新版本的平台是完全向后兼容的。只要您的应用仅使用标准 API 并遵循开发最佳实践,它就可以在新版本上正常工作。其次,在某些情况下,声明该属性可能会导致您的应用在系统更新到更高 API 级别后从用户设备中删除。您的应用可能安装在大多数设备上会定期接收无线系统更新,因此在设置此属性之前,请考虑它们对您的应用的影响。
引入于:API 级别 4
某些 Android 版本(Android 2.0.1 以上)在安装或重新验证期间不会检查或强制执行maxSdkVersion
属性。然而,Google Play 在向用户呈现可供下载的应用时,仍会使用该属性作为过滤器。
- 引入于
- API 级别 1
什么是 API 级别?
API 级别是一个整数值,可唯一标识 Android 平台版本提供的框架 API 修订版本。
Android 平台提供了一个框架 API,应用可以使用它与底层 Android 系统进行交互。框架 API 包括:
- 一组核心软件包和类
- 一组用于声明清单文件的 XML 元素和属性
- 一组用于声明和访问资源的 XML 元素和属性
- 一组 Intent
- 一组应用可以请求的权限,以及系统中包含的权限强制执行
Android 平台的每个后续版本都可能包含其提供的 Android 应用框架 API 的更新。
框架 API 的更新旨在使新 API 与早期版本的 API 保持兼容。也就是说,API 中的大多数更改都是增量的,并引入了新的或替代的功能。随着 API 的部分升级,旧的被替换的部分会被废弃但不会被移除,以便现有应用仍可以使用它们。
在极少数情况下,API 的部分内容会被修改或移除,但通常此类更改仅为了支持 API 的稳健性以及应用或系统安全性。早期修订版的所有其他 API 部分均原封不动地保留。
Android 平台提供的框架 API 使用一个整数标识符指定,该标识符称为 API 级别。每个 Android 平台版本都精确支持一个 API 级别,尽管它隐式支持所有早期 API 级别(最低到 API 级别 1)。Android 平台的初始版本提供了 API 级别 1,后续版本则递增了 API 级别。
下表指定了每个 Android 平台版本支持的 API 级别。有关运行每个版本的设备的相对数量的信息,请参阅分布概况。
Android 中 API 级别的用途
API 级别标识符在帮助确保用户和应用开发者的最佳体验方面起着关键作用
- 它让 Android 平台可以描述其支持的最高框架 API 修订版本。
- 它让应用可以描述它们所需的框架 API 修订版本。
- 它让系统可以协商在用户设备上安装应用,从而避免安装版本不兼容的应用。
每个 Android 平台版本都将其 API 级别标识符内部存储在 Android 系统本身中。
应用可以使用框架 API 提供的清单元素 — <uses-sdk>
— 来描述它们能够运行的最低和最高 API 级别,以及它们设计支持的首选 API 级别。该元素提供三个关键属性:
android:minSdkVersion
:应用能够运行的最低 API 级别。默认值为“1”。android:targetSdkVersion
:应用设计运行的 API 级别。在某些情况下,这允许应用使用目标 API 级别中定义的清单元素或行为,而不是仅限于使用为最低 API 级别定义的元素或行为。android:maxSdkVersion
:应用能够运行的最高 API 级别。重要提示:在使用此属性之前,请阅读本页面上的关于此属性的信息。
例如,为了指定应用运行所需的最低系统 API 级别,应用在其清单中包含一个带有 android:minSdkVersion
属性的 <uses-sdk>
元素。android:minSdkVersion
的值是一个整数,对应于应用可以运行的最低 Android 平台版本的 API 级别。
当用户尝试安装应用时,或者在系统更新后重新验证应用时,Android 系统首先会检查应用清单中的 <uses-sdk>
属性,并将这些值与其自身的内部 API 级别进行比较。只有满足以下条件,系统才会允许安装开始:
- 如果声明了
android:minSdkVersion
属性,则其值小于或等于系统的 API 级别整数。如果未声明,系统会假定该应用需要 API 级别 1。 - 如果声明了
android:maxSdkVersion
属性,则其值等于或大于系统的 API 级别整数。如果未声明,系统会假定该应用没有最高 API 级别。有关系统如何处理此属性的更多信息,请阅读此属性的说明。
在应用清单中声明时,<uses-sdk>
元素可能如下所示:
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
应用在 android:minSdkVersion
中声明 API 级别的主要原因是为了告知 Android 系统,它使用了在该指定 API 级别中引入的 API。
如果应用以某种方式安装在 API 级别较低的平台上,则当它尝试访问不存在的 API 时,会在运行时崩溃。系统通过不允许应用安装来防止这种情况发生,如果它所需的最低 API 级别高于目标设备上平台版本的 API 级别。
开发注意事项
以下部分提供了您在开发应用时需要考虑的与 API 级别相关的信息。
应用前向兼容性
Android 应用通常与新版本的 Android 平台前向兼容。
因为框架 API 的几乎所有更改都是增量的,所以使用任何给定版本的 API(由其 API 级别指定)开发的 Android 应用都与更高版本的 Android 平台和更高 API 级别前向兼容。应用可以在所有更高版本的 Android 平台上运行,除非在极少数情况下应用使用了后来因某种原因被移除的 API 部分。
前向兼容性很重要,因为许多 Android 设备会接收无线 (OTA) 系统更新。用户可能会安装您的应用并成功使用,然后稍后接收到 Android 平台新版本的 OTA 更新。一旦安装了更新,您的应用将在环境的新运行时版本中运行,但它仍然具有您的应用所依赖的 API 和系统功能。
API 以下的更改,例如底层系统本身的更改,可能会在您的应用在新环境中运行时对其产生影响。作为应用开发者,了解应用在每个系统环境中的外观和行为非常重要。
为了帮助您在各种 Android 平台版本上测试应用,Android SDK 包含多个您可以下载的平台。每个平台都包含一个兼容的系统映像,您可以在 AVD 中运行该映像来测试您的应用。
应用向后兼容性
Android 应用不一定与比其编译所针对的 Android 平台版本更旧的版本向后兼容。
Android 平台的每个新版本都可能包含新的框架 API,例如那些让应用能够访问新平台功能或替换现有 API 部分的 API。当应用在新平台上运行时以及在 API 级别指定的更高版本的平台上运行时,都可以访问新的 API。但由于早期版本的平台不包含新的 API,因此使用新 API 的应用无法在这些平台上运行。
尽管 Android 设备不太可能降级到以前版本的平台,但重要的是要认识到,现场可能有很多设备运行的是早期版本的平台。即使在接收 OTA 更新的设备中,有些设备也可能滞后,并且可能长时间未收到更新。
选择平台版本和 API 级别
在开发应用时,您需要选择编译应用所针对的平台版本。通常,请将您的应用编译到您的应用可以支持的最低平台版本。
您可以通过将应用针对逐步降低的构建目标进行编译来确定最低的平台版本。确定最低版本后,使用相应的平台版本和 API 级别创建 AVD,并全面测试您的应用。请务必在应用的清单中声明 android:minSdkVersion
属性,并将其值设置为该平台版本的 API 级别。
声明最低 API 级别
如果您构建的应用使用了最新平台版本中引入的 API 或系统功能,请将 android:minSdkVersion
属性设置为最新平台版本的 API 级别。这样,用户只有在他们的设备运行兼容的 Android 平台版本时才能安装您的应用。反过来,这有助于确保您的应用可以在他们的设备上正常运行。
如果您的应用使用了最新平台版本中引入的 API,但未声明 android:minSdkVersion
属性,那么它可以在运行最新平台版本的设备上正常运行,但不能在运行早期平台版本的设备上运行。在后一种情况下,当应用尝试使用早期版本中不存在的 API 时,会在运行时崩溃。
针对更高 API 级别进行测试
编译应用后,请务必在应用 android:minSdkVersion
属性中指定的平台上进行测试。为此,请创建使用应用所需平台版本的 AVD。此外,为了检查前向兼容性,请在所有使用比您的应用使用的 API 级别更高的 API 级别的平台上运行和测试应用。
Android SDK 包含多个您可以使用的平台版本,包括最新版本,并提供一个更新工具,您可以使用它根据需要下载其他平台版本。
要访问更新程序,请使用位于 <sdk>/tools 目录中的 android
命令行工具。您可以通过执行 android sdk
启动 SDK 更新程序。您也可以双击 android.bat
(Windows) 或 android
(OS X/Linux) 文件。
要在模拟器中针对不同平台版本运行您的应用,请为您要测试的每个平台版本创建一个 AVD。有关 AVD 的更多信息,请参阅创建和管理虚拟设备。如果您使用物理设备进行测试,请确保您了解其运行的 Android 平台的 API 级别。有关平台版本及其 API 级别的列表,请参阅本文档中的表格。
按 API 级别筛选参考文档
Android 平台参考文档页面的左上方区域提供“API 级别”控件。您可以根据应用在其清单文件的 android:minSdkVersion
属性中指定的 API 级别,使用该控件仅显示应用实际可访问的 API 部分的文档。
要使用筛选,请从菜单中选择您的应用指定的 API 级别。在更高 API 级别中引入的 API 将会变灰并隐藏其内容,因为您的应用无法访问它们。
文档中按 API 级别筛选不提供每个 API 级别中新增或引入的内容的视图。它提供了一种方式来查看与给定 API 级别关联的整个 API,同时排除在更高 API 级别中引入的 API 元素。
要返回查看完整文档,请选择 API 级别菜单顶部的 REL。默认情况下,API 级别筛选处于禁用状态,因此您可以查看完整的框架 API,无论 API 级别如何。
单个 API 元素的参考文档指定了每个元素引入的 API 级别。软件包和类的 API 级别在每个文档页面内容区域的右上角指定为“在 API 级别中添加”。类成员的 API 级别在其详细说明标题中指定,位于右侧边距。