<uses-sdk>

Google Play 使用您应用清单中声明的 <uses-sdk> 属性来过滤不满足其平台版本要求的设备上的应用。在设置这些属性之前，请确保您了解 Google Play 过滤器。

语法

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

包含在

<manifest>

描述

允许您通过 API 级别整数表示应用程序与一个或多个 Android 平台版本的兼容性。应用程序表示的 API 级别与给定 Android 系统的 API 级别进行比较，这在不同的 Android 设备之间可能有所不同。

尽管名称如此，此元素用于指定 API 级别，而不是软件开发工具包 (SDK) 或 Android 平台的版本号。API 级别始终是一个整数。您无法从其关联的 Android 版本号推导出 API 级别。例如，它与主版本或主版本和次版本之和不同。

另请阅读有关 应用程序版本控制 的文档。

属性

android:minSdkVersion

一个整数，指定应用程序运行所需的最低 API 级别。如果系统的 API 级别低于此属性中指定的值，则 Android 系统会阻止用户安装应用程序。始终声明此属性。

注意：如果未声明此属性，则系统会假定默认值为“1”，这表示您的应用程序与所有版本的 Android 兼容。如果不是这种情况，并且您没有声明正确的 minSdkVersion，那么当安装在具有不兼容 API 级别的系统上时，应用程序在尝试访问不可用的 API 时会在运行时崩溃。因此，请务必在 minSdkVersion 属性中声明适当的 API 级别。

android:targetSdkVersion

一个整数，指定应用程序目标的 API 级别。如果未设置，则默认值等于赋予 minSdkVersion 的值。

此属性通知系统您已针对目标版本进行了测试，并且系统不会启用任何兼容性行为来维护您的应用与目标版本的向前兼容性。应用程序仍然能够在较低版本（低至 minSdkVersion）上运行。

随着 Android 每个新版本的演变，某些行为甚至外观都可能会发生变化。但是，如果平台的 API 级别高于您的应用的 targetSdkVersion 中声明的版本，则系统可以启用兼容性行为，以便您的应用继续以您期望的方式工作。您可以通过将 targetSdkVersion 指定为与运行它的平台的 API 级别匹配来禁用此类兼容性行为。

例如，将此值设置为“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 级别，则系统不允许应用程序安装。在系统更新后的重新验证情况下，这实际上会从设备中删除您的应用程序。

为了说明此属性如何在系统更新后影响您的应用程序，请考虑以下示例

一个应用程序在其清单中声明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，应用程序可以使用它与底层的 Android 系统交互。框架 API 包括

• 一组核心包和类
• 一组用于声明清单文件的 XML 元素和属性
• 一组用于声明和访问资源的 XML 元素和属性
• 一组意图
• 一组应用程序可以请求的权限，以及系统中包含的权限执行

Android 平台的每个后续版本都可能包含对其提供的 Android 应用程序框架 API 的更新。

框架 API 的更新设计为使新 API 与早期版本的 API 保持兼容。也就是说，API 中的大多数更改都是增量的，并引入了新的或替换的功能。随着 API 的部分升级，旧的替换部分会被弃用但不会被删除，以便现有应用程序仍然可以使用它们。

在极少数情况下，API 的部分会被修改或删除，尽管通常只有在需要支持 API 稳健性和应用程序或系统安全性时才需要进行此类更改。来自早期修订版的所有其他 API 部分都会原样保留。

Android 平台提供的框架 API 使用称为API 级别的整数标识符进行指定。每个 Android 平台版本都支持一个 API 级别，尽管隐式支持所有早期 API 级别（低至 API 级别 1）。Android 平台的初始版本提供了 API 级别 1，随后的版本增加了 API 级别。

下表指定了每个版本的 Android 平台支持的 API 级别。有关运行每个版本的设备相对数量的信息，请参阅分发信息中心。

Android 中 API 级别用途

API 级别标识符在帮助确保用户和应用程序开发人员获得最佳体验方面发挥着关键作用

