Android 2.3 API

API 级别9

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

API 概览

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

基于 SIP 的 VoIP

该平台现在包含 SIP 协议堆栈和框架 API,支持开发者构建互联网电话应用。利用该 API,应用可以提供语音通话功能,而无需管理会话、传输级通信或音频,这些内容均由平台的 SIP API 和服务以透明方式进行处理。

SIP API 在 android.net.sip 软件包中提供。关键类为 SipManager,应用使用该类来设置和管理 SIP 配置文件,然后发起语音通话和接听语音通话。建立语音通话后,应用可以执行将通话静音、开启扬声器模式、发送 DTMF 提示音等操作。应用还可以使用 SipManager 创建通用 SIP 连接。

平台的底层 SIP 堆栈和服务是否可以在设备上提供,由制造商和关联运营商自行决定。因此,在向用户提供通话功能之前,应用应使用 isApiSupported() 方法检查是否提供 SIP 支持。

如需使用 SIP API,应用必须通过在其清单文件中声明 <uses-permission android:name="android.permission.INTERNET"><uses-permission android:name="android.permission.USE_SIP"> 向用户请求权限。

此外,开发者还可以在 Google Play 上请求过滤,这样,如果设备不包含平台 SIP 堆栈和服务的用户就无法发现其应用。如需请求过滤,请将 <uses-feature android:name="android.software.sip" android:required="true"><uses-feature android:name="android.software.sip.voip"> 添加到应用清单中。

如需了解详情,请参阅 SIP 开发者指南。

近距离无线通信 (NFC)

Android 2.3 包含一个 NFC 堆栈和框架 API,可让开发者读取在用户轻触支持 NFC 的设备时发现的 NDEF 标签,以标记嵌入在贴纸、智能海报甚至其他设备中的元素。

平台提供与设备硬件协同工作的底层 NFC 服务,以便在标签进入检测范围时发现标签。发现标签后,平台会广播 intent,并将标签的 NDEF 消息作为 extra 附加到 intent 中。应用可以创建 intent 过滤器,来识别和处理目标标记和消息。例如,在按 intent 接收标签后,应用会提取、存储、提醒用户或以其他方式处理 NDEF 消息。

NFC API 可在 android.nfc 软件包中找到。关键类包括:

  • NfcAdapter:表示设备上的 NFC 硬件。
  • NdefMessage:表示 NDEF 数据消息,这是在设备和标签之间传输数据的“记录”的标准格式。应用可以从 ACTION_TAG_DISCOVERED intent 接收这些消息。
  • NdefRecord,在 NdefMessage 中传递,用于描述共享的数据类型,并携带数据本身。

NFC 通信依赖于设备硬件中的无线技术,因此平台是否支持特定设备上的 NFC 功能由其制造商决定。如需确定当前设备是否支持 NFC,应用可以调用 isEnabled() 来查询 NfcAdapter。但是,无论底层硬件支持如何,NFC API 始终存在。

如需使用 NFC API,应用必须通过在其清单文件中声明 <uses-permission android:name="android.permission.NFC"> 向用户请求权限。

此外,开发者可以在 Google Play 上请求过滤,这样不支持 NFC 的设备的用户就无法发现其应用。如需请求过滤,请将 <uses-feature android:name="android.hardware.nfc" android:required="true"> 添加到应用的清单中。

如需查看使用 NFC API 的示例应用,请参阅 NFCDemo

陀螺仪和其他传感器

Android 2.3 增加了对几种新的传感器读数类型(陀螺仪、旋转矢量、线性加速度、重力和气压计)的平台和 API 支持。开发者可以使用新的传感器读数来创建能够快速、流畅地响应设备位置和动作的精确变化的应用。Sensor API 会向感兴趣的应用报告陀螺仪和其他传感器的更改,无论这些应用是在应用框架上运行,还是在原生代码中运行。

请注意,任何给定设备上可用的一组特定硬件传感器因设备制造商的决定而有所不同。

开发者可以在 Google Play 上请求过滤,这样,如果设备不提供陀螺仪传感器,用户就无法发现其应用。为此,请将 <uses-feature android:name="android.hardware.sensor.gyroscope" android:required="true"> 添加到应用清单中。

