Android 3.1 API

API 级别：12

Android 3.1 平台面向开发者 (HONEYCOMB_MR1) 作为 可下载组件该可下载平台包括： Android 库和系统映像，以及一组模拟器皮肤和 。可下载平台不包含任何外部库。

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

API 概览

以下各部分从技术层面简要介绍了面向开发者的新变化 包括自从 Android 3.1 以来 先前版本。

USB API

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

堆栈和 API 会根据不同的内容，区分两种基本的 USB 硬件类型， Android 设备是充当主机还是外部硬件 是主讲人：

  • USB 设备是一种已连接的硬件，具体取决于 充当主机的 Android 设备。例如，大多数输入设备、鼠标 操纵杆是 USB 设备，还有许多摄像头、集线器等。
  • USB 配件是指具有 USB 功能的已连接硬件 主机控制器、供电 通过 USB 连接的 Android 设备，各种外围设备都可以作为 从机器人控制器到音乐器材、健身自行车 等等。

对于这两种类型（USB 设备和 USB 配件），使用 平台的 USB API 支持通过 intent 广播发现（在连接或连接时） 以及标准接口、端点和传输模式 （控制、批量和中断）。

软件包 android.hardware.usb 中提供了这些 USB API。通过 核心类是 UsbManager，它提供 帮助程序方法来识别问题并与之通信， USB 设备和 USB 配件。应用可以获取 UsbManager，然后查询所挂接的 或配件，然后与它们通信或管理它们。 UsbManager 还声明了 系统广播，以在连接了 USB 设备或配件时发出公告， 已分离。

其他类包括：

  • UsbDevice，一个表示外部资源的类 作为 USB 设备连接的硬件（其中 Android 设备充当 主机）。
  • UsbAccessory，表示外部硬件 作为 USB 主机连接（将 Android 设备用作 USB 设备）。
  • UsbInterface 和 UsbEndpoint，它们支持对标准 USB 的访问 接口和端点。
  • UsbDeviceConnection 和 UsbRequest，用于发送和接收数据和控制 向 USB 设备发送或从其接收消息。
  • UsbConstants，它为以下对象提供常量： 端点类型、设备类等等

请注意，尽管 USB 堆栈内置于平台中，但实际支持 特定设备上的 USB 主机模式和开放配件模式由 其制造商。具体来说，主机模式依赖于相应的 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 测试和导弹 启动器

MTP/PTP API

Android 3.1 公开了一个新的 MTP API，可让应用直接交互 以及已连接的摄像头和其他 PTP 设备。新的 API 让 用于在安装和移除设备时接收通知， 管理这些设备上的文件和存储空间，以及将文件和元数据传输到 MTP API 实现 PTP（图片传输协议）子集 媒体传输协议 (MTP) 规范要求。

MTP API 包含在 android.mtp 软件包中， 这些类：

  • MtpDevice封装了 MTP 设备 通过 USB 主机总线进行连接应用可以实例化 然后使用其方法来获取有关设备 以及打开连接和传输数据。 其中一些方法包括： <ph type="x-smartling-placeholder">
      </ph>
    • getObjectHandles() 会返回设备上符合以下条件的所有对象的句柄列表： 与指定的格式和父项匹配。要获取有关某个对象的信息， 应用可以向 getObjectInfo() 传递句柄。
    • importFile() 允许应用将对象数据复制到外部文件 storage。此调用可能会阻塞任意时间，具体取决于 设备的数据大小和速度，因此 线程。
    • open() 允许应用打开已连接的 MTP/PTP 设备。
    • 退货费用 getThumbnail() 对象的缩略图（以字节数组表示）。
  • MtpStorageInfo 包含有关存储空间的信息 单位，与上文所述的 StorageInfo 数据集相对应 MTP 规范的第 5.2.2 节。类中的方法可让应用 获取存储单元的说明字符串、可用空间、最大存储容量、 存储 ID 和卷标识符。
  • MtpDeviceInfo 存储有关 MTP 设备的信息 与 MTP 第 5.1.1 节中所述的 DeviceInfo 数据集对应 规范通过该类中的方法，应用可以获取设备的 制造商、型号、序列号和版本
  • MtpObjectInfo 存储有关所存储对象的信息 MTP 设备上，对应于第 8 节中描述的 ObjectInfo 数据集 5.3.1 MTP 规范。通过该类中的方法，应用可以获取 对象的大小、数据格式、关联类型、创建日期和缩略图 信息。
  • MtpConstants 提供用于声明 MTP 文件的常量 格式代码、关联类型和保护措施状态。

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

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