• 它允许 Android 平台描述其支持的最大框架 API 修订版。
• 它允许应用程序描述其所需的框架 API 修订版。
• 它允许系统协商在用户设备上安装应用程序，以便不会安装版本不兼容的应用程序。

每个 Android 平台版本都在内部存储其 API 级别标识符，在 Android 系统本身中。

应用程序可以使用框架 API 提供的清单元素——<uses-sdk>——来描述它们能够运行的最低和最高 API 级别，以及它们设计支持的首选 API 级别。该元素提供了三个关键属性

• android:minSdkVersion：应用程序能够运行的最低 API 级别。默认值为“1”。
• android:targetSdkVersion：应用程序设计运行的 API 级别。在某些情况下，这允许应用程序使用目标 API 级别中定义的清单元素或行为，而不是仅限于使用为最低 API 级别定义的那些。
• android:maxSdkVersion：应用程序能够运行的最大 API 级别。重要提示：在使用此属性之前，请阅读此页面上有关此属性的信息。

例如，要指定应用程序运行所需的最低系统 API 级别，应用程序在其清单中包含一个<uses-sdk>元素，并带有android:minSdkVersion属性。 android:minSdkVersion的值是对应于应用程序可以在其下运行的 Android 平台最早版本的 API 级别的整数。

当用户尝试安装应用程序或在系统更新后重新验证应用程序时，Android 系统首先检查应用程序清单中的<uses-sdk>属性，并将这些值与其自身的内部 API 级别进行比较。只有满足以下条件，系统才会开始安装

• 如果声明了android:minSdkVersion属性，则其值小于或等于系统的 API 级别整数。如果未声明，则系统假定应用程序需要 API 级别 1。
• 如果声明了android:maxSdkVersion属性，则其值等于或大于系统的 API 级别整数。如果未声明，则系统假定应用程序没有最大 API 级别。阅读此属性的描述，以获取有关系统如何处理它的更多信息。

在应用程序的清单中声明时，<uses-sdk>元素可能如下所示

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

应用程序在android:minSdkVersion中声明 API 级别的主要原因是告诉 Android 系统它使用了在指定的 API 级别中引入的 API。

如果应用程序以某种方式安装在 API 级别较低的平台上，则当它尝试访问不存在的 API 时，它会在运行时崩溃。系统通过在应用程序所需的最低 API 级别高于目标设备上平台版本的 API 级别时不允许应用程序安装来防止这种情况发生。

开发注意事项

以下部分提供了与开发应用程序时需要考虑的 API 级别相关的信息。

应用程序向前兼容性

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

由于框架 API 的几乎所有更改都是增量的，因此使用任何给定版本的 API 开发的 Android 应用程序（由其 API 级别指定）与 Android 平台的更高版本和更高 API 级别向前兼容。应用程序可以在 Android 平台的所有更高版本上运行，除非在某些孤立的情况下，应用程序使用了后来由于某种原因而被删除的 API 部分。

向前兼容性非常重要，因为许多搭载 Android 系统的设备都会接收无线 (OTA) 系统更新。用户可能安装并成功使用您的应用程序，然后稍后收到 Android 平台新版本的 OTA 更新。更新安装后，您的应用程序将在环境的新运行时版本中运行，但该版本仍然拥有您的应用程序依赖的 API 和系统功能。

API **以下**的更改，例如底层系统本身的更改，可能会在应用程序在新环境中运行时对其产生影响。作为应用程序开发者，了解应用程序在每个系统环境中的外观和行为至关重要。

为了帮助您在 Android 平台的各个版本上测试应用程序，Android SDK 包含多个可供下载的平台。每个平台都包含一个兼容的系统映像，您可以在 AVD 中运行该映像以测试您的应用程序。

应用程序向后兼容性

Android 应用程序不一定与早于其编译目标版本的 Android 平台版本向后兼容。

