外文原文
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
1
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 android.appwidget 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)
2
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.
3
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.
4
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 android.bat (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
5
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
6
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.
7
在 android 中使用 API 级别
中文翻译
API 级别标识为保证用户和应用程序开发者的最佳体验,起了关键作用:
1.它让 android 平台可以描述它支持的框架 API 的最高版本
2.它让应用程序可以描述它需要的框架 API 版本
3.它使得系统可以在硬件设备上安装应用程序时能够检查版本是否匹配,使得版
本不兼容的应用程序不会被错误安装在设备之上.
每个版本的 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 级别要求的目标硬件上来防止此类结果发生。
8