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 宽）为单位，而不是按通用屏幕尺寸（如大或特大）进行测量。

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

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

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

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

此外，应用仍可以查询系统，并管理在运行时的界面和资源加载，就像在以前的平台版本中那样。

由于新 API 可让您通过 smallestWidth、宽度和高度更直接地定位屏幕，因此了解不同屏幕类型的典型特征会很有帮助。下表列出了一些示例，以“dp”为单位。

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

类型	密度（通用）	尺寸 (dp)	smallestWidth (dp)
Baseline 手机	mdpi	320x480	320
小平板电脑/大手机	mdpi	480x800	480
7 英寸平板电脑	mdpi	600x1024	600
10英寸平板电脑	mdpi	800x1280	800

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

为屏幕支持添加了新的资源限定符

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

新的限定符包括：

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

如果需要，您还可以创建多个重叠的资源配置。例如，您可以标记一些资源以用于宽度超过 480 dp 的任何屏幕，另一些资源用于宽度超过 600 dp 的屏幕，以及另一些资源用于宽度超过 720 dp 的屏幕。当有多个资源配置符合给定屏幕的条件时，系统会选择最匹配的配置。为了精确控制在给定屏幕上加载哪些资源，您可以使用一个限定符标记资源，也可以组合使用多个新的或现有的限定符。

根据前面列出的典型维度，以下是有关如何使用新限定符的一些示例：

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" - 通过此属性，您可以指定无需兼容模式即可运行应用的最大 smallestWidth。如果当前屏幕大于指定的值，则系统会以普通模式显示应用，但允许用户选择通过系统栏中的设置切换到兼容模式。
• android:largestWidthLimitDp="numDp" - 此属性可让您指定运行应用的最大 smallestWidth。如果当前屏幕大于指定的值，系统会强制应用进入屏幕兼容模式，以确保在当前屏幕上实现最佳显示。
• android:requiresSmallestWidthDp="numDp" - 此属性可让您指定应用可在其上运行时的最小 smallestWidth。如果当前屏幕小于指定的值，系统会认为应用与设备不兼容，但不会阻止它安装和运行。

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

如需了解有关如何使用新属性的完整信息，请参阅声明屏幕尺寸支持。

屏幕兼容性模式

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

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

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

注意：有关如何控制应用中的兼容模式的重要信息，请查看 Android 开发者博客上的适用于大屏设备上的应用的新模式一文。

适用于 720p 电视和类似设备的新屏幕密度

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

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

一般而言，应用不需要使用此密度。对于 720p 屏幕需要输出的情况，平台可以自动扩缩界面元素。

界面框架

• fragment
  • 新的 Fragment.SavedState 类包含通过 saveFragmentInstanceState() 从 fragment 实例检索到的状态信息。
  • 新方法 saveFragmentInstanceState() 可保存指定 Fragment 的当前实例状态。稍后创建与当前状态匹配的 Fragment 新实例时，可以使用该状态。
  • 新方法 setInitialSavedState() 可在首次构建 Fragment 时设置 Fragment 的初始保存状态。
  • 新的 onViewCreated() 回调方法会在任何已保存状态恢复到视图之前通知 Fragment onCreateView() 已返回。
  • isDetached() 方法确定 Fragment 是否已与界面显式分离。
  • 新的 attach() 和 detach() 方法允许应用在界面中重新附加或分离 fragment。
  • 借助新的 setCustomAnimations() 重载方法，您可以设置要针对进入/退出操作（尤其是在弹出返回堆栈时）运行的特定动画资源。现有实现未考虑 Fragment 在弹出返回堆栈时的不同行为。
• ActivityInfo 和 ApplicationInfo 中的屏幕尺寸信息
  • ActivityInfo 将 CONFIG_SCREEN_SIZE 和 CONFIG_SMALLEST_SCREEN_SIZE 添加为 configChanges 中的位掩码。这些位用于指示 Activity 本身能否处理屏幕尺寸和最小屏幕尺寸。
  • ApplicationInfo 添加了 largestWidthLimitDp、compatibleWidthLimitDp 和 requiresSmallestWidthDp 字段，这些字段派生自应用清单文件中的相应 <supports-screens> 属性。
• 用于从 WindowManager 获取显示大小的帮助程序
  • 新方法 getSize() 和 getRectSize() 允许应用获取显示屏的原始尺寸。
• 新增了公开的“全息”样式
  • 该平台现在针对文本、操作栏微件和标签页等提供了各种公开“全息”样式。如需查看完整列表，请参阅 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 框架

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

网络

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

电话

• 新增了 NETWORK_TYPE_HSPAP 网络类型常量。

核心实用程序

• Parcelable 实用程序
  • 新接口 Parcelable.ClassLoaderCreator 允许应用接收在其中创建对象的 ClassLoader。
  • 新增了 adoptFd、dup() 和 fromFd()，用于管理 ParcelFileDescriptor 对象。
• 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 库编译应用。您可能还需要在应用清单中的 <uses-sdk> 元素中添加 android:minSdkVersion="13" 属性，具体取决于您的需求。

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