安卓 英文 外文文献翻译 Android API级别

2024年2月3日发(作者：)

本科毕业设计(论文)

外文翻译（附外文原文）

学 院： 信息科学与工程学院

课题名称： 基于腾讯微博开放平台的

数字教学交流系统

专业(方向)： 计算机科学与技术

班 级： BCU09-4

学 生： 周杰伦

指导教师： 方文山

日 期： 2013/4/19

Android API级别

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

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

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

API级别是什么？

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级别的对应关系。

平台版本

Android 3.0

Android 2.3

Android 2.2

Android 2.1

Android 2.0

Android 1.6

Android 1.5

Android 1.1

Android 1.0

API级别

11

9

8

7

5

4

3

2

1

Android 2.3.3 10

Android 2.0.1 6

在Android中使用API级别

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







它让Android平台可以描述它支持的框架API的最高版本

它让应用程序可以描述它需要的框架API版本

它使得系统可以在硬件设备上安装应用程序时能够检查版本是否匹配，使得版本不兼容的应用程序不会被错误安装在设备之上.

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

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





android:minSdkVersion — 指明该应用程序可以运行的API最低版本。默认是“1”。

android:targetSdkVersion — 指明该应用程序设计时期望运行的目标API版本。在某些情况下，这允许应用程序使用目标API级别下定义的清单元素或行为，而不是只限于使用最低API级别定义的内容。

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级别要求的目标硬件上来防止此类结果发生。

例如，get类包是在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级别需求的更多信息，请阅读文档中关于清单文件的章节。

开发者需要考虑的内容

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

应用程序的向前兼容性

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

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

向前兼容性的特性如此重要，是因为很多的Android驱动的设备能够使用OTA远程下载技术进行系统更新。用户开始时能够很好的安装和使用你开发的应

用程序，后来进行了OTA升级到新版本的Android平台。一旦升级完毕，你的应用程序将运行在一个新的版本环境下，而这个环境应当包含了你的应用程序所需的API和系统功能。

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

应用程序的向后兼容性

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

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

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

平台版本和API级别的选择

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

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

声明最低API级别

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

如果你用了最新的API或平台特性，但是没有申明android:minSdkVersion属性，那么你的应用程序在最新平台上运行是没有稳定，但是在早期版本的平台上

是会出错的。在后一种情况，应用程序在尝试访问旧平台上不存在的API时会崩溃。

针对高版本的API级别测试

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

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

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

AVD Manager来访问升级工具。

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

使用临时的API级别

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

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

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

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

Android开发者站点上的参考文档的每个页面的右上方提供了“Filter by API

Level”控件。你可以用这个控件来仅仅显示你应用程序相关的那部分API文档，可以通过应用程序清单文件中的android:minSdkVersion属性值进行过滤。

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

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

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

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

Android API Levels

As you develop your application on Android, it's useful to understand the platform's general

approach to API change management. It's also important to understand the API Level identifier

and the role it plays in ensuring your application's compatibility with devices on which it may be

installed.

The sections below provide information about API Level and how it affects your applications.

For information about how to use the "Filter by API Level" control available in the API

reference documentation, see

Filtering the documentation

at the end of this document.

What is API Level?

API Level is an integer value that uniquely identifies the framework API revision offered by a

version of the Android platform.

The Android platform provides a framework API that applications can use to interact with the

underlying Android system. The framework API consists of:











A core set of packages and classes

A set of XML elements and attributes for declaring a manifest file

A set of XML elements and attributes for declaring and accessing resources

A set of Intents

A set of permissions that applications can request, as well as permission enforcements

included in the system

Each successive version of the Android platform can include updates to the Android

application framework API that it delivers.

Updates to the framework API are designed so that the new API remains compatible with

earlier versions of the API. That is, most changes in the API are additive and introduce new or

replacement functionality. As parts of the API are upgraded, the older replaced parts are

deprecated but are not removed, so that existing applications can still use them. In a very

small number of cases, parts of the API may be modified or removed, although typically such

changes are only needed to ensure API robustness and application or system security. All

other API parts from earlier revisions are carried forward without modification.

The framework API that an Android platform delivers is specified using an integer identifier

called "API Level". Each Android platform version supports exactly one API Level, although

support is implicit for all earlier API Levels (down to API Level 1). The initial release of the

Android platform provided API Level 1 and subsequent releases have incremented the API

Level.

The following table specifies the API Level supported by each version of the Android platform.

