Android 2.3 API

API 級別： 9

對開發人員來說，Android 2.3 (GINGERBREAD) 平台可做為 Android SDK 的可下載元件。可下載的平台內含一個 Android 程式庫和系統映像檔，以及一組模擬器外觀等項目。如要開始針對 Android 2.3 進行開發或測試，請使用 Android SDK Manager 將平台下載至 SDK。

API 總覽

下列各節將提供 2.3 版開發人員最新消息的技術總覽，包括自舊版以來架構 API 的新功能和異動。

SIP 型 IP 網路語音傳遞技術

這個平台現在包含 SIP 通訊協定堆疊和架構 API，可讓開發人員建構網際網路電話應用程式。只要使用 API，應用程式就能提供語音通話功能，而不必管理工作階段、傳輸層級通訊或音訊，而這些功能會由平台的 SIP API 和服務公開處理。

您可以在 android.net.sip 套件中取得 SIP API。金鑰類別為 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 服務，可與裝置硬體搭配運作，以便在這些標記進入有效範圍內時進行探索。探索標記時，平台會透過廣播意圖通知應用程式，並將標記的 NDEF 訊息做為額外項目附加至意圖。應用程式可以建立意圖篩選器，以辨識及處理指定標記和訊息。例如，應用程式會在透過意圖收到標記後，擷取、儲存 NDEF 訊息、提醒使用者，或是以其他方式處理訊息。

您可以在 android.nfc 套件中取得 NFC API。主要類別如下：

  • NfcAdapter，代表裝置上的 NFC 硬體。
  • NdefMessage 代表 NDEF 資料訊息，這是「記錄」傳輸資料在裝置和標記之間傳輸的標準格式。應用程式可以從 ACTION_TAG_DISCOVERED 意圖接收這些訊息。
  • 在 NdefMessage 中提供 NdefRecord，用於說明要分享的資料類型，並運送資料本身。

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 支援。開發人員可以使用新的感應器讀數建立應用程式，快速流暢地回應裝置位置和動作的變化。無論應用程式是在應用程式架構或原生程式碼中，感應器 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 註冊廣播接收器，以便在使用者點選通知或下載 UI 中的執行下載時，妥善處理。
  • DownloadManager.Request 類別可讓應用程式提供要求新下載的所有必要資訊，例如要求 URI 和下載目的地。要求 URI 是唯一的必要參數。請注意，預設的下載目的地是共用磁碟區，在需要收回空間以供系統使用時，也可刪除您的檔案。若要永久儲存下載內容，請指定外部儲存空間的下載目的地 (請參閱 setDestinationUri(Uri))。
  • DownloadManager.Query 類別提供多種方法，讓應用程式查詢及篩選有效下載項目。

StrictMode (嚴格模式)

為協助開發人員監控及提升應用程式效能，該平台提供一個名為 StrictMode 的新系統功能。在應用程式中實作時，StrictMode 會擷取並通知開發人員，以免影響應用程式效能的意外磁碟或網路活動，例如發生在應用程式主執行緒 (接收 UI 作業和播放動畫) 上的活動。開發人員可以評估 StrictMode 中產生的網路和磁碟用量問題，並視需要加以修正，讓主執行緒更敏捷，避免向使用者顯示 ANR 對話方塊。

  • StrictMode 是核心類別，是系統和 VM 的主要整合點。這個類別提供管理執行緒和適用於執行個體的 VM 政策的便利方法。
  • StrictMode.ThreadPolicy 和 StrictMode.VmPolicy 會保留您定義並套用至執行緒和 VM 執行個體的政策。

如要進一步瞭解如何使用 StrictMode 最佳化應用程式，請參閱 android.os.StrictMode 中的類別說明文件和程式碼範例。

