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 主機控制器、提供電源，並且可透過 USB 與 Android 裝置通訊，各種週邊裝置能以配件連接，包括機器人控制器、音樂設備、健身自行車等。

針對這兩種類型，USB 裝置和 USB 配件：平台的 USB API 支援在連接或卸離時透過意圖廣播進行探索，以及標準介面、端點，以及傳輸模式 (控制、大量和中斷)。

USB API 位於 android.hardware.usb 套件中。中央類別為 UsbManager，可提供輔助方法識別及與 USB 裝置和 USB 配件進行通訊。應用程式可以取得 UsbManager 的例項，然後查詢連接的裝置或配件清單，並與這些項目通訊或管理。UsbManager 也會宣告系統要廣播的意圖動作，以在 USB 裝置或配件連接或卸離時發出通知。

其他類別包括：

  • UsbDevice：這個類別，代表以 USB 裝置連接的外部硬體 (並將做為主機的 Android 裝置)。
  • UsbAccessory，代表以 USB 主機連接的外部硬體 (將 Android 裝置當做 USB 裝置使用)。
  • UsbInterface 和 UsbEndpoint：提供裝置標準 USB 介面和端點的存取權。
  • UsbDeviceConnection 和 UsbRequest：能以同步、非同步的方式收發資料和控制 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 測試和任務啟動器

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 會保留對應於 DeviceInfo 資料集所對應的 MTP 裝置資訊，如 MTP 規格第 5.1.1 節所述。類別中的方法可讓應用程式取得裝置的製造商、型號、序號和版本。
  • MtpObjectInfo 會保留儲存在 MTP 裝置上的物件資訊，與 MTP 規格第 5.3.1 節所述的 ObjectInfo 資料集相對應。類別中的方法可讓應用程式取得物件的大小、資料格式、關聯類型、建立日期和縮圖資訊。
  • 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 必須取得焦點，才能接收搖桿事件。應用程式可以視需要改為實作 onGenericMotionEvent()，在活動或對話方塊層級處理這些事件。

如要查看使用搖桿動作事件的範例應用程式，請參閱 GameControllerInput 和 GameView。

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 驗證使用者名稱

下載管理員

輸入法編輯器架構

媒體

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

在已停止的應用程式上啟動控制項

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

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

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

若未在意圖中定義這兩個標記或兩個標記，預設行為是在潛在目標清單中納入已停止應用程式的篩選器。

請注意，系統會將 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建構 WebView 或 CookieManager 執行個體之前，您可以使用 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 級別？」一文。