Android API Levels

　　 在本文中
　　　　API 的级别是什么?
　　　　在 Android 中使用 API 级别
　　　　开发者需要考虑的内容
　　　　　　应用程序的向前兼容性
　　　　　　应用程序的向后兼容性
　　　　　　平台版本和 API 级别的选择
　　　　　　声明最低 API 级别
　　　　　　针对高版本的 API 级别测试
　　　　使用临时的 API 级别
　　　　通过 API 级别进行文档内容过滤
参见
　　　　 manifest element

当你开发你的 Android 应用程序时，了解该平台 API 变更管理的基本方法和概念是很有帮助的。同样的，知道 API 级别标识以及该标识如何保障你的应用与实际硬件设备相兼容对于开发及后续的发布、维护都是有益的。　　

本节内容告诉你 API 级别的知识，以及它如何影响你开发和使用的应用。　　

关于如何使用 “以 API 级别进行过滤” 来使用 API 参考手册，从本文末尾的文档过滤 (Filtering the documentation) 中可以得到更多信息。

API 级别是什么？(What is API Level?)　　

API 级别是一个整数值，它唯一标识了一个具体版本的 Android 平台，及其框架的 API 的版本。　　

Android 平台提供了一套框架 API，使得应用程序可以与系统底层进行交互。该框架 API 由以下模块组成：

• 一组核心的包和类
• 清单 (manifest) 文件的 XML 元素和属性声明
• 资源文件的 XML 元素和属性声明及访问形式
• 各类意图 (Intents)
• 应用程序可以请求的各类授权，以及系统中包含的授权执行　　
  每个 Android 平台的后续版本会包括它提供的更新的 Android 应用程序框架的 API。　　
  该框架的 API 的更新设计，使高版本的 API 与早期版本兼容。也就是说，在新版本 API 中大多数都是新增功能，和引进新的或替代的功能。作为 API 的部分升级，老的替换的部分已过时，但不会从新版本中删除，使得已有的应用程序仍然可以使用它们。在极少数情况下，旧版本 API 的部分可能被修改或删除，通常这种变化是为了保障 API 的稳定性及应用程序或系统的安全。所有其他早期版本的 API 将不做修改的保留。　　
  一个 Android 平台提供的框架 API，被指定一个整数标识符，称为 “API 级别”。每一个版本的 Android 平台只支持有一个 API 级别，虽然该支持是隐含地包括了所有早期的 API 级别（一直到 API 级别 1 级）。 Android 平台的最初版本提供的框架 API 级别是 1 级，随后的版本依次递增。　　
  下表说明了具体平台版本和支持的 API 级别的对应关系。
  | 平台版本 | API 级别 | |-------: | -------: |
  |Android 3.0 | 11 | |Android 2.3.3| 10| |Android 2.3 |9| |Android 2.2| 8| |Android 2.1 |7| |Android 2.0.1 |6| |Android 2.0 |5| |Android 1.6 |4| |Android 1.5 |3| |Android 1.1 |2| |Android 1.0 |1|

在 Android 中使用 API 级别 (Uses of API Level in Android)　　

API 级别标识为保证用户和应用程序开发者的最佳体验，起了关键作用：

• 它让 Android 平台可以描述它支持的框架 API 的最高版本
• 它让应用程序可以描述它需要的框架 API 版本
• 它使得系统可以在硬件设备上安装应用程序时能够检查版本是否匹配，使得版本不兼容的应用程序不会被错误安装在设备之上.　　
  每个版本的 Android 平台都在其内部存储了自己的 API 级别标识。　　
  应用程序可以用框架 API 提供的清单文件元素 — 来描述该应用程序可以运行的最小和最大 API 级别，以及应用程序开发者设计期望运行的平台版本。三种属性分别描述如下:
  
