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.ThreadPolicy 和 StrictMode.VmPolicy 保存您定义并应用于线程和虚拟机实例的政策。

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

界面框架

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

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

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

    • 超大屏幕

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

    图形

    内容提供程序

    • 新增了用于设置闹钟或处理闹钟的 AlarmClock 提供程序类。该提供程序包含 ACTION_SET_ALARM intent 操作和 extra，可用于启动 activity 以在闹钟应用中设置新闹钟。希望接收 SET_ALARM intent 的应用应创建一个需要 SET_ALARM 权限的 activity。希望创建新闹钟的应用应使用 Context.startActivity()，这样用户就可以选择要使用的闹钟应用。
    • MediaStore 支持新的 intent 操作 PLAY_FROM_SEARCH，借助该操作，应用可搜索音乐媒体，并尽可能从结果中自动播放内容。例如，应用可能会在发出用于收听音乐的语音识别命令时触发此 intent。
    • MediaStore 还添加了一个新的 MEDIA_IGNORE_FILENAME 标志，用于告知媒体扫描程序忽略其所在目录及其子目录中的媒体。开发者可以使用此方法来避免在图库中显示图形，同时阻止应用的声音和音乐显示在音乐应用中。
    • Settings 提供程序添加了新的 Activity 操作 APPLICATION_DETAILS_SETTINGS 和 MANAGE_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 卡。

    文件包管理器

    电话

    对 activity 生命周期和窗口的原生访问

    Android 2.3 向使用原生代码的应用提供了一系列 API。此类应用感兴趣的框架类包括：

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