Android开发-API指南-

时间：2023-12-04 20:46:56

<uses-sdk>

英文原文：http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
采集（更新）日期：2014-5-7
搬迁自原博客：http://blog.sina.com.cn/s/blog_48d491300100zmx9.html

Android开发-API指南-<uses-sdk>

Google Play 过滤机制

Google Play 使用 manifest 中的 < uses-sdk >
属性对应用程序进行过滤，将不符合系统版本需求的设备排除掉。
在设置此属性之前，请确认自己已经完全理解了
Google Play 过滤器

语法：
<uses-sdk android:minSdkVersion="integer"

          android:targetSdkVersion="integer"

          android:maxSdkVersion="integer" />
包含于：
<manifest>
说明：

用于表明应用程序与一个或多个版本 Android 平台的兼容性，以整数型的 API 级别来表示。 应用程序声明的 API 级别将与给定的 Android 系统进行比较，不同 Android 设备的 API Level 可能各不相同。

不要去理会名称（指 uses-sdk），本元素是用于指定 API 级别 的，而不是指 SDK （软件开发包）或 Android 平台的版本号。 API 级别总是以一个整数值来表示。 API 级别是无法从相应的 Android 版本号推导出来的（比如，它既不是主版本号，也不是主版本号加小版本号）。

请参阅文档 将应用程序版本化。

属性：
android:minSdkVersion
整数值，指定运行应用程序所需的最低 API 级别。 如果系统 API 级别低于本属性设定的值， Android 系统将阻止用户安装此应用程序。 本属性必需指定。

提醒： 如果未声明本属性，系统假定缺省值为“1”，这表示应用程序与所有版本的 Android 兼容。 如果应用程序无法兼容所有版本（比如，用到了 API 级别 3 才开始引入的 API ）， 也没有声明正确的 android:minSdkVersion， 那么安装在低于 API 级别 3 的系统中后，一旦在运行过程中试图访问不可用的 API，应用程序就会崩溃。 因此，请确保在 minSdkVersion 属性中声明正确的 API 级别。

android:targetSdkVersion
整数值，指定应用程序的目标 API 级别。如果不设置本属性，缺省值等于已给定的 minSdkVersion。

本属性将告知系统应用程序已经针对此目标版本进行了测试，系统不会启用任何与此目标版本相关的向前兼容特性。 应用程序仍然能够在较低版本（最低至 minSdkVersion）的系统上运行。

随着 Android 的版本更新，某些特性甚至组件外观都会发生变化。 不过，当平台的 API 级别高于应用程序声明的 targetSdkVersion时，系统会启用兼容性特性，应用程序仍然可以按预计方式运行。 通过把 targetSdkVersion 设定为所需的平台版本，你可以禁用兼容特性。 比如，将本值设置为大于等于“11”，当运行于 Android 3.0 以上版本时， 系统就能在应用程序上使用新加入的默认主题（Holo），并且在大屏幕设备上时还会禁用 屏幕兼容模式 （因为 API 级别 11 隐含了对大屏幕的支持）。

根据本属性设定的值，有系统可能会启用很多兼容性特性。 有相当多的特性在参考文档 Build.VERSION_CODES 中分版本进行了说明。

为了能随着 Android 版本的发布而对应用程序进行维护，你应该及时调大本属性值以匹配最新的 API 级别， 然后在对应版本的平台上对程序进行充分的测试。

引入于：API 级别 4

android:maxSdkVersion
整数值，指定应用程序设计可运行的最高 API 级别。

在 Android 1.5、1.6、2.0 和 2.0.1 版本中，当安装应用程序、系统更新后对应用程序进行重校验时，系统都会检查本属性值。 这两种情况下，如果应用程序的 maxSdkVersion 属性小于系统的 API 级别，系统就会阻止该程序的安装。 实际上，当系统更新后对应用程序进行重校验时，系统将会从设备上删除该应用程序。

为了说明本属性在系统更新后对应用程序的影响，请参阅以下例子：

