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 Manager 將平台下載至您的 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 主機控制器的連線硬體,可透過 USB 與 Android 裝置通訊。各種週邊裝置能以配件形式連線,包括機器人控制器、音樂設備、健身自行車等。

無論是 USB 裝置和 USB 配件,平台的 USB API 都支援在附加或卸離時透過意圖廣播進行探索,並提供標準介面、端點和傳輸模式 (控制、大量和中斷)。

android.hardware.usb 套件提供 USB API。中央類別為 UsbManager,可提供識別和通訊 USB 裝置和 USB 配件的輔助方法。應用程式可以取得 UsbManager 的執行個體,然後查詢連接的裝置或配件清單,然後與其通訊或管理。UsbManager 也會宣告系統廣播的意圖動作,以在連接或卸離 USB 裝置或配件時宣告。

其他類別包括:

  • UsbDevice,這個類別代表外部硬體已連線至 USB 裝置 (使用 Android 裝置做為主機)。
  • UsbAccessory,代表連線至 USB 主機的外部硬體 (使用做為 USB 裝置的 Android 裝置)。
  • UsbInterfaceUsbEndpoint,可提供裝置標準 USB 介面和端點的存取權。
  • UsbDeviceConnectionUsbRequest,用於以同步和非同步的方式,與 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() 可讓應用程式將物件的資料複製到外部儲存空間中的檔案。這個呼叫可能會根據資料大小和速度,任意時間長度封鎖,因此應使用滲透執行緒進行。
    • open() 可讓應用程式開啟已連結的 MTP/PTP 裝置。
    • getThumbnail() 會以位元組陣列的形式傳回物件的縮圖。
  • MtpStorageInfo 會保存 MTP 裝置上儲存單元的相關資訊,對應 MTP 規格第 5.2.2 節所述的 StorageInfo 資料集。這個類別中的方法可讓應用程式取得儲存單位的說明字串、可用空間、最大儲存空間容量、儲存空間 ID 和磁碟區 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 必須聚焦,才能接收搖桿事件。如有需要,應用程式可改為在「活動」或「對話方塊」層級實作 onGenericMotionEvent(),藉此處理這些事件。

如要查看使用搖桿動作事件的範例應用程式,請參閱 GameControllerInputGameView

RTP API

Android 3.1 版將 API 公開至內建的 RTP (即時傳輸通訊協定) 堆疊,供應用程式管理隨選或互動式資料串流。特別是,提供 VOIP、推送通話、會議和音訊串流的應用程式,可以使用這個 API 透過任何可用網路啟動工作階段,以及傳輸或接收資料串流。

android.net.rtp 套件提供 RTP API。這些類別包括:

為了支援音訊會議和類似用途,應用程式將兩個類別執行個體化為串流的端點:

最簡單的應用方式是使用單一遠端端點和本機端點。如需更複雜的使用方法,請參閱 AudioGroup 的限制。

如要使用 RTP API,應用程式必須在資訊清單檔案中宣告 <uses-permission android:name="android.permission.INTERNET">,以便向使用者要求權限。如要取得裝置麥克風,還需要 <uses-permission android:name="android.permission.RECORD_AUDIO"> 權限。

可調整大小的應用程式小工具

從 Android 3.1 開始,開發人員可以調整主畫面小工具的大小,包括水平、垂直或兩軸調整。使用者按住小工具即可顯示其大小調整控點,然後拖曳水平和/或垂直控點來變更版面配置格線的大小。

開發人員可在小工具的 AppWidgetProviderInfo 中繼資料中定義 resizeMode 屬性,讓任何主畫面小工具調整大小。resizeMode 屬性的值包括「horizontal」、「vertical」和「none」。如要將小工具宣告為可水平和垂直調整大小,請提供「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>

如要進一步瞭解主畫面小工具,請參閱「應用程式小工具」說明文件。

動畫架構

  • 新增 ViewPropertyAnimator 類別
  • 動畫背景顏色
  • ViewAnimator 取得分數動畫

UI 架構

顯示卡

  • 管理點陣圖的輔助程式
    • 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 中的新方法,存取更多類型網路用量的統計資料。應用程式可使用以下方法,取得特定 UID 的 UDP 統計資料、封包數量、TCP 傳輸/接收酬載位元組及區段。
  • SIP 驗證使用者名稱

