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

Android API Levels

译者署名： jackeylu

译者链接： http://jackeylu.wordpress.com/

版本：Android 3.0 r1

原文

http://developer.android.com/guide/appendix/api-levels.html

Android API Levels

在本文中

API的级别是什么?

在Android中使用API级别

开发者需要考虑的内容

应用程序的向前兼容性

应用程序的向后兼容性

平台版本和API级别的选择

声明最低API级别

针对高版本的API级别测试

使用临时的API级别

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

参见

<uses-sdk> 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提供的清单文件元素 — <uses-sdk> 来描述该应用程序可以运行的最小和最大API级别，以及应用程序开发者设计期望运行的平台版本。三种属性分别描述如下:

android:minSdkVersion — 指明该应用程序可以运行的API最低版本。默认是“1”。
android:targetSdkVersion — 指明该应用程序设计时期望运行的目标API版本。在某些情况下，这允许应用程序使用目标API级别下定义的清单元素或行为，而不是只限于使用最低API级别定义的内容。(译者注：android之targetsdkversion的理解---兼容性问题)
android:maxSdkVersion — 指明该应用程序可以运行的最高API级别。重要声明: 使用该属性之前请阅读<uses-sdk>文档。

比如，要指明一个应用程序能够运行的最低API级别，应当在该应用程序的清单文件的<uses-sdk>元素中加入android:minSdkVersion属性。android:minSdkVersion的值是一个正整数，对应的是该应用程序能够运行的最低平台的API级别标识。

用户尝试安装一个应用程序，或者在系统升级后重验证应用程序的时候，Android系统首先会检查应用程序的清单文件中的<uses-sdk>属性，将其与系统内部API级别对比。系统只有在满足下列情况时才允许进行应用程序安装：

如果声明了android:minSdkVersion属性，其属性值必须小于或等于该系统的API级别对应的整数值。如果未声明，系统会默认该应用程序运行需要的最低API级别是1。
如果声明了android:maxSdkVersion属性，其属性值必须等于或大于该系统的API级对应的整数值。如果未声明，系统会默认该应用程序没有最高API级别限制。请通过阅读文档<uses-sdk>以获得系统如何处理该属性的更多信息。

应用程序清单文件中声明该属性后， <uses-sdk>元素看起来应类似于下面的例子：

这样做的主要原因是，应用程序会通过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级别需求的更多信息，请阅读文档中关于清单文件的<uses-sdk>章节。

开发者需要考虑的内容(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命令行方式，该工具位于<sdk>/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 level>”进行声明该包和类的引入信息。类成员的API级别在其详细描述文件头部的右边进行描述。

文章精选

Android API Level

更多相关文章

随机推荐