• android:minSdkVersion — 指明该应用程序可以运行的 API 最低版本。默认是 “1”。
• android:targetSdkVersion — 指明该应用程序设计时期望运行的目标 API 版本。在某些情况下，这允许应用程序使用目标 API 级别下定义的清单元素或行为，而不是只限于使用最低 API 级别定义的内容。(译者注：android 之 targetsdkversion 的理解 --- 兼容性问题)
• android:maxSdkVersion — 指明该应用程序可以运行的最高 API 级别。重要声明: 使用该属性之前请阅读文档。　　
  比如，要指明一个应用程序能够运行的最低 API 级别，应当在该应用程序的清单文件的元素中加入 android:minSdkVersion 属性。android:minSdkVersion 的值是一个正整数，对应的是该应用程序能够运行的最低平台的 API 级别标识。　　
  用户尝试安装一个应用程序，或者在系统升级后重验证应用程序的时候，Android 系统首先会检查应用程序的清单文件中的属性，将其与系统内部 API 级别对比。系统只有在满足下列情况时才允许进行应用程序安装：
• 如果声明了 android:minSdkVersion 属性，其属性值必须小于或等于该系统的 API 级别对应的整数值。如果未声明，系统会默认该应用程序运行需要的最低 API 级别是 1。
• 如果声明了 android:maxSdkVersion 属性，其属性值必须等于或大于该系统的 API 级对应的整数值。如果未声明，系统会默认该应用程序没有最高 API 级别限制。请通过阅读文档以获得系统如何处理该属性的更多信息。 　
  应用程序清单文件中声明该属性后， 元素看起来应类似于下面的例子： 　　
  这样做的主要原因是，应用程序会通过 android:miniSdkVersion 声明的 API 级别来告知系统——该应用程序使用的 API 是指定引入的 API 级别。假如没有这种属性声明，一个应用程序如果因为某些不知名的原因被安装在低级别 API 系统之上，那么该应用程序会在运行时因为尝试访问不存在的 API 而崩溃。为此，Android 系统通过不允许应用程序被安装在不满足其最低 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 级别需求的更多信息，请阅读文档中关于清单文件的章节。

开发者需要考虑的内容 (Development Considerations)

本节属于应用程序开发者需要了解的内容。

应用程序的向前兼容性 (Application forward compatibility)　　

Android 应用程序一般向前兼容于 Android 平台的新版本。　　

这是因为几乎所有的框架 API 变更都是添加性质的，一个以某种版本的 API 开发的应用程序是向前兼容与后续 Android 系统及高版本 API。应用程序应当可以运行于高版本的平台，除非使用了未来因某种原因移除的 API。　　

向前兼容性的特性如此重要，是因为很多的 Android 驱动的设备能够使用 OTA 远程下载技术进行系统更新。用户开始时能够很好的安装和使用你开发的应用程序，后来进行了 OTA 升级到新版本的 Android 平台。一旦升级完毕，你的应用程序将运行在一个新的版本环境下，而这个环境应当包含了你的应用程序所需的 API 和系统功能。　　

某些情况下，API 背后的变化，例如系统底层的变化，可能会影响到你的应用程序运行在新的环境下。为此，作为应用程序开发人员，应当了解应用程序在不同系统环境下将会有如何的外观和行为。Android SDK 包含了多个平台版本，开发人员可以下载下来，用于测试自己的应用程序在不同版本下的运行情况。每个版本的平台都提供了兼容的系统镜像，你可以将应用程序运行在对应的 Android 虚拟设备（模拟器）上进行测试。

应用程序的向后兼容性 (Application backward compatibility)　　

Android 应用程序不一定向后兼容于那些比这些应用程序开发环境低的平台环境。　　

Android 平台的每个新版本包含了新的框架 API，例如新的平台功能，或者替代部分已有的 API。应用程序在新平台上可以访问这些新的 API，就像之前提到的，在后续更新的版本中，这些新功能 API 也是可以继续使用。相反的，因为早期版本的平台不会包含新的 API 功能，使用了新 API 的应用程序在那些旧平台上是无法运行的。　　

虽然一个 Android 平台设备不太可能降级到以前的版本，但是需要了解的是：实际生活中可能会有很多设备运行的是较旧的平台版本。即使在设备接收到 OTA 远程下载升级，有些人仍然可能会滞后甚至可能不会收到更新。
平台版本和 API 级别的选择 (Selecting a platform version and API Level)　　

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

你可以通过寻找最低的可以支持你的应用程序编译的平台方式来决定你将会支持的最低平台版本。一旦你确定了支持的最低版本后，你就可以创建对应版本的 AVD 模拟器来全面测试你的应用程序。你需要注意的是不要忘记在应用程序清单文件中申明 android:minSdkVersion 属性，并赋上正确的 API 级别标识。

