Android 3.2 API

API 级别：13

Android 3.2 (HONEYCOMB_MR2) 是一个增量平台版本，为用户和开发者添加了新功能。以下部分概述了新功能和开发者 API。

对于开发者，Android 3.2 平台可作为 Android SDK 的可下载组件使用。可下载的平台包含 Android 库和系统映像，以及一组模拟器皮肤等。如需开始针对 Android 3.2 进行开发或测试，请使用 Android SDK 管理器将该平台下载到您的 SDK 中。

平台亮点

新用户功能

• 针对更广泛的平板电脑进行优化

  Android 3.2 对整个系统进行了多项优化，以确保在更多类型的平板电脑设备上提供出色的用户体验。

• 适用于固定大小应用的兼容性缩放

  Android 3.2 引入了新的兼容性缩放模式，让用户能够在更大的设备上以新的方式查看固定大小的应用。对于未设计为在较大屏幕尺寸（例如平板电脑）上运行的应用，新模式提供了一种像素级缩放替代方案，可替代标准界面拉伸。对于需要兼容性支持的应用，用户可以通过系统栏中的菜单图标访问新模式。

• 从 SD 卡同步媒体

  在支持 SD 卡的设备上，用户现在可以将媒体文件直接从 SD 卡加载到使用这些文件的应用。系统设施可让应用访问系统媒体库中的文件。

新的开发者功能

• 支持用于管理屏幕的扩展 API

  Android 3.2 为平台的屏幕支持 API 引入了扩展，以便开发者能够通过其他方式管理各种 Android 设备上的应用界面。该 API 包含新的资源限定符和新的清单属性，可让您更精确地控制应用在不同尺寸设备上的显示方式，而不是依赖于笼统的尺寸类别。

  为了确保固定大小的应用和对各种屏幕尺寸支持有限的应用获得尽可能最佳的显示效果，该平台还提供了一种新的缩放兼容模式，该模式会在较小的屏幕区域内渲染界面，然后将其放大以填充显示屏上的可用空间。如需详细了解屏幕支持 API 及其提供的控件，请参阅以下部分。

API 概览

屏幕支持 API

Android 3.2 引入了新的屏幕支持 API，可让您更好地控制应用在不同屏幕尺寸上的显示方式。该 API 基于现有的屏幕支持 API（包括平台的通用屏幕密度模型）构建而成，但通过以尺寸（以不依赖于密度的像素单位 [例如宽度为 600dp 或 720dp] 衡量）而非通用屏幕尺寸（例如 large 或 xlarge）来精确定位特定屏幕范围，对其进行了扩展

在设计应用界面时，您仍然可以依赖平台提供密度抽象，这意味着应用无需补偿不同设备之间实际像素密度的差异。您可以根据可用的水平或垂直空间量来设计应用界面。该平台使用三个新特征来表示可用空间量：smallestWidth、width 和 height。