某应用程序在 manifest 中声明了 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，应用程序可以用这些 API 与底层系统进行交互。 这套API由以下部分组成：

  • 核心包和类
  • Manifest 文件中使用的 XML 格式的元素和属性声明
  • 声明和访问资源时所用的 XML 格式的元素和属性
  • 一些预设的 Intent
  • 应用程序可请求的权限以及系统预设的权限

Android 平台每个较高版本都会包含之前的 API 更新。

API 的更新机制使得新版本的 API 可以与早期版本保持兼容。 也就是说，大部分的 API 改动都是新增功能，或是引入新 API ，或是替代原有功能。 作为 API 升级过程中的一部分工作，被替换的旧功能被视为过时功能但不会被删除。 因此，现有的应用程序仍然可以使用这些过时的功能。 在极少数情况下，一部分 API 可能会被修改或删除，通常这种改动只是为了确保 API 的稳定性及应用程序或系统的安全性。 早期版​​本的 API 剩余部分都将原封不动地带入新版本。

Android 平台提供的每个版本的 API 都用一个整数值标识，名为“API级别”。 每个版本的 Android 平台只对应支持一个 API 级别，虽然这隐含了对所有之前版本 API 级别的支持（直至 API 级别 1）。 Android 平台的第一个版本提供了 API 级别 1 ，后续版本的级别依次递增。

下表给出了 Android 平台每个版本对应支持的 API 级别。 有关各个版本 Android 设备的数量占比情况，请参阅 平台版本统计。

平台版本 API 级别 VERSION_CODE 备注
Android 4.4 19 KITKAT 特点
Android 4.3 18 JELLY_BEAN_MR2 特点
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 特点
Android 4.1, 4.1.1 16 JELLY_BEAN 特点
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 特点
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2 Platform
Highlights-->
Android 3.1.x 12 HONEYCOMB_MR1 特点
Android 3.0.x 11 HONEYCOMB 特点
Android 2.3.4
Android 2.3.3		 10 GINGERBREAD_MR1 特点
Android 2.3.2
Android 2.3.1
Android 2.3		 9 GINGERBREAD
Android 2.2.x 8 FROYO 特点
Android 2.1.x 7 ECLAIR_MR1 特点
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT 特点
Android 1.5 3 CUPCAKE 特点
Android 1.1 2 BASE_1_1  
Android 1.0 1 BASE  

API 级别在 Android 中的用途

API 级别在保证用户和应用程序开发人员的最佳体验方面发挥了关键性作用：

  • Android 平台可以用它描述所支持的最高 API 版本。
  • 应用程序可以用它描述所需要的 API 版本。
  • 系统可以用它检验应用程序在用户设备上的可安装性，版本不兼容的应用程序将不会安装。

每个版本的Android平台都在其内部存储了自己的 API 级别号。

应用程序可以用 API 提供的 manifest 元素 — <uses-sdk> —
描述可正常运行的最低、最高 API 级别，以及预期应支持的 API 级别。
该元素给出了三个关键属性：

  • android:minSdkVersion —
    指明应用程序可以运行的最低 API 级别。默认值是“1”。
  • android:targetSdkVersion —
    指明设计应用程序时期望运行的 API 级别。
    某些情况下，应用程序可通过本属性使用目标 API 级别中定义的 manifest 元素或特性，
    而不限于使用最低 API 级别定义的内容。
  • android:maxSdkVersion —
    指明该应用程序可以运行的最高 API 级别。
    重点： 使用该属性之前请先阅读文档
    <uses-sdk>。

例如，为了指定运行所需的最低 API 级别，
应用程序应该在其 manifest 的 <uses-sdk> 元素中包含 android:minSdkVersion 属性。
android:minSdkVersion 的值应该是一个整数，对应于应用程序可运行的最早 Android 版本 的 API 级别。

当用户尝试安装某应用程序时，或者在系统升级后对应用程序重新校验时，
Android 系统首先会检查应用程序 manifest 中的 <uses-sdk> 属性，
并将其值与系统内部的 API 级别进行比较。
只有满足以下条件时，系统才会允许应用程序的安装：

  • 如果声明了android:minSdkVersion属性，则其值必须小于等于当前系统的 API 级别值。
    如果未声明，系统就会假定该应用程序运行需要的最低 API 级别是 1 。
  • 如果声明了android:maxSdkVersion属性，则其值必须大于等于当前系统的 API 级别值。
    如果未声明，系统就会假定该应用程序没有最高 API 级别的限制。
    关于系统如何处理该属性的更多信息，请阅读文档
    <uses-sdk>。