Platform Version

Android 3.0

Android 2.3.3

Android 2.3

Android 2.2

Android 2.1

Android 2.0.1

Android 2.0

Android 1.6

Android 1.5

Android 1.1

Android 1.0

API Level

11

10

9

8

7

6

5

4

3

2

1

Uses of API Level in Android

The API Level identifier serves a key role in ensuring the best possible experience for users

and application developers:







It lets the Android platform describe the maximum framework API revision that it supports

It lets applications describe the framework API revision that they require

It lets the system negotiate the installation of applications on the user's device, such that

version-incompatible applications are not installed.

Each Android platform version stores its API Level identifier internally, in the Android system

itself.

Applications can use a manifest element provided by the framework API

—

— to describe the minimum and maximum API Levels under which they

are able to run, as well as the preferred API Level that they are designed to support. The

element offers three key attributes:



android:minSdkVersion — Specifies the minimum API Level on which the

application is able to run. The default value is "1".



android:targetSdkVersion — Specifies the API Level on which the application is

designed to run. In some cases, this allows the application to use manifest elements or

behaviors defined in the target API Level, rather than being restricted to using only those

defined for the minimum API Level.



android:maxSdkVersion — Specifies the maximum API Level on which the

application is able to run. Important: Please read the

documentation before

using this attribute.

For example, to specify the minimum system API Level that an application requires in order to

run, the application would include in its manifest a

element with

a

android:minSdkVersion attribute. The value

of

android:minSdkVersion would be the integer corresponding to the API Level of

the earliest version of the Android platform under which the application can run.

When the user attempts to install an application, or when revalidating an appplication after a

system update, the Android system first checks the

attributes in the

application's manifest and compares the values against its own internal API Level. The system

allows the installation to begin only if these conditions are met:

 If a

android:minSdkVersion attribute is declared, its value must be less than

or equal to the system's API Level integer. If not declared, the system assumes that the

application requires API Level 1.

 If a

android:maxSdkVersion attribute is declared, its value must be equal to

or greater than the system's API Level integer. If not declared, the system assumes that the

application has no maximum API Level. Please read the

documentation for

more information about how the system handles this attribute.

When declared in an application's manifest, a

element might look like this:

...

The principal reason that an application would declare an API Level

in

android:minSdkVersion is to tell the Android system that it is using APIs that

were introduced in the API Level specified. If the application were to be somehow installed on

a platform with a lower API Level, then it would crash at run-time when it tried to access APIs

that don't exist. The system prevents such an outcome by not allowing the application to be

installed if the lowest API Level it requires is higher than that of the platform version on the

target device.

For example, the

get package was introduced with API Level 3. If an

application uses that API, it must declare a

android:minSdkVersion attribute with a

