Android 3.1 API

API 级别12

对于开发者而言,Android 3.1 平台 (HONEYCOMB_MR1) 可作为 Android SDK 的可下载组件使用。可下载平台包含 Android 库、系统映像,以及一组模拟器皮肤等。可下载的平台不包含任何外部库。

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

API 概览

以下部分从技术上概述了 Android 3.1 中面向开发者的新功能,包括自上一个版本以来框架 API 中的新功能和变化。

USB API

Android 3.1 引入了一些强大的新 API,用于将连接的外围设备与平台上运行的应用集成。这些 API 基于 USB(通用串行总线)堆栈和平台内置的服务,包括对 USB 主机和设备互动的支持。利用这些 API,开发者可以创建能够发现、与通过 USB 连接的各种设备类型以及管理此类设备的应用。

堆栈和 API 根据 Android 设备是充当主机还是外部硬件充当主机,从而区分两种基本类型的 USB 硬件:

  • USB 设备是一部连接的硬件,它依赖 Android 设备充当主机。例如,大多数输入设备、鼠标和操纵杆都是 USB 设备,许多相机、集线器等也是如此。
  • USB 配件是一部分已连接的硬件,该硬件具有 USB 主机控制器,能够为 Android 设备供电,旨在通过 USB 与 Android 设备通信。从机器人控制器到音乐器材、健身自行车等,各种外围设备都可以作为配件连接。

对于 USB 设备和 USB 配件这两种类型,平台的 USB API 都支持在连接或断开连接时通过 intent 广播进行发现,还支持标准接口、端点和传输模式(控制、批量和中断)。

android.hardware.usb 软件包中提供 USB API。中心类是 UsbManager,它提供了用于识别 USB 设备和 USB 配件并与之通信的辅助方法。应用可以获取 UsbManager 的实例,然后查询连接的设备或配件的列表,然后与它们进行通信或管理它们。UsbManager 还会声明系统广播的 intent 操作,以便在连接或断开 USB 设备或配件时进行通告。

其他类包括:

  • UsbDevice:一个类,表示作为 USB 设备连接的外部硬件(Android 设备充当主机)。
  • UsbAccessory:表示作为 USB 主机连接的外部硬件(其中 Android 设备充当 USB 设备)。
  • UsbInterfaceUsbEndpoint,可提供对设备的标准 USB 接口和端点的访问权限。
  • UsbDeviceConnectionUsbRequest,用于以同步或异步方式向 USB 设备发送数据以及从 USB 设备接收数据和控制消息。
  • UsbConstants,提供用于声明端点类型、设备类等的常量。

请注意,虽然平台中内置了 USB 堆栈,但具体设备上对 USB 主机和打开配件模式的实际支持由其制造商决定。具体而言,主机模式依赖于 Android 设备中相应的 USB 控制器硬件。

此外,开发者可以在 Google Play 上请求过滤,这样,如果设备未提供适当的 USB 支持,用户就无法使用其应用。如需请求过滤,请根据需要将以下一个或两个元素添加到应用清单中:

  • 如果应用应仅对支持 USB 主机模式(USB 设备连接)的设备可见,请声明以下元素:

    <uses-feature android:name="android.hardware.usb.host" android:required="true">

  • 如果应用应仅对支持 USB 配件(USB 主机连接)的设备可见,请声明以下元素:

    <uses-feature android:name="android.hardware.usb.accessory" android:required="true">

如需全面了解如何开发与 USB 配件互动的应用,请参阅开发者文档

如需查看使用 USB 主机 API 的示例应用,请参阅 ADB 测试Missile 启动器

MTP/PTP API

Android 3.1 提供了新的 MTP API,可让应用直接与连接的摄像头和其他 PTP 设备交互。借助此新 API,应用可以轻松地在连接和移除设备时接收通知、管理这些设备上的文件和存储空间,以及将文件和元数据传输到设备或从设备上传输文件和元数据。MTP API 可实现 MTP(媒体传输协议)规范的 PTP(图片传输协议)子集。