Android 平台的每个新版本都可能包含新的框架 API，例如为应用程序提供访问新平台功能或替换现有 API 部分的功能。当在新平台上运行以及在 API 级别指定的更高版本平台上运行时，应用程序都可以访问这些新 API。但是，由于早期版本的平台不包含新 API，因此使用新 API 的应用程序无法在这些平台上运行。

尽管 Android 设备不太可能降级到以前的平台版本，但重要的是要认识到，现场可能存在许多运行早期平台版本的设备。即使在接收 OTA 更新的设备中，某些设备也可能滞后，并且可能在相当长的一段时间内无法收到更新。

选择平台版本和 API 级别

开发应用程序时，您需要选择要针对其编译应用程序的平台版本。通常，应针对应用程序可以支持的最低平台版本编译应用程序。

您可以通过针对连续较低的构建目标编译应用程序来确定最低可能的平台版本。确定最低版本后，使用相应的平台版本和 API 级别创建一个 AVD，并全面测试您的应用程序。确保在应用程序清单中声明 android:minSdkVersion 属性，并将其值设置为平台版本的 API 级别。

声明最低 API 级别

如果您构建的应用程序使用了最新平台版本中引入的 API 或系统功能，请将 android:minSdkVersion 属性设置为最新平台版本的 API 级别。这样，只有当用户的设备运行兼容版本的 Android 平台时，他们才能安装您的应用程序。反过来，这有助于确保您的应用程序能够在他们的设备上正常运行。

如果您的应用程序使用了最新平台版本中引入的 API，但**未**声明 android:minSdkVersion 属性，则它会在运行最新版本平台的设备上正常运行，但在运行早期版本平台的设备上**无法**正常运行。在后一种情况下，应用程序在尝试使用早期版本中不存在的 API 时，将在运行时崩溃。

针对更高 API 级别进行测试

编译应用程序后，请确保在应用程序 android:minSdkVersion 属性中指定的平台上对其进行测试。为此，请创建一个使用应用程序所需的平台版本的 AVD。此外，为了检查向前兼容性，请在所有使用比应用程序使用的 API 级别更高的 API 级别的平台上运行和测试应用程序。

Android SDK 包含多个可供使用的平台版本，包括最新版本，并提供了一个更新程序工具，您可以根据需要使用该工具下载其他平台版本。

要访问更新程序，请使用位于 /tools 目录中的 android 命令行工具。您可以通过执行 android sdk 来启动 SDK 更新程序。您也可以双击 android.bat（Windows）或 android（OS X/Linux）文件。

要在模拟器中针对不同的平台版本运行应用程序，请为要测试的每个平台版本创建一个 AVD。有关 AVD 的更多信息，请参阅创建和管理虚拟设备。如果您使用的是物理设备进行测试，请确保您知道其运行的 Android 平台的 API 级别。请参阅本文档中的表格，了解平台版本及其 API 级别列表。

按 API 级别筛选参考文档

Android 平台参考文档页面在每个页面的左上方提供“API 级别”控件。您可以使用该控件仅显示 API 中实际可供应用程序访问的部分的文档，具体取决于其清单文件中 android:minSdkVersion 属性中指定的 API 级别。

要使用筛选功能，请从菜单中选择应用程序指定的 API 级别。然后，将在更高 API 级别中引入的 API 将变灰，并且其内容将被屏蔽，因为它们无法被您的应用程序访问。

在文档中按 API 级别进行筛选不会提供每个 API 级别中新增或引入内容的视图。它提供了一种查看与给定 API 级别关联的整个 API 的方法，同时排除在更高 API 级别中引入的 API 元素。

要返回查看完整文档，请在 API 级别菜单顶部选择**REL**。默认情况下，API 级别筛选功能处于禁用状态，因此您可以查看完整的框架 API，而不管 API 级别如何。

各个 API 元素的参考文档指定了每个元素引入的 API 级别。包和类的 API 级别在每个文档页面内容区域的右上角指定为“在 API 级别中添加”。类成员的 API 级别在其详细说明标题中指定，位于右边缘。