如需详细了解 API,请参阅 Sensor

支持多个摄像头

应用现在可以利用设备上可用的任何相机来拍摄照片或视频。Camera 允许应用查询可用的摄像头数量以及每个摄像头的独特特征。

如需查看用于访问前置摄像头的示例代码,请参阅 ApiDemos 示例应用中的 CameraPreview.java

Camera API 还添加了以下功能:

可混合的音效

平台的媒体框架新增了对单音轨或全局音效的支持,包括低音增强、耳机虚拟化、均衡和混响。

如需查看音效的示例代码,请参阅 ApiDemos 示例应用中的 AudioFxDemo.java

媒体框架还添加了:

  • 新增对 JPEG 文件的 EXIF 元数据中的海拔标签的支持。新增了 getAltitude() 方法,用于检索 EXIF 海拔高度标签的值。
  • 新的 setOrientationHint() 方法可让应用在视频拍摄期间告知 MediaRecorder 的方向。

下载管理器

平台包含新的 DownloadManager 系统服务,用于处理长时间运行的 HTTP 下载。应用可以请求将 URI 下载到特定目标文件。DownloadManager 将在后台进行下载,处理 HTTP 交互,并在失败后或者连接发生变化和系统重新启动后重新尝试下载。

  • 应用可以通过调用 getSystemService(String) 并传递 DOWNLOAD_SERVICE 来获取 DownloadManager 类的实例。通过此 API 请求下载的应用应为 ACTION_NOTIFICATION_CLICKED 注册广播接收器,以便在用户点击通知中或“下载内容”界面中正在运行的下载内容时进行适当处理。
  • 通过 DownloadManager.Request 类,应用可以提供请求新下载所需的所有信息,例如请求 URI 和下载目标位置。请求 URI 是唯一的必需参数。请注意,默认下载目标位置是一个共享卷,如果系统需要回收空间以供系统使用,可以删除该文件。如需永久性存储下载内容,请在外部存储空间中指定下载目标位置(请参阅 setDestinationUri(Uri))。
  • DownloadManager.Query 类提供的方法可让应用查询和过滤活跃下载内容。

StrictMode

为了帮助开发者监控和提升其应用的性能,该平台提供了一个名为 StrictMode 的新系统设施。在应用中实现时,StrictMode 会捕获可能会降低应用性能的意外磁盘或网络活动,并通知开发者,比如在应用的主线程上发生活动(接收界面操作并同时显示动画)。开发者可以评估 StrictMode 中发生的网络和磁盘使用问题,并根据需要进行纠正,让主线程响应更快,并防止向用户显示 ANR 对话框。

  • StrictMode 是核心类,也是与系统和虚拟机的主要集成点。该类提供了便捷的方法,用于管理适用于实例的线程和虚拟机政策。
  • StrictMode.ThreadPolicyStrictMode.VmPolicy 保存您定义并应用于线程和虚拟机实例的政策。

如需详细了解如何使用 StrictMode 优化应用,请参阅 android.os.StrictMode 中的类文档和示例代码。