如果应用程序的 manifest 文件中进行了声明，则 <uses-sdk> 元素看起来应如下所示：

< manifest>

  <uses-sdk android:minSdkVersion="5" />

  ...

< /manifest>

应用程序都应该在 android:minSdkVersion 中声明 API 级别， 主要目的是为了告诉 Android 系统，它将会用到给定 API 级别引入的 API。 如果由于某种原因应用程序被安装到了 API 级别较低的平台上，那么一旦去访问那些不存在的API时，它就会崩溃。 如果所需的最低 API 级别高于目标设备的平台版本，则系统就会禁止应用程序的安装，这样就防止了上述情况的发生。

例如， android.appwidget 包是 API 级别 3 开始引入的。 如果某应用程序用到了此 API，就必须声明 android:minSdkVersion 属性为 3。 这样，该应用程序就可以在 Android 1.5（API 级别 3 ）、Android 1.6 （API 级别 4） 等平台上安装， 而无法安装到 Android 1.1 （API 级别 2）和 Android 1.0 （API 级别 1）平台上。

关于指定应用程序所需 API 级别的更多信息，请参阅 manifest 文件的 <uses-sdk> 部分。

开发时的注意事项

以下章节描述了开发应用程序时应该考虑的有关 API 级别的内容。

应用程序的向前兼容性

Android 应用程序通常向前兼容较新版本的 Android 平台

几乎所有的 API 变动都是递增的，因此使用给定版本 API （由 API 级别来指定）开发的应用程序都是与后续版本 Android 及更高级别 API 相兼容的。 应用程序应该可以在任何高版本的 Android 平台上运行，除非它用到了之后因某种原因被移除的 API。

向前兼容性非常重要，因为很多 Android 设备会收到无线（over-the-air ，OTA）系统更新提醒。 用户可能在安装和使用应用程序时一切正常，然后收到 OTA 更新并升级到新版本的 Android 平台。 一旦升级完成，应用程序就要在一个新版本的环境下运行，这个环境也包含了应用程序所需的 API 和系统功能。

某些情况下，隐藏在 API 背后的变化（比如系统底层的变化）可能会对运行于新环境下的应用程序造成影响。 因此，作为开发人员有一点非常重要，就是了解应用程序在各种系统环境下的外观和行为。 为了帮助你在各种版本的 Android 平台上测试应用程序，Android SDK 包含了多个版本的平台以供下载。 每个版本的平台都包含了兼容的系统镜像，你可以在相应版本的 AVD （模拟器）运行这些镜像，以便对应用程序进行测试。

应用程序的向后兼容性

Android 应用程序并不是非要向后兼容于比编译环境更早的 Android 平台版本。

Android 平台的每个新版本都可能包含新的 API ，比如提供新的平台功能，或者替代部分已有的 API 。 应用程序可以在新版本及后续版本的平台中使用这些新的API，版本的更新可以由 API 级别来反映。 反之，由于早期版本的平台不包含这些新的 API，用到新 API 的应用程序在旧版的平台上是无法运行的。

虽然 Android 设备不太可能会降级到以前的系统版本，但你必须意识到：会有很多设备仍然运行着老版本的系统。 即便是那些收到 OTA 更新消息的设备，有些仍然会延迟更新甚至长时间未完成更新。

选择平台版本和 API 级别

在开发应用程序时，你需要选择一个平台版本，以便基于此版本 Android 平台进行编译。 通常，你应该选择可支持的最低版本进行编译。

你可以逐次递减目标版本并进行编译，以便确定最低可支持的平台版本。 一旦确定了最低的版本，你就应该创建相应版本（即 API 级别）的 AVD ，并全面测试你的应用程序。 请确保在应用程序的 manifest 中申明 android:minSdkVersion属性，并赋予相应版本的 API 级别。

声明最低 API 级别

