<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 元素和属性集
  • Intent 集
  • 应用可以请求的权限集，以及系统中包含的权限强制措施

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 级别。有关运行每个版本的设备相对数量的信息，请参阅分发情况面板。

平台版本API 级别VERSION_CODE备注
Android 16 36 BAKLAVA 平台亮点
Android 15 35 VANILLA_ICE_CREAM 平台亮点
Android 14 34 UPSIDE_DOWN_CAKE 平台亮点
Android 13 33 TIRAMISU 平台亮点
Android 12 32 S_V2 平台亮点
31 S 平台亮点
Android 11 30 R 平台亮点
Android 10 29 Q 平台亮点
Android 9 28 P 平台亮点
Android 8.1 27 O_MR1 平台亮点
Android 8.0 26 O 平台亮点
Android 7.1.1
Android 7.1		 25 N_MR1 平台亮点
Android 7.0 24 N 平台亮点
Android 6.0 23 M 平台亮点
Android 5.1 22 LOLLIPOP_MR1 平台亮点
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH 仅适用于 Wearables 的 KitKat
Android 4.4 19 KITKAT 平台亮点
Android 4.3 18 JELLY_BEAN_MR2 平台亮点
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 平台亮点
Android 4.1, 4.1.1 16 JELLY_BEAN 平台亮点
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 平台亮点
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 平台亮点
Android 3.0.x 11 HONEYCOMB 平台亮点
Android 2.3.4
Android 2.3.3		 10 GINGERBREAD_MR1 平台亮点
Android 2.3.2
Android 2.3.1
Android 2.3		 9 GINGERBREAD
Android 2.2.x 8 FROYO 平台亮点
Android 2.1.x 7 ECLAIR_MR1 平台亮点
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT 平台亮点
Android 1.5 3 CUPCAKE 平台亮点
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

API 级别在 Android 中的用途

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

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

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

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

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

例如，为了指定应用运行所需的最低系统 API 级别，应用在其清单中包含一个带有 android:minSdkVersion 属性的 <uses-sdk> 元素。 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 级别向前兼容。除非在应用使用了后来因某种原因被移除的部分 API 的个别情况下，否则应用可以在所有更高版本的 Android 平台上运行。

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

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

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

应用的向后兼容性

Android 应用不一定向后兼容比编译时使用的 Android 平台版本更旧的版本。

每个新版本的 Android 平台都可以包含新的框架 API，例如那些使应用能够访问新的平台功能或替换现有 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 级别 Platform API 的平台上运行和测试应用。

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

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

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

按 API 级别过滤参考文档

Android 平台参考文档页面在每页左上角提供了一个“API 级别”控件。您可以使用此控件仅显示应用清单文件 android:minSdkVersion 属性中指定 API 级别下实际可访问的 API 部分的文档。

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

按 API 级别过滤文档不会显示每个 API 级别中新增或引入的内容。它提供了一种查看与给定 API 级别关联的整个 API 的方式，同时排除在更高 API 级别中引入的 API 元素。

要返回查看完整文档，请选择 API 级别菜单顶部的REL。默认情况下，API 级别过滤处于禁用状态，以便您可以查看完整的框架 API，无论 API 级别如何。

单个 API 元素的参考文档指定了每个元素引入时的 API 级别。软件包和类的 API 级别在每个文档页面内容区域的右上角显示为“Added in API level”。类成员的 API 级别在其详细说明标题的右侧边缘指定。