UI 架構

  • 支援過度捲動
    • 新增在「檢視畫面」和「小工具」中對過度捲動功能的支援。在 View 中，應用程式可以啟用/停用特定檢視區塊的過度捲動、設定遮蔽模式、控制過度捲動距離，以及處理過度捲動的結果。
    • 在小工具中，應用程式可控制捲動的特性，例如動畫、彈簧及過度捲動距離。詳情請參閱 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。系統會在動作事件期間單獨追蹤多個指標 ID，並且評估最後一組指標和下一組指標之間的距離，以確保指標的連續性。
  • 文字選取控制項
    • 新的 setComposingRegion 方法可讓應用程式將文字區域標示為撰寫文字，維持目前的樣式。getSelectedText 方法會將選取的文字傳回應用程式。BaseInputConnection、InputConnection 和 InputConnectionWrapper 提供方法。
    • 為 <TextView> 新增 textSelectHandle、textSelectHandleLeft、textSelectHandleRight 和 textSelectHandleWindowStyle 屬性，以參照用於顯示文字選取錨點和包含視窗樣式的可繪項目。
  • 活動控制項
  • 通知文字和圖示樣式

    • 超大螢幕

    平台現在支援超大型的螢幕尺寸，例如可在平板電腦裝置中找到的尺寸。開發人員可以在資訊清單檔案中加入 <supports screens ... android:xlargeScreens="true"> 元素，指出應用程式設計可支援超大螢幕尺寸。應用程式可以使用新的資源限定詞 xlarge 來標記特別大螢幕專用的資源。如要進一步瞭解如何支援超大螢幕和其他螢幕大小，請參閱「支援多個螢幕」。

    圖像

    內容供應程式

    • 新增用於設定鬧鐘或處理鬧鐘的 AlarmClock 提供者類別。提供者包含 ACTION_SET_ALARM 意圖動作，以及可用來在鬧鐘應用程式中設定新鬧鐘的其他項目。想要接收 SET_ALARM 意圖的應用程式應建立需要 SET_ALARM 權限的活動。要建立新鬧鐘的應用程式應使用 Context.startActivity()，讓使用者可以選擇要使用的鬧鐘應用程式。
    • MediaStore 支援新的意圖動作 PLAY_FROM_SEARCH，可讓應用程式搜尋音樂媒體，並在可能的情況下自動從結果中播放內容。例如，應用程式可以透過語音辨識指令來觸發這個意圖來監聽音樂。
    • MediaStore 也會新增 MEDIA_IGNORE_FILENAME 標記，指示媒體掃描器忽略所屬目錄及其子目錄中的媒體。開發人員可使用這個方法，避免圖像出現在媒體庫中，同時防止應用程式音效和音樂顯示在音樂應用程式中。
    • Settings 提供者會新增活動動作 APPLICATION_DETAILS_SETTINGS 和 MANAGE_ALL_APPLICATIONS_SETTINGS，以便應用程式顯示特定應用程式的詳細資料畫面，或顯示「管理應用程式」畫面。
    • ContactsContract 供應商新增 ContactsContract.CommonDataKinds.SipAddress 資料種類，用於儲存聯絡人的 SIP (網際網路電話) 位址。

    位置

    • LocationManager 現在會根據 WorkSource (由系統管理的類別，用於識別應用程式的類別) 追蹤導致 Wake Lock 或 Wi-Fi 鎖定的應用程式要求。

      LocationManager 會追蹤所有要求定期更新的用戶端，並在設定最短更新時間時，將其視為 WorkSource 參數告知提供者。網路位置供應商會使用 WorkSource 追蹤應用程式啟動的喚醒和 Wi-Fi 鎖定，並將其加到「管理應用程式」中回報的應用程式電池用量。

    • LocationManager 新增多個新方法，讓活動登錄可根據指定條件接收定期或單次位置的更新資料 (請參閱下方說明)。
    • 新的 Criteria 類別可讓應用程式指定一組選取位置供應器的條件。例如，供應商可根據準確性、耗電量、回報高度、速度、航向和金錢費用等條件來排序。

    儲存空間

    • Android 2.3 新增了支援 OBB (不透明二進位檔 Blob) 檔案的 StorageManager。雖然 Android 2.3 提供對 OBB 的平台支援，但自 2011 年初起，才能使用用於建立及管理 OBB 檔案的開發工具。
    • 針對未包含 SD 卡的裝置，Android 2.3 平台新增了官方支援 (雖然它提供虛擬 SD 卡分區，但在沒有可用的實體 SD 卡的情況下)。便利的方法 isExternalStorageRemovable() 可讓應用程式判斷是否有實體 SD 卡。

    套裝管理員

    電話通訊系統

    對活動生命週期和視窗的原生存取權

    Android 2.3 將一系列 API 提供給使用原生程式碼的應用程式。這類應用程式感興趣的架構類別包括：

    • NativeActivity 是新的 Activity 類別，其生命週期回呼會直接在原生程式碼中實作。NativeActivity 及其基礎原生程式碼會像在其他 Activity 一樣於系統中執行，特別是在 Android 應用程式的系統程序中執行，並在應用程式的主要 UI 執行緒上執行，且會收到與其他 Activity 相同的生命週期回呼。
    • 新的 InputQueue 類別和回呼介面可讓原生程式碼管理事件佇列。
    • 新的 SurfaceHolder.Callback2 介面可讓原生程式碼管理 SurfaceHolder。
    • Window 中的新 takeInputQueue 和 takeSurface() 方法可讓原生程式碼管理事件和途徑。

    如需使用原生程式碼或下載 NDK 的完整資訊，請參閱 Android NDK 頁面。

    Dalvik 執行階段

    新的資訊清單元素和屬性

    • 為 <supports-screens> 元素新增 xlargeScreens 屬性，指出應用程式是否支援額外的大螢幕板型規格。詳情請參閱「支援多個螢幕」。
    • <activity> 元素的 android:screenOrientation 屬性新值：
      • "reverseLandscape"：活動會使螢幕以橫向模式從一般橫向切換為相反方向。
      • "reversePortrait"：活動會使螢幕以縱向方向開啟，並自一般直向切換為相反方向。
      • "sensorLandscape"：活動希望螢幕以橫向呈現，但可以使用感應器來變更螢幕朝向的方向。
      • "sensorPortrait"：活動希望螢幕以直向顯示，但可以使用感應器來變更螢幕朝向的方向。
      • "fullSensor" — 方向是由實體方向感應器決定：畫面會根據使用者移動裝置的方式旋轉。無論裝置的平常操作方式為何，這樣做都可以允許 4 種可能旋轉 (例如，部分裝置通常不會採用 180 度旋轉)。

    新權限

    • com.android.permission.SET_ALARM：允許應用程式廣播意圖，以便為使用者設定鬧鐘。處理 SET_ALARM 意圖動作的活動應需要這項權限。
    • 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 會獲派一個整數 ID「9」，該 ID 儲存在系統本身中。這個 ID 稱為「API 級別」，可讓系統在安裝應用程式之前正確判斷應用程式是否與系統相容。

    如要在應用程式中使用 Android 2.3 中導入的 API，您需要根據 Android 2.3 SDK 平台提供的 Android 程式庫編譯應用程式。視您的需求而定，您可能還需要在應用程式資訊清單中的 <uses-sdk> 元素中加入 android:minSdkVersion="9" 屬性。如果您的應用程式設計為僅在 Android 2.3 及以上版本中執行，宣告這項屬性可避免在舊版平台上安裝應用程式。

    詳情請參閱「什麼是 API 級別？」一文。