声明最低 API 级别 (Declaring a minimum API Level)　　

如果你开发的应用程序使用了最新平台上引入的 API 或平台特性，你就需要将 android:minSdkVersion 属性赋最新平台的 API 级别标识。这将保证用户只能在他们的设备与你的应用程序平台版本兼容情况下安装。反过来说，这样能够保证你的应用程序在他们的设备上表现正常。　　

如果你用了最新的 API 或平台特性，但是没有申明 android:minSdkVersion 属性，那么你的应用程序在最新平台上运行是没有稳定，但是在早期版本的平台上是会出错的。在后一种情况，应用程序在尝试访问旧平台上不存在的 API 时会崩溃。

针对高版本的 API 级别测试 (Testing against higher API Levels)　　

编译完你的应用程序，你应当在支持的最低版本平台上详细测试应用程序的表现。可以通过创建对应平台的 AVD 模拟器进行测试。此外，要保证向前兼容性，你应当在你的应用程序可能运行的更高平台版本上进行运行和测试。　　

Android SDK 包含了多个平台版本供开发者使用，其中包括了最新的版本，并且提供了升级工具使得开发者可以获取其他的版本。　　

要使用升级工具，可以通过 Android 命令行方式，该工具位于/tools 路径下。你可以用敲入 android 指令运行该升级工具，而不用指定任何参数。你也可以简单地通过双击 Windows 下的 android.bat 或 OS X/Linux 下的 android 文件来启动升级工具。在 ADT 工具界面，你可以通过菜单的 Window > Android SDK and AVD Manager 来访问升级工具。　　

要想将你的应用程序在不同平台版本的模拟器上运行，需要创建对应的 AVD 设备。关于 AVD 的更多信息，请参见 Creating and Managing Virtual Devices。如果你用物理设备进行测试，确保清楚运行的具体平台版本。通过本文开始部分的映射表格可以知道平台版本对应的 API 级别标识。

使用临时的 API 级别 (Using a Provisional API Level)　　

某些情况下，有可能会发布 “早期预览 (Early Look)” 版的 Android 平台 SDK。在此平台版本上开发使用的 API 将不会是最终发布版，平台的 API 级别标识数字就不会指定。你必须在程序清单文件中使用临时的 API 级别进行标识，以便建立对应的平台应用。临时 API 级别不是一个整数，而是一个表示未发布的平台版本的字符串代号。“早期预览” 版本的 API 级别在发布说明中会申明，该代号是大小写敏感的。　　

临时 API 级别标识的用途是保护开发者和设备使用者免于无意中发布或安装在 “早期预览” 平台版本上开发的应用程序，这些应用程序可能在最终的发布系统上运行不稳定。　　

临时 API 级别标识仅仅在使用 “早期预览” 版本的 SDK 下有效，并且只能运行应用程序于模拟器之中。实际的 Android 设备上是无法安装使用临时 API 级别标识的应用程序的。在最终版本平台发布后，你必须将程序清单文件中用到的临时 API 级别标识替换成最终平台的实际 API 级别整数值。

通过 API 级别进行文档内容过滤

(Filtering the Reference Documentation by API Level)　　

Android 开发者站点上的参考文档的每个页面的右上方提供了 “Filter by API Level” 控件。你可以用这个控件来仅仅显示你应用程序相关的那部分 API 文档，可以通过应用程序清单文件中的 android:minSdkVersion 属性值进行过滤。　　

要使用过滤功能，可以通过页面搜索框下面的选择框来启用过滤功能。比如设定 “Filter by API Level” 控件内容与你应用程序申明的相同。注意：在选定级别之后引入的心 API 会以灰色显示，并且内容被隐藏，因为你的应用程序是无法访问这些新功能。　

API 级别过滤方法不会提供每个 API 级别中新添加的功能视图，仅仅展现对应 API 级别的整个内容，其中去除了后续新版本中的内容。　

如果你不想过滤 API 文档了，只需要关闭该选择框的特性。API 级别过滤默认是关闭的，因此你可以看到整个框架 API 的全貌，而不管具体的 API 级别。　　

还要注意的是个别的 API 元素申明了该 API 参考文档在哪一级引入的。这通过在每个文档页面正文部分的右上角的 “Since ” 进行声明该包和类的引入信息。类成员的 API 级别在其详细描述文件头部的右边进行描述。