MTP API 位于 android.mtp 软件包中,并提供以下类:

  • MtpDevice 封装通过 USB 主机总线连接的 MTP 设备。应用可以实例化此类型的对象,然后使用其方法获取设备及其上存储的对象的相关信息,以及打开连接并传输数据。 其中一些方法包括:
    • getObjectHandles() 会返回设备上与指定格式和父级匹配的所有对象的句柄列表。若要获取有关对象的信息,应用可以将句柄传递给 getObjectInfo()
    • importFile() 允许应用将对象数据复制到外部存储空间中的文件。此调用可能会阻塞任意时间,具体取决于数据大小和设备的运行速度,因此应通过 spearate 线程进行。
    • open() 允许应用打开已连接的 MTP/PTP 设备。
    • getThumbnail() 会以字节数组的形式返回对象的缩略图。
  • MtpStorageInfo 存储有关 MTP 设备上存储单元的信息,与 MTP 规范第 5.2.2 节中所述的 StorageInfo 数据集相对应。借助该类中的方法,应用可获取存储单元的说明字符串、可用空间、最大存储容量、存储 ID 和卷标识符。
  • MtpDeviceInfo 存储与 MTP 规范第 5.1.1 节中所述的 DeviceInfo 数据集相对应的 MTP 设备信息。该类中的方法可让应用获取设备的制造商、型号、序列号和版本。
  • MtpObjectInfo 包含存储在 MTP 设备上的对象的相关信息,与 MTP 规范第 5.3.1 节中所述的 ObjectInfo 数据集相对应。通过该类中的方法,应用可以获取对象的大小、数据格式、关联类型、创建日期和缩略图信息。
  • MtpConstants 提供用于声明 MTP 文件格式代码、关联类型和保护状态的常量。

支持新的输入设备和动作事件

Android 3.1 扩展了输入子系统,以跨所有视图和窗口支持新的输入设备和新的动作事件类型。开发者可以基于这些功能进行构建,让用户除了使用键盘和触摸屏外,还可以使用鼠标、轨迹球、操纵杆、游戏手柄和其他设备与应用进行交互。

为了处理鼠标、滚轮和轨迹球输入,平台支持两种新的动作事件操作:

  • ACTION_SCROLL:描述非触摸滚动运动(例如通过鼠标滚轮)发生的指针位置。在 MotionEvent 中,AXIS_HSCROLLAXIS_VSCROLL 轴的值指定相对滚动移动。
  • ACTION_HOVER_MOVE 报告在没有按下按钮时鼠标的当前位置,以及自上次 HOVER_MOVE 事件以来的任何中间点。目前尚不支持悬停进入和退出通知。

为了支持操纵杆和游戏手柄,InputDevice 类包含以下新的输入设备来源:

为了描述来自这些新来源以及来自鼠标和轨迹球的动作事件,平台现在在 MotionEvent 上定义了轴代码,其方式类似于在 KeyEvent 上定义按键代码。操纵杆和游戏控制器的新轴代码包括 AXIS_HAT_XAXIS_HAT_YAXIS_RTRIGGERAXIS_ORIENTATIONAXIS_THROTTLE 等。现有的 MotionEvent 轴由 AXIS_XAXIS_YAXIS_PRESSUREAXIS_SIZEAXIS_TOUCH_MAJORAXIS_TOUCH_MINORAXIS_TOOL_MAJORAXIS_TOOL_MINORAXIS_ORIENTATION 表示。

此外,MotionEvent 还定义了一些通用轴代码,当框架不知道如何映射特定轴时,会使用这些代码。特定设备可以使用通用轴代码将自定义运动数据传递给应用。如需查看轴及其预期解释的完整列表,请参阅 MotionEvent 类文档。

平台批量向应用提供动作事件,因此单个事件可能包含当前位置和多个所谓的历史移动。应用应使用 getHistorySize() 获取历史样本的数量,然后使用 getHistoricalAxisValue() 按顺序检索和处理所有历史样本。之后,应用应使用 getAxisValue() 处理当前样本。

某些轴可通过特殊访问器方法进行检索。例如,应用可以调用 getX(),而不是调用 getAxisValue()。具有内置访问器的轴包括 AXIS_XAXIS_YAXIS_PRESSUREAXIS_SIZEAXIS_TOUCH_MAJORAXIS_TOUCH_MINORAXIS_TOOL_MAJORAXIS_TOOL_MINORAXIS_ORIENTATION

每个输入设备都有一个由系统分配的唯一 ID,还可提供多个来源。设备提供多个源时,多个源可以使用同一轴提供轴数据。例如,来自触摸来源的触摸事件使用 X 轴表示屏幕位置数据,而来自操纵杆来源的操纵杆事件改为使用 X 轴表示操纵杆位置。因此,应用务必要根据轴值的来源来解读轴值。处理动作事件时,应用应使用 InputDevice 类中的方法确定设备或来源支持的轴。具体而言,应用可以使用 getMotionRanges() 查询设备的所有轴或设备给定源的所有轴。在这两种情况下,InputDevice.MotionRange 对象中返回的轴的范围信息都会指定每个轴值的来源。

最后,由于来自操纵杆、游戏手柄、鼠标和轨迹球的动作事件不属于触摸事件,因此平台添加了一个新的回调方法,用于将这些事件作为“通用”动作事件传递给 View。具体而言,它会通过调用 onGenericMotionEvent()(而非 onTouchEvent())向 View 报告非触摸动作事件。