下載管理員

IME 架構

媒體

  • 新增串流音訊格式
    • 媒體架構新增原始 ADTS AAC 內容的內建支援,可改善串流音訊,並支援 FLAC 音訊,可提供最高品質 (無損) 壓縮的音訊內容。詳情請參閱「支援的媒體格式」文件。

針對已停止的應用程式啟動控制項

從 Android 3.1 版開始,系統的套件管理員會追蹤處於停止狀態的應用程式,並提供控制在背景程序和其他應用程式中啟動應用程式的方法。

請注意,應用程式的停止狀態與 Activity 的停止狀態不同。系統會分別管理這兩個停止狀態。

平台定義了兩個新的意圖旗標,可讓傳送者指定是否應允許該意圖在已停止的應用程式中啟動元件。

如果這兩個標記都未在意圖中定義,或兩者都未定義,預設行為是在可能目標清單中納入已停止應用程式的篩選器。

請注意,系統會將 FLAG_EXCLUDE_STOPPED_PACKAGES 新增至所有廣播意圖。這麼做可以防止背景服務的廣播訊息意外 (或不必要的) 啟動已停止運作應用程式的元件。背景服務或應用程式可以在應允許啟動已停止應用程式的廣播意圖中加入 FLAG_INCLUDE_STOPPED_PACKAGES 標記,藉此覆寫這個行為。

首次安裝但尚未啟動的應用程式,以及使用者手動停止應用程式時,應用程式會處於停止狀態 (在「管理應用程式」中)。

應用程式首次啟動與升級通知

這個平台透過兩項新的意圖動作,針對應用程式首次啟動和升級新增更完善的通知:

  • ACTION_PACKAGE_FIRST_LAUNCH:在應用程式首次啟動時 (也就是第一次移出已停止狀態時) 傳送至應用程式的安裝程式套件。資料包含套件名稱。
  • ACTION_MY_PACKAGE_REPLACED — 在應用程式更新後安裝新版本,而非現有版本。這項資訊只會傳送至遭取代的應用程式。不含任何額外資料。如要接收訊息,請為這個動作宣告意圖篩選器。您可以使用意圖觸發程式碼,讓應用程式在升級後返回適當的執行形狀。

    此意圖會直接傳送至應用程式,但前提是應用程式必須在處於啟動狀態 (而非停止狀態) 時進行升級。

核心公用程式

  • LRU 快取
    • 新的 LruCache 類別可讓應用程式受益於有效的快取功能。應用程式可以使用該類別減少從網路計算或下載資料的時間,同時維持快取資料的合理記憶體用量。LruCache 是一種快取,會保留少數值的強參照參照。每次存取值時,該值都會移至佇列的頂端。當您在完整快取中加入一個值時,該佇列結尾的值會遭到撤銷,且可能符合垃圾收集的資格。
  • 做為 int 的檔案描述元

WebKit

  • 檔案配置 Cookie
    • CookieManager 現在支援使用 file: URI 配置的 Cookie。在建構 WebViewCookieManager 執行個體之前,您可以使用 setAcceptFileSchemeCookies() 啟用/停用檔案配置 Cookie 支援功能。在 CookieManager 執行個體中,您可以呼叫 allowFileSchemeCookies() 來檢查檔案配置 Cookie 是否已啟用。
  • 登入要求通知
    • 為了支援 Android 3.0 中導入的瀏覽器自動登入功能,新方法 onReceivedLoginRequest() 會通知主機應用程式,處理使用者的自動登入要求已處理完畢。
  • 移除類別和介面
    • 某些類別和介面在先前處於淘汰狀態後已從公用 API 中移除。詳情請參閱 API 差異報告

Browser

瀏覽器應用程式新增了下列功能以支援網頁應用程式:

  • 支援內嵌播放 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 會指派一個儲存在系統本身中的整數 ID (12)。這個 ID 稱為「API 級別」,可讓系統在安裝應用程式前,正確判斷應用程式是否與系統相容。

如要在應用程式中使用 Android 3.1 中導入的 API,您必須針對 Android 3.1 SDK 平台提供的 Android 程式庫編譯應用程式。視您的需求而定,您可能還需要在應用程式資訊清單中的 <uses-sdk> 元素中加入 android:minSdkVersion="12" 屬性。

詳情請參閱「什麼是 API 級別?」一節。