如果你的应用程序用到了最新版本平台才引入的 API 或系统特性，你就应该将 android:minSdkVersion 属性设为该版本对应的 API 级别。 这将确保用户只能在运行所需兼容版本 Android 的设备上安装你的应用程序。 进而保证能在他们的设备上正常使用你的应用程序。

如果应用程序用到了最新版本平台引入的 API，但却没有声明 android:minSdkVersion 属性， 那它在最新平台上是会正常运行，但是在早期版本的平台上却不行。 在后一种情况下，一旦应用程序试图访问旧平台上不存在的 API，它就会崩溃。

针对高版本 API 级别进行测试

应用程序编译完毕后，你必须在 android:minSdkVersion 属性设定的版本上进行测试。 请用相应的版本创建 AVD 来完成测试。 此外，为了确保向前兼容性，你还应该在所有高于所需 API 级别的版本上运行和测试应用程序。

Android SDK 包含了包括最新版本在内的多版本平台以供使用，并且还提供了升级工具，用于下载所需要的其他版本。

要使用升级工具，请使用 android 命令行工具，该工具位于 <sdk>/tools 目录中。 你可以执行 android sdk 命令来启动 SDK 升级工具，也可以简单地双击 android.bat （Windows下）或 android （OS X/Linux）文件。 在 ADT 中，你还可以选择菜单Window > Android SDK Manager来访问升级工具。

为了让应用程序能在多个版本的模拟器上运行，请为每个要测试的版本都创建一个 AVD 设备。 关于 AVD 的更多信息，请参阅 创建并管理模拟器。 如果你使用物理设备进行测试，请确认它的 Android 平台的 API 级别。 请参阅本文开头的平台版本和 API 级别对照表。

使用临时 API 级别

有时候，可能会存在一种“早期预览”（Early Look）版的 Android 平台 SDK。 尽管这时的 API 可能不是最终版本，但为了能在此版本上着手开发，就不会设定此类平台的 API 级别。 你必须在 manifest 中换用此版本平台的 provisional API Level ，以便建立与此版本对应的应用程序。 临时 API级别 不是一个整数，而是一个表示未发布平台版本的字符串名称。 “早期预览”版本的临时 API 级别将会在发布说明中进行设定，且为大小写敏感的。

临时 API 级别的用途是为了防止开发者无意中发布或用户不小心安装了基于“早期预览”版 API 开发的应用程序， 这些应用程序可能无法稳定运行于最终的系统上。

临时 API 级别仅在使用早期预览版的 SDK 时才有效，并且只能运行于模拟器之中。 使用临时 API 级别的应用程序永远都无法安装到 Android 设备中。 在最终版本发布后，你必须将 manifest 中的所有临时 API 级别替换成最终平台的实际 API 级别值。

根据 API 级别过滤参考文档

在 Android Developers 网站的参考文档页面的右上角，有一个“根据 API 级别筛选 ”（“Filter by API Level”）的选项。 （译者注：经核实，此选项目前在页面左侧，可直接下拉选择各 API Level 。） 利用这个选项，你可以只显示应用程序实际用到的那部分 API 文档，这是根据 Manifest 文件中的 android:minSdkVersion 属性值指定的 API 级别来确定的。

要使用筛选功能，请选中搜索框下面的勾选框。 （译者注：经核实，未找到此勾选框，也许是文档未更新。） 然后将“Filter by API Level”选项设置为应用程序指定的 API 级别。 你可以看到，因为应用程序无法访问指定级别之后才引入的 API ，这些新 API 的内容会标记为灰色。

根据 API 级别进行筛选的功能并不会为每个 API 级别的新增内容都提供一个新的页面， 它只是给出一种完整展现某级别 API 内容的方法，并去除了后续版本引入的 API 内容。

如果你不需要筛选 API 文档，只要通过勾选框禁用即可。 API 级别筛选默认是被禁用的，因此你可以看到全部的 API，而不必去关心 API 级别。

还有一点需要注意，每个单独的 API 参考文档页面都指明了该 API 是从哪个级别开始引入的。 包和类的 API 级别在每个文档页面的右上角“Since <api level>”部分进行了说明。 类成员的 API 级别在其详细信息的上部右侧进行了说明。

相关文章