为了处理鼠标、滚轮和轨迹球输入，该平台支持 两项新的动作事件操作：

  • ACTION_SCROLL，用于描述指针 非触摸滚动操作（例如鼠标滚轮）所处的位置， 事件。在 MotionEvent 中，AXIS_HSCROLL 轴和 AXIS_VSCROLL 轴的值指定相对滚动
  • ACTION_HOVER_MOVE，报告当前 以及任何中间操作按钮 自上次 HOVER_MOVE 事件以来获得的积分。悬停鼠标进入和退出 通知。

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

描述来自这些新来源的动作事件以及来自鼠标的动作事件 和轨迹球，平台现在在 MotionEvent 上定义轴代码，类似于在 KeyEvent 上定义键码。新的操纵杆轴代码 游戏控制器包括 AXIS_HAT_X、AXIS_HAT_Y、AXIS_RTRIGGER、AXIS_ORIENTATION、AXIS_THROTTLE以及其他许多人。 现有的 MotionEvent 轴由 AXIS_X、AXIS_Y、 AXIS_PRESSURE、AXIS_SIZE、AXIS_TOUCH_MAJOR、AXIS_TOUCH_MINOR、AXIS_TOOL_MAJOR、AXIS_TOOL_MINOR 和 AXIS_ORIENTATION。

此外，MotionEvent 还定义了一些通用的 当框架不知道如何映射 特定轴。特定设备可以使用通用轴代码传递自定义 运动数据传递给应用。有关轴及其用途的完整列表 请参阅 MotionEvent 类文档。

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

可以使用特殊的访问器方法来检索某些轴。例如： 应用可以调用 getX()，而不是调用 getAxisValue()。具有内置访问器的轴包括 AXIS_X、AXIS_Y、 AXIS_PRESSURE、AXIS_SIZE、AXIS_TOUCH_MAJOR、AXIS_TOUCH_MINOR、AXIS_TOOL_MAJOR、AXIS_TOOL_MINOR 和 AXIS_ORIENTATION。

每个输入设备都有一个由系统分配的唯一 ID，并且还可以提供 多个来源。当设备提供多个来源时，多个来源 可以使用同一轴提供轴数据。例如，一个触摸事件 使用 X 轴获取屏幕位置数据，而操纵杆 事件将使用 X 轴作为摇杆位置 。因此，应用解释轴 根据这些值的来源确定这些值。处理动作时 事件，应用应使用 InputDevice 上的方法 类来确定设备或来源支持的轴。具体而言， 应用可以使用 getMotionRanges() 查询设备的所有轴或给定的所有轴 来源。在这两种情况下， InputDevice.MotionRange 对象会指定 每个轴值

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

平台会以不同的方式分派通用动作事件，具体取决于 事件来源类。SOURCE_CLASS_POINTER 个事件 会转到指针下方的View，与触摸方式类似 事件有效。所有其他项都会转到当前聚焦的 View。 例如，这意味着 View 必须获得焦点才能 用于接收操纵杆事件。如果需要，应用可在 可改为在 activity 或对话框级别实现 onGenericMotionEvent()。

查看使用操纵杆运动的示例应用 事件，请参阅 GameControllerInput 和 GameView。

RTP API

Android 3.1 向其内置的 RTP（实时传输协议）公开了一个 API 应用可用于管理按需数据或交互式数据 。具体来说，提供 VoIP、一键通话、会议 和音频流式传输可以使用该 API 发起会话，并传输或接收会话、 允许通过任何可用网络传输数据