平台会以不同方式分派一般动作事件,具体取决于事件来源类。SOURCE_CLASS_POINTER 事件会转到指针下的 View,类似于触摸事件的工作方式。所有其他项会转到当前聚焦的 View。 例如,这意味着 View 必须取得焦点,才能接收操纵杆事件。如果需要,应用可以通过在 activity 或 Dialog 级别实现 onGenericMotionEvent() 来处理这些事件。

如需查看使用操纵杆动作事件的示例应用,请参阅 GameControllerInputGameView

RTP API

Android 3.1 在其内置 RTP(实时传输协议)堆栈中公开了一个 API,应用可以使用该 API 管理按需或交互式数据流式传输。具体而言,提供 VoIP、推送通话、会议和音频流式传输的应用可以使用该 API 发起会话,并通过任何可用网络传输或接收数据流。

RTP API 可在 android.net.rtp 软件包中找到。类包括:

为了支持音频会议和类似用途,应用将两个类实例化为流的端点:

最简单的用法涉及单个远程端点和本地端点。对于更复杂的用法,请参阅 AudioGroup 所述的限制。

如需使用 RTP API,应用必须通过在其清单文件中声明 <uses-permission android:name="android.permission.INTERNET"> 向用户请求权限。如需获取设备麦克风,还需具备 <uses-permission android:name="android.permission.RECORD_AUDIO"> 权限。

可调整大小的应用微件

从 Android 3.1 开始,开发者可以调整主屏幕 widget 的大小,即在水平、垂直方向上或在两个轴上调整大小。用户轻触并按住 widget 以显示其调整大小的手柄,然后拖动水平和/或垂直手柄以更改布局网格上的大小。

开发者可以通过在 widget 的 AppWidgetProviderInfo 元数据中定义 resizeMode 属性,使任何主屏幕 widget 可调整大小。resizeMode 属性的值包括“horizontal”、“vertical”和“none”。如需将 widget 声明为可在水平和垂直方向上调整大小,请提供值“horizontal|vertical”。

示例如下:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="294dp"
    android:minHeight="72dp"
    android:updatePeriodMillis="86400000"
    android:previewImage="@drawable/preview"
    android:initialLayout="@layout/example_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigure"
    android:resizeMode="horizontal|vertical" >
</appwidget-provider>

如需详细了解主屏幕 widget,请参阅应用 widget 文档。

动画框架

  • 新增了 ViewPropertyAnimator 类
    • 新的 ViewPropertyAnimator 类为开发者提供了一种便利的方式来为 View 对象上的选定属性添加动画效果。该类可以自动执行和优化属性的动画,并且可让您更轻松地管理 View 对象上的多个同时动画。

      ViewPropertyAnimator 的使用非常简单。若要为 View 的属性添加动画效果,请调用 animate() 来为该 View 构建 ViewPropertyAnimator 对象。使用 ViewPropertyAnimator 上的方法指定要为哪个属性添加动画效果以及如何为其添加动画效果。例如,如需将 View 淡入透明,请调用 alpha(0);ViewPropertyAnimator 对象负责处理关于配置底层 Animator 类和启动该类,然后渲染动画的详细信息。

  • 动画背景颜色
    • 新的 getBackgroundColor()setBackgroundColor(int) 方法可让您获取/设置动画背后的背景颜色(仅适用于窗口动画)。目前背景必须为黑色,并具有任何所需的 alpha 级别。
  • ViewAnimator 获取带动画效果的分数

界面框架

显卡

  • 用于管理位图的帮助程序
    • setHasAlpha(boolean) 可让应用指明位图中的所有像素都已知不透明 (false),或者某些像素可能包含非不透明的 Alpha 值 (true)。请注意,对于某些配置(例如 RGB_565),系统会忽略此调用,因为它不支持每像素的 Alpha 值。这意味着这是一个绘制提示,因为在某些情况下,已知不透明的位图的绘制速度可能比可能具有非不透明每像素 Alpha 值的位图更快。
    • getByteCount() 可获取位图的大小(以字节为单位)。
    • getGenerationId() 可让应用了解位图是否已修改(例如,为了进行缓存)。
    • sameAs(android.graphics.Bitmap) 可确定给定位图在尺寸、配置或像素数据方面是否与当前位图不同。
  • 设置相机位置和旋转角度

网络

  • 高性能 Wi-Fi 锁定
    • 新的高性能 Wi-Fi 锁可让应用保持高性能 Wi-Fi 连接,即使设备屏幕关闭也是如此。长时间流式传输音乐、视频或语音的应用可以获得高性能 Wi-Fi 锁,以确保即使屏幕关闭也能确保流式传输性能。由于耗电量更高,因此当需要长时间运行时,应用应获取高性能 Wi-Fi 连接。

      如需创建高性能锁,请在对 createWifiLock() 的调用中传递 WIFI_MODE_FULL_HIGH_PERF 作为锁定模式。

  • 更多流量统计信息
    • 应用现在可以使用 TrafficStats 中的新方法访问有关更多类型网络使用情况的统计信息。应用可以使用这些方法获取 UDP 统计信息、数据包计数、TCP 传输/接收载荷字节以及给定 UID 的段。
  • SIP 身份验证用户名