value of "3". The application will then be installable on platforms such as Android 1.5 (API

Level 3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and Android

1.0 platforms (API Level 1).

For more information about how to specify an application's API Level requirements, see

the

section of the manifest file documentation.

Development Considerations

The sections below provide information related to API level that you should consider when

developing your application.

Application forward compatibility

Android applications are generally forward-compatible with new versions of the Android

platform.

Because almost all changes to the framework API are additive, an Android application

developed using any given version of the API (as specified by its API Level) is

forward-compatible with later versions of the Android platform and higher API levels. The

application should be able to run on all later versions of the Android platform, except in isolated

cases where the application uses a part of the API that is later removed for some reason.

Forward compatibility is important because many Android-powered devices receive

over-the-air (OTA) system updates. The user may install your application and use it

successfully, then later receive an OTA update to a new version of the Android platform. Once

the update is installed, your application will run in a new run-time version of the environment,

but one that has the API and system capabilities that your application depends on.

In some cases, changes below the API, such those in the underlying system itself, may affect

your application when it is run in the new environment. For that reason it's important for you, as

the application developer, to understand how the application will look and behave in each

system environment. To help you test your application on various versions of the Android

platform, the Android SDK includes multiple platforms that you can download. Each platform

includes a compatible system image that you can run in an AVD, to test your application.

Application backward compatibility

Android applications are not necessarily backward compatible with versions of the Android

platform older than the version against which they were compiled.

Each new version of the Android platform can include new framework APIs, such as those that

give applications access to new platform capabilities or replace existing API parts. The new

APIs are accessible to applications when running on the new platform and, as mentioned

above, also when running on later versions of the platform, as specified by API Level.

Conversely, because earlier versions of the platform do not include the new APIs, applications

that use the new APIs are unable to run on those platforms.

Although it's unlikely that an Android-powered device would be downgraded to a previous

version of the platform, it's important to realize that there are likely to be many devices in the

field that run earlier versions of the platform. Even among devices that receive OTA updates,

some might lag and might not receive an update for a significant amount of time.

Selecting a platform version and API Level

When you are developing your application, you will need to choose the platform version

against which you will compile the application. In general, you should compile your application

against the lowest possible version of the platform that your application can support.

You can determine the lowest possible platform version by compiling the application against

successively lower build targets. After you determine the lowest version, you should create an

AVD using the corresponding platform version (and API Level) and fully test your application.

Make sure to declare a

android:minSdkVersion attribute in the application's

manifest and set its value to the API Level of the platform version.

Declaring a minimum API Level

If you build an application that uses APIs or system features introduced in the latest platform

version, you should set the

android:minSdkVersion attribute to the API Level of the

latest platform version. This ensures that users will only be able to install your application if

their devices are running a compatible version of the Android platform. In turn, this ensures

that your application can function properly on their devices.

If your application uses APIs introduced in the latest platform version but does not declare

a

android:minSdkVersion attribute, then it will run properly on devices running the

latest version of the platform, but not on devices running earlier versions of the platform. In the

latter case, the application will crash at runtime when it tries to use APIs that don't exist on the

earlier versions.

Testing against higher API Levels

After compiling your application, you should make sure to test it on the platform specified in the

application's

android:minSdkVersion attribute. To do so, create an AVD that uses

the platform version required by your application. Additionally, to ensure forward-compatibility,

you should run and test the application on all platforms that use a higher API Level than that

used by your application.

The Android SDK includes multiple platform versions that you can use, including the latest

version, and provides an updater tool that you can use to download other platform versions as

necessary.

To access the updater, use the

android command-line tool, located in the /tools

directory. You can launch the Updater by using the

android command without specifying

any options. You can also simply double-click the (Windows) or android (OS

X/Linux) file. In ADT, you can also access the updater by selecting Window > Android SDK

and AVD Manager.

To run your application against different platform versions in the emulator, create an AVD for

each platform version that you want to test. For more information about AVDs, see Creating

and Managing Virtual Devices. If you are using a physical device for testing, ensure that you

know the API Level of the Android platform it runs. See the table at the top of this document for

a list of platform versions and their API Levels.

Using a Provisional API Level

In some cases, an "Early Look" Android SDK platform may be available. To let you begin

developing on the platform although the APIs may not be final, the platform's API Level integer

will not be specified. You must instead use the platform's provisional API Level in your

application manifest, in order to build applications against the platform. A provisional API Level

is not an integer, but a string matching the codename of the unreleased platform version. The

provisional API Level will be specified in the release notes for the Early Look SDK release

notes and is case-sensitive.

The use of a provisional API Level is designed to protect developers and device users from

inadvertently publishing or installing applications based on the Early Look framework API,

which may not run properly on actual devices running the final system image.

The provisional API Level will only be valid while using the Early Look SDK and can only be

used to run applications in the emulator. An application using the provisional API Level can

never be installed on an Android device. At the final release of the platform, you must replace

any instances of the provisional API Level in your application manifest with the final platform's

actual API Level integer.

Filtering the Reference Documentation by API Level

Reference documentation pages on the Android Developers site offer a "Filter by API Level"

control in the top-right area of each page. You can use the control to show documentation only

for parts of the API that are actually accessible to your application, based on the API Level that

it specifies in the

android:minSdkVersion attribute of its manifest file.

To use filtering, select the checkbox to enable filtering, just below the page search box. Then

set the "Filter by API Level" control to the same API Level as specified by your application.

Notice that APIs introduced in a later API Level are then grayed out and their content is

masked, since they would not be accessible to your application.

Filtering by API Level in the documentation does not provide a view of what is new or

introduced in each API Level — it simply provides a way to view the entire API associated with

a given API Level, while excluding API elements introduced in later API Levels.

If you decide that you don't want to filter the API documentation, just disable the feature using

the checkbox. By default, API Level filtering is disabled, so that you can view the full

framework API, regardless of API Level.

Also note that the reference documentation for individual API elements specifies the API Level at

which each element was introduced. The API Level for packages and classes is specified as "Since

" at the top-right corner of the content area on each documentation page. The API

Level for class members is specified in their detailed description headers, at the right margin.