界面框架

  • 支持滚动
    • 在 View 和 widget 中新增对滚动回弹的支持。在 View 中,应用可以为给定视图启用/停用滚动回弹,设置过滚动模式,控制滚动回弹距离,以及处理滚动回弹的结果。
    • 在 widget 中,应用可以控制滚动特征,例如动画、弹跳和滚动距离。如需了解详情,请参阅 android.view.Viewandroid.widget.OverScroller
    • ViewConfiguration 还提供 getScaledOverflingDistance()getScaledOverscrollDistance() 方法。
    • <ListView> 元素新增了 overScrollModeoverScrollFooteroverScrollHeader 属性,用于控制滚动行为。
  • 支持触摸过滤
    • 新增对触摸过滤的支持,可让应用提高提供对敏感功能的访问权限的 View 的安全性。例如,触摸过滤适用于确保用户操作(例如授予权限请求、购买或点击广告)的安全性。如需了解详情,请参阅查看类文档
    • 为视图元素新增了 filterTouchesWhenObscured 属性,该属性用于声明当视图的窗口被另一个可见窗口遮挡时是否过滤触摸操作。设置为 "true" 时,每当视图窗口上方出现消息框、对话框或其他窗口时,视图都不会接收触摸操作。如需了解详情,请参阅查看安全文档

    如需查看轻触过滤的示例代码,请参阅 ApiDemos 示例应用中的 SecureView.java

  • 改进了事件管理
    • 为输入事件新增了 InputEvent 基类。该类提供的方法可让应用确定事件的含义,例如通过查询发起事件的 InputDevice。KeyEventMotionEventInputEvent 的子类。
    • 为输入设备新增了 InputDevice 基类。该类会存储特定输入设备的功能信息,并提供相关方法,以便应用确定如何解读来自输入设备的事件。
  • 改进了动作事件
    • MotionEvent API 已扩展为包含“指针 ID”信息,应用可通过该信息跟踪各个手指上下移动的轨迹。该类添加了各种方法,可让应用高效处理动作事件。
    • 输入系统现在具有相应的逻辑,可使用新的指针 ID 信息生成动作事件,并在新指针按下时合成标识符。系统会在动作事件期间单独跟踪多个指针 ID,并通过在上一组指针和下一组指针之间的距离处评估指针,以确保指针的连续性。
  • 文本选择控件
    • 借助新的 setComposingRegion 方法,应用可将文本区域标记为撰写文本,同时保持当前样式。getSelectedText 方法可将所选文本返回给应用。BaseInputConnectionInputConnectionInputConnectionWrapper 中提供了这些方法。
    • <TextView> 新增了 textSelectHandletextSelectHandleLefttextSelectHandleRighttextSelectHandleWindowStyle 属性,用于引用将用于显示文本选择锚点和所包含窗口样式的可绘制对象。
  • 活动控件
  • 通知文本和图标样式
  • 超大屏幕

    平台现在支持超大屏幕尺寸,例如平板电脑设备上可能的尺寸。开发者可以通过在其清单文件中添加 <supports screens ... android:xlargeScreens="true"> 元素,指明其应用支持超大屏幕尺寸。应用可以使用新的资源限定符 xlarge 来标记超大屏幕专用资源。如需详细了解如何支持超大尺寸和其他屏幕尺寸,请参阅支持多种屏幕

    显卡

    内容提供程序

    • 新增了用于设置闹钟或处理闹钟的 AlarmClock 提供程序类。该提供程序包含一个 ACTION_SET_ALARM intent 操作和可用于启动 activity 以在闹钟应用中设置新闹钟的 extra。希望接收 SET_ALARM intent 的应用应创建一个需要 SET_ALARM 权限的 activity。希望创建新闹钟的应用应使用 Context.startActivity(),以便用户可以选择要使用的闹钟应用。
    • MediaStore 支持新的 intent 操作 PLAY_FROM_SEARCH,可让应用搜索音乐媒体,并尽可能自动播放结果中的内容。例如,应用可能会在发出语音识别命令来收听音乐时触发此 intent。
    • MediaStore 还添加了一个新的 MEDIA_IGNORE_FILENAME 标志,用于指示媒体扫描器忽略所在目录及其子目录中的媒体。开发者可以使用此方法来避免在 Gallery 中显示图形,同时阻止应用的声音和音乐显示在 Music 应用中。
    • Settings 提供程序添加了新的 Activity 操作 APPLICATION_DETAILS_SETTINGSMANAGE_ALL_APPLICATIONS_SETTINGS,可让应用显示特定应用的详情屏幕或显示“管理应用”屏幕。
    • ContactsContract 提供程序添加了 ContactsContract.CommonDataKinds.SipAddress 数据类型,用于存储联系人的 SIP(互联网电话)地址。

    位置信息

    • LocationManager 现在会根据 WorkSource(用于标识应用的系统管理的类)跟踪导致唤醒锁定或 Wi-Fi 锁定的应用请求。

      LocationManager 会跟踪所有请求定期更新的客户端,并在设置这些客户端的最短更新时间时,以 WorkSource 参数的形式将其告知提供程序。网络位置信息提供程序使用 WorkSource 跟踪应用发起的唤醒和 Wi-Fi 锁定,并将其添加到“管理应用”中报告的应用的电池用量中。

    • LocationManager 添加了几种新方法,这些方法可让 activity 寄存器根据指定条件接收定期或一次性位置信息更新(见下文)。
    • 新的 Criteria 类让应用可以指定一组用于选择位置信息提供程序的条件。例如,提供商可以根据精确度、耗电量、报告海拔高度、速度、方位和货币成本的能力进行排序。

    存储

    • Android 2.3 添加了一个支持 OBB(不透明二进制 blob)文件的新 StorageManager。尽管 Android 2.3 中提供了对 OBB 的平台支持,但用于创建和管理 OBB 文件的开发工具要到 2011 年初才可用。
    • Android 2.3 平台增加了对不包含 SD 卡的设备的官方支持(尽管它在没有实体 SD 卡的情况下提供虚拟 SD 卡分区)。isExternalStorageRemovable() 是一种便捷方法,可让应用确定是否存在物理 SD 卡。

    文件包管理器

    telephony

    对 activity 生命周期、窗口的原生访问权限

    Android 2.3 向使用原生代码的应用提供了大量 API。此类应用感兴趣的框架类包括:

    • NativeActivity 是一种新型 Activity 类,其生命周期回调直接在原生代码中实现。NativeActivity 及其底层原生代码在系统中就像运行其他 activity 一样运行。具体而言,它们在 Android 应用的系统进程中运行,在应用的主界面线程上执行,而且它们会接收与其他 activity 相同的生命周期回调。
    • 新的 InputQueue 类和回调接口允许原生代码管理事件队列。
    • 新的 SurfaceHolder.Callback2 接口允许原生代码管理 SurfaceHolder
    • Window 中新增了 takeInputQueuetakeSurface() 方法,可让原生代码管理事件和 Surface。

    如需了解如何使用原生代码或下载 NDK 的完整信息,请参阅 Android NDK 页面。

    Dalvik 运行时

    新的清单元素和属性

    • <supports-screens> 元素新增了 xlargeScreens 属性,用于指明应用是否支持超大屏这种设备类型。如需了解详情,请参阅支持多种屏幕
    • <activity> 元素的 android:screenOrientation 属性的新值:
      • "reverseLandscape" - 此 activity 希望屏幕横向显示,即与正常横向显示方向相反。
      • "reversePortrait" - activity 希望屏幕为纵向,并使其方向与正常纵向方向相反。
      • "sensorLandscape" - activity 希望屏幕横向显示,但可以使用传感器更改屏幕朝向的方向。
      • "sensorPortrait" - activity 希望屏幕纵向显示,但可以使用传感器更改屏幕朝向的方向。
      • "fullSensor" - 屏幕方向由物理方向传感器确定:显示内容将根据用户手持设备的方向旋转。这样,无论设备在正常情况下如何旋转,即可实现 4 种可能的旋转中的任何一种(例如,某些设备通常不会使用 180 度旋转)。

    新权限

    • com.android.permission.SET_ALARM - 允许应用广播 intent,以便为用户设置闹钟。处理 SET_ALARM intent 操作的 activity 应需要此权限。
    • android.permission.USE_SIP - 允许应用使用 SIP API 拨打或接听互联网电话。
    • android.permission.NFC - 允许应用使用 NFC API 读取 NFC 标签。

    新功能常量

    平台添加了几项新的硬件功能,开发者可以在应用清单中将其声明为应用所需的功能。这样一来,开发者便可以控制应用在 Google Play 上发布时如何过滤。

    有关如何声明功能并使用功能进行过滤的完整信息,请参阅 <uses-feature> 的文档。

    API 差异报告

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

    API 级别

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

    如需在应用中使用 Android 2.3 中引入的 API,您需要根据 Android 2.3 SDK 平台中提供的 Android 库编译应用。您可能还需要向应用清单中的 <uses-sdk> 元素中添加一个 android:minSdkVersion="9" 属性,具体取决于您的需求。如果您的应用设计为仅在 Android 2.3 及更高版本上运行,则声明该属性会阻止应用安装在较低版本的平台上。

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