android.net.rtp 软件包中提供了 RTP API。等级 包括：

  • RtpStream 是发送和接收数据的流的基类 通过 RTP 接收带有媒体载荷的网络数据包。
  • AudioStream 是 RtpStream 的子类，用于通过 RTP 承载音频载荷。
  • AudioGroup，一个本地音频中心，用于管理和 设备扬声器、麦克风和 AudioStream 混音。
  • AudioCodec：用于存储一系列编解码器 为 AudioStream 定义的变量。

为了支持音频会议和类似用途，应用将 两类作为流的端点：

最简单的用法涉及单个远程端点和本地端点。 如需了解更复杂的用法，请参阅 AudioGroup。

要使用 RTP API，应用必须通过 正在声明<uses-permission android:name="android.permission.INTERNET"> 。如需获取设备麦克风，还需具备 <uses-permission android:name="android.permission.RECORD_AUDIO"> 权限。

可调整大小的应用微件

从 Android 3.1 开始，开发者可以将其主屏幕微件设为 可调整大小 — 水平、垂直或双轴。用户触摸 微件以显示其大小调整手柄，然后拖动水平和/或垂直 用于更改布局网格上大小的手柄。

开发者可以通过定义一个 widget 的 AppWidgetProviderInfo 元数据中的 resizeMode 属性。 resizeMode 属性包含“Horizontal”、“vertical”和“none”。 如需将微件声明为在水平和垂直方向上均可调整大小，请提供相应的值 "水平|垂直"。

示例如下：

<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>

如需详细了解主屏幕微件，请参阅应用微件 文档。

动画框架

  • 新增了 ViewPropertyAnimator 类 <ph type="x-smartling-placeholder">
  • 动画背景颜色 <ph type="x-smartling-placeholder">
  • 从 ViewAnimator 获取动画分数 <ph type="x-smartling-placeholder">
      </ph>
    • 全新getAnimatedFraction() 方法 可让您获取当前的动画比例，即已播放/插入动画的时长， 最近一次帧更新中使用的分数（来自 ValueAnimator）。

界面框架

图形

  • 用于管理位图的帮助程序 <ph type="x-smartling-placeholder">
      </ph>
    • setHasAlpha(boolean) 允许应用指示： 而位图中的所有像素都已知是不透明 (false) 或 像素可以包含非不透明 Alpha 值 (true)。请注意，对于某些配置（例如 设置为 RGB_565），此调用会被忽略，因为它不支持每像素 alpha 值 值。这只是一个绘制提示，在某些情况下， 不透明的绘制速度比不透明 每像素的 alpha 值。
    • getByteCount() 获取位图的大小， 字节。
    • getGenerationId()可让应用查找 指示位图是否已被修改（例如用于缓存）。
    • sameAs(android.graphics.Bitmap)可确定 给定位图是否与当前位图不同 或像素数据
  • 设置相机位置和旋转 <ph type="x-smartling-placeholder">

网络

  • 高性能 Wi-Fi 锁定 <ph type="x-smartling-placeholder">
      </ph>
    • 全新的高性能 Wi-Fi 锁定可让应用 高性能 Wi-Fi 连接。 长时间流式传输音乐、视频或语音的应用程序可以获取 高性能 Wi-Fi 锁定功能，可确保即使屏幕关闭， 已关闭。由于这会耗费更多电量，因此应用应获取 高性能 Wi-Fi（当需要长时间处于活动状态时） 连接。

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

  • 更多流量统计信息 <ph type="x-smartling-placeholder">
      </ph>
    • 应用现在可以访问更多网络使用情况统计信息 使用 TrafficStats 中的新方法。应用可以使用 获取 UDP 统计信息、数据包计数、TCP 传输/接收有效负载字节的方法， 与给定 UID 对应的细分受众群。
  • SIP 身份验证用户名 <ph type="x-smartling-placeholder">

内容下载管理器

IME 框架

媒体

  • 新的流式音频格式 <ph type="x-smartling-placeholder">
      </ph>
    • 媒体框架添加了对原始 ADTS AAC 内容的内置支持， 改进了流式音频，并支持 FLAC 音频，以呈现最高质量 （无损）压缩音频内容。请参阅支持的媒体格式 文档。

已停止时启动控件 应用