内容下载管理器

IME 框架

媒体

  • 新的流媒体音频格式
    • 媒体框架增加了对原始 ADTS AAC 内容的内置支持以改进流式音频,并支持 FLAC 音频,以提供最优质(无损)压缩音频内容。如需了解详情,请参阅支持的媒体格式文档。

对已停止的应用启动控制

从 Android 3.1 开始,系统的软件包管理器会跟踪处于停止状态的应用,并提供一种方式来控制其从后台进程和其他应用启动。

请注意,应用的停止状态与 Activity 的停止状态不同。系统会分别管理这两种停止状态。

平台定义了两个新的 intent 标志,用于让发送者指定是否应允许相应 intent 激活已停止的应用中的组件。

如果这两个标志均未在 intent 中定义,则默认行为是在潜在目标列表中包含已停止应用的过滤器。

请注意,系统会将 FLAG_EXCLUDE_STOPPED_PACKAGES 添加到所有广播 intent。这样做是为了防止来自后台服务的广播无意中或不必要地启动已停止的应用的组件。后台服务或应用可以替换此行为,方法是向广播 intent 添加 FLAG_INCLUDE_STOPPED_PACKAGES 标志,以便允许这些 intent 激活已停止的应用。

首次安装但尚未启动应用以及被用户手动停止(在“管理应用”中)时,应用会处于停止状态。

关于应用首次启动和升级的通知

平台通过两项新的 intent 操作添加了经过改进的应用首次启动通知和升级通知:

  • ACTION_PACKAGE_FIRST_LAUNCH - 当某个应用首次启动时(即首次脱离停止状态时),该参数会发送到应用的安装程序软件包。该数据包含软件包名称。
  • ACTION_MY_PACKAGE_REPLACED - 通知应用它已更新,有新版本安装到了现有版本上。此信息只会发送到被替换的应用。不包含任何额外数据。如需接收它,请为此操作声明一个 intent 过滤器。您可以使用 intent 触发代码,以便在升级后使应用恢复到正常运行状态。

    此 intent 会直接发送给应用,但前提是应用在处于启动状态(而非停止状态)时升级。

核心实用程序

  • LRU 缓存
    • 新的 LruCache 类可让您的应用从高效缓存中受益。应用可以使用该类缩短从网络计算或下载数据所花的时间,同时保持缓存数据的合理内存占用。LruCache 是一种缓存,可对数量有限的值进行强引用。每次访问值时,该值都会被移到队列的开头。当某个值被添加到填满缓存时,该队列末尾的值会被逐出,并可能符合垃圾回收的条件。
  • 文件描述符:int

WebKit

  • 文件方案 Cookie
    • CookieManager 现在支持使用 file: URI 架构的 Cookie。在构造 WebViewCookieManager 的实例之前,您可以使用 setAcceptFileSchemeCookies() 启用/停用对文件方案 Cookie 的支持。在 CookieManager 实例中,您可以通过调用 allowFileSchemeCookies() 检查是否已启用文件方案 Cookie。
  • 登录请求通知
    • 为了支持 Android 3.0 中引入的浏览器自动登录功能,新的 onReceivedLoginRequest() 方法会通知主应用用户的自动登录请求已处理。
  • 移除了类和接口
    • 从公共 API 中移除了多个类和接口(之前处于已废弃状态)。如需了解详情,请参阅 API 差异报告

浏览器

浏览器应用添加了以下功能来支持 Web 应用:

  • 支持以内嵌方式播放 HTML5 <video> 标记中嵌入的视频。播放尽可能采用硬件加速。
  • 为所有网站(移动版和桌面版)添加对固定位置元素的支持。

新功能常量

平台添加了新的硬件功能常量,开发者可以在应用清单中声明这些常量,以便向 Google Play 等外部实体告知应用要求此版本平台支持的新硬件功能。开发者会在 <uses-feature> 清单元素中声明这些常量以及其他功能常量。

Google Play 会根据 <uses-feature> 清单元素中声明的功能来过滤应用。如需详细了解如何在应用清单中声明功能,请参阅 Google Play 过滤器

API 差异报告

如需详细了解 Android 3.1(API 级别 12)中的所有 API 变更,请参阅 API 差异报告

API 级别

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

如需在应用中使用 Android 3.1 中引入的 API,您需要根据 Android 3.1 SDK 平台中提供的 Android 库编译应用。根据您的需求,您可能还需要向应用清单中的 <uses-sdk> 元素添加一个 android:minSdkVersion="12" 属性。

如需了解详情,请参阅什么是 API 级别?