• 屏幕的 smallestWidth 是其基本最小尺寸，以密度无关像素 (“dp”）为单位。是屏幕的高度或宽度中较短的尺寸。对于纵向屏幕，smallestWidth 通常基于其宽度；对于横向屏幕，则基于其高度。在所有情况下，smallestWidth 均派生自屏幕的固定特性，并且无论屏幕方向如何，其值都不会发生变化。smallestWidth 对应用非常重要，因为它表示需要绘制应用界面的最短宽度（不包括系统预留的屏幕区域）。
• 与之相反，屏幕的宽度和高度表示当前可供应用布局使用的横向或纵向空间，以“dp”为单位，不包括系统预留的屏幕区域。当用户在横向和纵向之间切换屏幕方向时，屏幕的宽度和高度会发生变化。

新的屏幕支持 API 旨在让您根据当前屏幕的 smallestWidth 管理应用界面。您还可以根据需要根据当前宽度或高度管理界面。为此，该 API 提供了以下工具：

• 用于将布局和其他资源定位到最小 smallestWidth、宽度或高度的新资源限定符，以及
• 新增了清单属性，用于指定应用的最大屏幕兼容性范围

此外，与旧版平台一样，应用仍可在运行时查询系统并管理界面和资源加载。

由于新 API 允许您通过 smallestWidth、width 和 height 更直接地定位屏幕，因此了解不同屏幕类型的典型特征会很有帮助。下表提供了一些示例，以“dp”为单位。

表 1. 典型设备，密度和尺寸以 dp 为单位。

类型	密度（一般化）	尺寸 (dp)	最小宽度 (dp)
基准手机	mdpi	320x480	320
小屏平板电脑/大屏手机	mdpi	480x800	480
7 英寸平板电脑	mdpi	600x1024	600
10英寸平板电脑	mdpi	800x1280	800

以下部分详细介绍了新的屏幕限定符和清单属性。如需详细了解如何使用屏幕支持 API，请参阅支持多种屏幕。

新增了屏幕支持资源限定符

借助 Android 3.2 中的新资源限定符，您可以更好地针对屏幕尺寸范围定位布局。您可以使用这些限定符创建针对特定最小 smallestWidth、当前宽度或当前高度（以密度无关像素为单位）而设计的资源配置。

新限定符如下：

• swNNNdp - 指定资源应使用的最小 smallestWidth，以“dp”为单位。如上所述，无论屏幕方向如何，其 smallestWidth 都是常量。示例：sw320dp、sw720dp、sw720dp。
• wNNNdp 和 hNNNdp - 指定资源应使用的最小宽度或高度（以“dp”为单位）。如上所述，屏幕的宽度和高度相对于屏幕的方向而言，并且会随方向的改变而改变。示例：w320dp、w720dp、h1024dp。

您还可以根据需要创建多个重叠的资源配置。 例如，您可以为某些资源添加标记，以便在宽度大于 480dp 的任何屏幕上使用，为其他资源添加标记，以便在宽度大于 600dp 的屏幕上使用，为其他资源添加标记，以便在宽度大于 720dp 的屏幕上使用。如果有多个资源配置适用于给定屏幕，系统会选择最匹配的配置。如需精确控制在给定屏幕上加载哪些资源，您可以使用一个限定符标记资源，也可以组合使用多个新限定符或现有限定符。

下面根据前面列出的典型维度，举例说明了如何使用新限定符：

res/layout/main_activity.xml   # For phones
res/layout-sw600dp/main_activity.xml   # For 7” tablets
res/layout-sw720dp/main_activity.xml   # For 10” tablets
res/layout-w600dp/main_activity.xml   # Multi-pane when enough width
res/layout-sw600dp-w720dp/main_activity.xml   # For large width

较低版本的平台会忽略新的限定符，因此您可以根据需要混合使用它们，以确保您的应用在任何设备上都能完美呈现。下面是一些示例：

res/layout/main_activity.xml   # For phones
res/layout-xlarge/main_activity.xml   # For pre-3.2 tablets
res/layout-sw600dp/main_activity.xml   # For 3.2 and up tablets

如需详细了解如何使用新限定符，请参阅使用新的尺寸限定符。

新增了用于实现屏幕尺寸兼容性的清单属性

该框架提供了一组新的 <supports-screens> 清单属性，可让您管理应用对不同屏幕尺寸的支持。具体而言，您可以指定应用设计为在哪些最小和最大屏幕上运行，以及应用设计为在哪些最大屏幕上运行时无需使用系统的新屏幕兼容性模式。与上述资源限定符一样，新的清单属性会指定应用支持的屏幕范围，如 smallestWidth 所指定。

适用于屏幕支持的新清单属性如下：

• android:compatibleWidthLimitDp="numDp" - 通过此属性，您可以指定应用在不使用兼容模式的情况下可以运行的最小宽度。如果当前屏幕大于指定的值，系统会在正常模式下显示应用，但允许用户通过系统栏中的设置选择切换到兼容模式。
• android:largestWidthLimitDp="numDp" - 通过此属性，您可以指定应用支持的最小 smallestWidth 值。如果当前屏幕大于指定的值，系统会强制应用进入屏幕兼容性模式，以确保在当前屏幕上获得最佳显示效果。
• android:requiresSmallestWidthDp="numDp" - 通过此属性，您可以指定能够运行应用的最小 smallestWidth。如果当前屏幕小于指定的值，系统会认为应用与设备不兼容，但不会阻止安装和运行该应用。

注意：Google Play 目前不会根据上述任何属性过滤应用。后续平台版本中将添加对过滤的支持。需要根据屏幕尺寸进行过滤的应用可以使用现有的 <supports-screens> 属性。

如需详细了解如何使用新属性，请参阅声明屏幕尺寸支持。

屏幕兼容性模式

Android 3.2 为明确声明不支持与其运行设备屏幕尺寸一样大的屏幕的应用提供了新的屏幕兼容模式。这种新的“缩放”模式是像素级缩放，它会在较小的屏幕区域内渲染应用，然后缩放像素以填充当前屏幕。

默认情况下，系统会为需要屏幕兼容模式的应用提供屏幕兼容模式作为用户选项。用户可以使用系统栏中的控件开启和关闭缩放模式。

由于新屏幕兼容性模式可能不适用于所有应用，因此平台允许应用使用清单属性停用该模式。当应用停用此功能时，系统不会在应用运行时向用户提供“缩放”兼容模式选项。

注意：如需了解如何在应用中控制兼容性模式的重要信息，请参阅 Android 开发者博客上的适用于大屏设备的应用的新模式一文。

针对 720p 电视和类似设备新增了屏幕密度

为了满足在 720p 电视或类似屏幕以及中等密度屏幕上运行的应用的需求，Android 3.2 引入了新的广义密度 tvdpi，约为 213。应用可以在 densityDpi 中查询新密度，并可以使用新的 tvdpi 限定符为电视和类似设备标记资源。例如：

res/drawable-tvdpi/my_icon.png   # Bitmap for tv density

一般情况下，应用应该不需要使用此密度。如果需要针对 720p 屏幕输出，平台可以自动缩放界面元素。

界面框架

• fragment
  • 新的 Fragment.SavedState 类用于存储通过 saveFragmentInstanceState() 从 fragment 实例检索的状态信息。
  • 新方法 saveFragmentInstanceState() 会保存给定 fragment 的当前实例状态。稍后在创建与当前状态匹配的 Fragment 实例时，可以使用该状态。
  • 新方法 setInitialSavedState() 用于在 Fragment 首次构建时设置其初始保存状态。
  • 新的 onViewCreated() 回调方法会在任何已保存状态恢复到视图之前通知 fragment onCreateView() 已返回。
  • isDetached() 方法用于确定 Fragment 是否已明确与界面分离。
  • 借助新的 attach() 和 detach() 方法，应用可以在界面中重新附加或分离 fragment。
  • 借助新的 setCustomAnimations() 重载方法，您可以设置要为进入/退出操作（尤其是在弹出返回堆栈时）运行的特定动画资源。现有实现未考虑到 fragment 在弹出返回堆栈时的不同行为。
• ActivityInfo 和 ApplicationInfo 中的屏幕尺寸信息
  • ActivityInfo 会在 configChanges 中将 CONFIG_SCREEN_SIZE 和 CONFIG_SMALLEST_SCREEN_SIZE 添加为位掩码。这些位表示 activity 本身是否可以处理屏幕尺寸和最小屏幕尺寸。
  • ApplicationInfo 添加了 largestWidthLimitDp、compatibleWidthLimitDp 和 requiresSmallestWidthDp 字段，这些字段派生自应用清单文件中相应的 <supports-screens> 属性。
• 用于从 WindowManager 获取显示大小的帮助程序
  • 借助新方法 getSize() 和 getRectSize()，应用可以获取显示屏的原始尺寸。
• 新的公开“全息”样式
  • 该平台现在为文本、ActionBar Widget 和标签页等提供了各种公共“全息”样式。如需查看完整列表，请参阅 R.style。
• LocalActivityManager、ActivityGroup 和 LocalActivityManager 现已废弃
  • 新应用应使用 Fragment 而非这些类。如需继续在旧版平台上运行，您可以使用 Android SDK 中提供的 v4 支持库（兼容性库）。v4 支持库提供了一个可低至 Android 1.6（API 级别 4）的 Fragment API 版本。
  • 对于针对 Android 3.0（API 级别 11）或更高版本开发的应用，标签页通常使用新的 ActionBar.newTab() 和相关 API 在界面中显示，以便将标签页放置在其操作栏区域内。

媒体框架

• 使用平台媒体提供程序 (MediaStore) 的应用现在可以直接从可移动 SD 卡（如果设备支持）读取媒体数据。应用还可以使用 MTP API 直接与 SD 卡文件交互。

图形

• Point 和 PointF 中的 Parcelable 实用程序
  • Point 和 PointF 类现在包含 Parcelable 接口和实用程序方法 describeContents()、readFromParcel() 和 writeToParcel()。

IME 框架

• 新增了 getModifiers() 方法，用于检索辅助键的当前状态。

USB 框架

• 用于检索设备的原始 USB 描述符的新 getRawDescriptors() 方法。您可以使用此方法访问无法通过更高级别 API 直接访问的描述符。

网络

• 网络类型常量
  • ConnectivityManager 添加了常量 TYPE_ETHERNET 和 TYPE_BLUETOOTH。

电话

• 新的 NETWORK_TYPE_HSPAP 网络类型常量。

核心实用程序

• Parcelable 实用程序
  • 新接口 Parcelable.ClassLoaderCreator 允许应用接收用于创建对象的 ClassLoader。
  • 新增了用于管理 ParcelFileDescriptor 对象的 adoptFd、dup() 和 fromFd()。
• Binder 和 IBinder
  • Binder 和 IBinder 中的新方法 dumpAsync() 可让应用转储到指定文件，确保目标异步执行。
  • 借助新的 IBinder 协议事务代码 TWEET_TRANSACTION，应用可以向目标对象发送推文。

新的地图项常量

该平台添加了新的硬件功能常量，您可以在应用清单中声明这些常量，以向 Google Play 等外部实体告知所需的硬件和软件功能。您可以在 <uses-feature> 清单元素中声明这些和其他功能常量。

Google Play 会根据应用的 <uses-feature> 属性对其进行过滤，以确保应用仅可供符合其要求的设备使用。

• 针对横向或纵向要求的功能常量

  Android 3.2 引入了新的功能常量，让应用能够指定它们是需要在横向还是纵向显示，或者同时在横向和纵向显示。声明这些常量表示应用不得安装在不提供关联屏幕方向的设备上。反之，如果未声明其中一个或两个常量，则表示应用对未声明的屏幕方向没有偏好，并且可能会安装在不提供这些屏幕方向的设备上。

  • android.hardware.screen.landscape - 应用要求以横向模式显示。
  • android.hardware.screen.portrait - 应用需要纵向显示。

  通常，在横屏和竖屏模式下都能正常运行的典型应用无需声明屏幕方向要求。相反，主要针对一种屏幕方向设计的应用（例如，针对电视设计的应用）可以声明其中一个常量，以确保该应用无法在不提供该屏幕方向的设备上运行。

  如果清单中声明的任何 activity 使用 android:screenOrientation 属性请求在特定屏幕方向下运行，则这也声明应用需要该屏幕方向。

• 其他特征常量
  • android.hardware.faketouch.multitouch.distinct - 应用需要支持对两个或更多点进行区分跟踪的模拟多点触控输入。
  • android.hardware.faketouch.multitouch.jazzhand - 应用需要支持对五点或更多点的轨迹进行区分跟踪的模拟多点触控输入。

API 差异报告

如需详细了解 Android 3.2（API 级别 13）中的所有 API 变更，请参阅 API 差异报告。

API 级别

Android 3.2 平台提供了更新后的框架 API 版本。Android 3.2 API 会被分配一个整数标识符（13），该标识符存储在系统本身中。此标识符称为“API 级别”，可让系统在安装应用之前正确确定应用是否与系统兼容。

如需在应用中使用 Android 3.2 中引入的 API，您需要针对 Android 3.2 SDK 平台中提供的 Android 库编译应用。根据您的需求，您可能还需要将 android:minSdkVersion="13" 属性添加到应用清单中的 <uses-sdk> 元素。

如需了解详情，请参阅什么是 API 级别？