从 Android 3.1 开始，系统的软件包管理器会跟踪 此类应用提供一种控制 从后台进程和其他应用启动。

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

平台定义了两个新的 intent 标志，让发送方可以指定 是否应允许 Intent 激活已停止状态的组件 应用。

如果 intent 中未定义这两个标记或其中任一标记，则默认 将已停止应用的过滤器添加到 潜在目标。

请注意，系统会将 FLAG_EXCLUDE_STOPPED_PACKAGES 添加到所有广播 intent。这样就可以阻止来自后台服务的广播 无意中或不必要地启动已停止的应用的组件。 后台服务或应用程序可以通过添加 要广播的 FLAG_INCLUDE_STOPPED_PACKAGES 标志 intent 激活已停止的应用。

应用在首次安装时处于停止状态，但未安装 以及何时被用户手动停止（在“管理”中 应用）。

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

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

  • ACTION_PACKAGE_FIRST_LAUNCH - 已发送至 首次启动时应用的安装程序软件包 （即首次退出停止状态时）。数据 包含软件包的名称。
  • ACTION_MY_PACKAGE_REPLACED - 通知 更新过（安装了新版本的应用）的应用 现有版本。此邮件只会发送到已被替换的应用。它 未包含任何其他数据。若要接收它，请声明一个 intent 过滤器 执行此操作。您可以使用 intent 触发代码， 升级后的应用恢复到正确的运行状态。

    系统会将此 Intent 直接发送到应用，但仅当 在启动状态（非停止状态）时升级。

核心实用程序

  • LRU 缓存 <ph type="x-smartling-placeholder">
      </ph>
    • 新的 LruCache 类可让您的应用受益 从高效缓存中受益应用程序可以使用 类来减少花费的时间 计算或下载数据，同时保持合理的 缓存数据的内存占用量。LruCache 是缓存 对有限数量的值进行强引用。每次将值设为 则被移到队列头部。将值添加到完整 则队列末尾的值会被逐出， 垃圾回收。
  • 文件描述符为 int <ph type="x-smartling-placeholder">

WebKit

  • 文件架构 Cookie <ph type="x-smartling-placeholder">
      </ph>
    • CookieManager现在支持使用 该 file: URI scheme。您可以使用 setAcceptFileSchemeCookies() 执行以下操作： 在构造实例之前，启用/停用对文件架构 Cookie 的支持 （共 WebView 或 CookieManager）。在 CookieManager 实例，您可以检查文件架构 Cookie 可通过调用 allowFileSchemeCookies() 启用。
  • 登录请求通知 <ph type="x-smartling-placeholder">
      </ph>
    • 为了支持 Android 3.0 中引入的浏览器自动登录功能， 新 onReceivedLoginRequest() 方法 通知主机 表明已处理用户的自动登录请求。
  • 移除的类和接口 <ph type="x-smartling-placeholder">
      </ph>
    • 之后，从公共 API 中移除了多个类和接口， 之前处于已弃用状态请参阅 API 差异报告。

浏览器

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

  • 支持内嵌播放 HTML5 中嵌入的视频 <video> 标记之间。播放会尽可能进行硬件加速。
  • 针对所有网站（移动网站和 桌面设备）。

新功能常量

平台添加了新的硬件功能常量，开发者可以声明这些常量， 应用清单中，以告知 Google 等外部实体 应用对新硬件功能的支持要求 不同组件开发者声明这些功能及其他功能 <uses-feature> 清单元素中的常量。

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

API 差异报告

如需详细了解 Android 3.1（API 级别 12)，请参阅 API 差异报告。

API 级别

Android 3.1 平台提供了 框架 API。Android 3.1 API 分配了整数标识符 - 12，即 存储在系统本身中。此标识符称为“API 级别”，允许 正确确定应用是否与 然后再安装应用程序。

要在您的应用中使用 Android 3.1 中引入的 API，请执行以下操作： 您需要根据此 API 中提供的 Android 库 Android 3.1 SDK 平台。您可以根据自己的需求 可能 还需要添加一个 android:minSdkVersion="12" 属性添加到应用的 <uses-sdk> 元素中， 清单。

有关详情，请参阅什么是 API 水平？