Android 3.2 API

API 級別： 13

Android 3.2 (HONEYCOMB_MR2) 是逐步推出的平台版本，為使用者和開發人員新增功能。以下各節將概述新功能和開發人員 API。

對於開發人員而言，Android 3.2 平台可做為 Android SDK 的可下載元件使用。可下載的平台包含 Android 程式庫和系統映像檔，以及一組模擬器外觀等。如要開始針對 Android 3.2 進行開發或測試，請使用 Android SDK Manager 將平台下載至 SDK。

平台重點

新使用者功能

• 針對更多平板電腦進行最佳化

  Android 3.2 包含各種系統最佳化功能，可確保在更多平板電腦裝置上提供優質的使用者體驗。

• 固定大小應用程式的相容性縮放功能

  Android 3.2 推出了新的相容性縮放模式，讓使用者在較大的裝置上以新方式查看固定大小的應用程式。對於不是為了在較大螢幕上執行 (例如平板電腦) 而設計的應用程式，新模式提供了像素縮放的替代方案，以取代標準 UI 延展功能。如果應用程式需要相容性支援，使用者可以透過系統列中的選單圖示存取新模式。

• 從 SD 卡同步媒體

  在支援 SD 卡的裝置上，使用者現在可以直接從 SD 卡將媒體檔案載入至使用這些檔案的應用程式。系統設施可讓應用程式從系統媒體儲存區存取檔案。

新開發人員功能

• 管理螢幕支援的擴充 API

  Android 3.2 版為平台螢幕支援 API 推出了擴充功能，讓開發人員能夠以更多方式管理各種 Android 裝置上的應用程式 UI。這個 API 包含新的資源限定詞和新的資訊清單屬性，可讓您更精確地控管應用程式在不同大小螢幕上的顯示方式，而非依賴一般化的大小類別。

  為確保固定大小的應用程式和僅支援部分螢幕尺寸的應用程式能以最佳方式顯示，平台也提供新的縮放相容性模式，可在較小的螢幕區域中算繪 UI，然後將其縮放至填滿螢幕可用空間。如要進一步瞭解螢幕支援 API 及其提供的控制項，請參閱下列各節。

API 總覽

螢幕支援 API

Android 3.2 版推出了支援新螢幕的 API，讓您進一步控管應用程式在不同螢幕尺寸上的顯示方式。這個 API 以現有的螢幕支援 API 為基礎 (包括平台的通用螢幕密度模型)，但擴充了以其尺寸 (以密度獨立像素單位 (例如 600dp 或 720dp 寬) 為單位) 精確指定特定螢幕範圍的能力，而非以通用螢幕大小 (例如 large 或 xlarge) 為單位

設計應用程式 UI 時，您仍可依賴平台提供的密度抽象化功能，也就是說，應用程式不必針對不同裝置的實際像素密度差異進行補償。您可以根據可用的水平或垂直空間量來設計應用程式 UI。平台會使用三個新特徵來表示可用的空間量：smallestWidth、width 和 height。

• 螢幕的 smallestWidth 是其基本最小尺寸，以密度獨立像素 (「dp」) 為單位進行測量。螢幕的高度或寬度，兩者中較短的一個。如果是直向的螢幕，smallestWidth 通常是根據寬度而定，在橫向中則是根據高度。無論螢幕方向為何，smallestWidth 一律會從螢幕的固定特性衍生，且值不會變更。應用程式需要最小寬度，因為它代表應用程式 UI 需要繪製的最小寬度，不包括系統保留的螢幕區域。
• 相較之下，螢幕的寬度和高度代表應用程式版面配置目前可用的水平或垂直空間，以「dp」為單位，不含系統保留的螢幕區域。當使用者在橫向和直向之間切換螢幕方向時，螢幕的寬度和高度會有所變動。

新的螢幕支援 API 可讓您根據目前螢幕的最小寬度來管理應用程式 UI。您也可以視需要根據目前的寬度或高度管理 UI。為達到這些目的，API 提供下列工具：

• 新的資源限定詞，可將版面配置和其他資源指定為最小寬度、寬度或高度，以及
• 新的資訊清單屬性，用於指定應用程式的最大螢幕相容性範圍

此外，與舊版平台一樣，應用程式仍可查詢系統，並管理執行階段的 UI 和資源載入。

由於新版 API 可讓您透過 smallestWidth、width 和 height 更直接地指定螢幕，因此瞭解不同螢幕類型的典型特徵會很有幫助。下表提供一些以「dp」單位為單位的範例。

表 1. 常見的裝置，密度和大小以 dp 為單位。

以下各節將進一步說明新的螢幕限定詞和資訊清單屬性。如要進一步瞭解如何使用螢幕支援 API，請參閱「支援多螢幕」。

支援螢幕的新資源限定詞

Android 3.2 中的新資源限定詞可讓您更精準地針對螢幕尺寸範圍設定版面配置。透過限定詞，您可以建立專為特定最小 smallestWidth、目前寬度或目前高度所設計的資源設定，以密度獨立像素為單位。

新限定詞如下：

• swNNNdp：指定應使用資源的最小 smallestWidth，以「dp」為單位。如上所述，無論螢幕方向為何，螢幕的最小寬度都是常數。例如：sw320dp、sw720dp、sw720dp。
• wNNNdp 和 hNNNdp：指定應使用資源的最小寬度或高度，以「dp」為單位。如上所述，螢幕的寬度和高度會依螢幕方向而定，並會在方向變更時變更。例如：w320dp、w720dp、h1024dp。

您也可以視需要建立多個重疊的資源設定。舉例來說，您可以為某些資源加上標記，以便在任何寬度大於 480 dp 的螢幕上使用，其他資源則可用於寬度大於 600 dp 的螢幕，其他資源則可用於寬度大於 720 dp 的螢幕。當多個資源設定符合特定螢幕的條件時，系統會選取最相符的設定。如要精確控制特定畫面載入哪些資源，您可以為資源加上一個限定詞，或結合多個新或現有的限定詞。

根據前述的一般維度，以下提供幾個使用新限定詞的範例：

res/layout/main_activity.xml   # For phones
res/layout-sw600dp/main_activity.xml   # For 7” tablets
res/layout-sw720dp/main_activity.xml   # For 10” tablets
res/layout-w600dp/main_activity.xml   # Multi-pane when enough width
res/layout-sw600dp-w720dp/main_activity.xml   # For large width

舊版平台會忽略新限定詞，因此您可以視需要混合使用這兩種限定詞，確保應用程式在任何裝置上都能正常顯示。以下列舉幾個例子：

res/layout/main_activity.xml   # For phones
res/layout-xlarge/main_activity.xml   # For pre-3.2 tablets
res/layout-sw600dp/main_activity.xml   # For 3.2 and up tablets

如要進一步瞭解如何使用新的限定詞，請參閱「使用新的大小限定詞」。

用於螢幕大小相容性的新資訊清單屬性

此架構提供一組新的 <supports-screens> 資訊清單屬性，可讓您管理應用程式對不同螢幕尺寸的支援情形。具體來說，您可以指定應用程式設計用來執行的最大和最小螢幕，以及應用程式設計用來執行的最大螢幕，而無需使用系統的新螢幕相容模式。如同上述所述的資源限定詞，新的資訊清單屬性會指定應用程式支援的螢幕範圍，如同 smallestWidth 所指定。

螢幕支援的新資訊清單屬性如下：

• android:compatibleWidthLimitDp="numDp"：這項屬性可讓您指定應用程式可在其上執行的最大 smallestWidth，而不需要相容模式。如果目前的螢幕大於指定的值，系統會以一般模式顯示應用程式，但允許使用者選擇透過系統列中的設定切換至相容模式。
• android:largestWidthLimitDp="numDp"：這項屬性可讓您指定應用程式設計的「最小寬度」上限。如果目前的螢幕大於指定的值，系統會強制將應用程式設為螢幕相容模式，確保在目前螢幕上顯示最佳畫面。
• android:requiresSmallestWidthDp="numDp"：這項屬性可讓您指定應用程式可執行的最小寬度。如果目前的螢幕小於指定的值，系統會認為應用程式與裝置不相容，但不會禁止安裝和執行應用程式。

注意：Google Play 目前不會根據上述任何屬性篩選應用程式。我們將在後續平台版本中新增篩選功能支援。需要根據螢幕大小進行篩選的應用程式可以使用現有的 <supports-screens> 屬性。

如要進一步瞭解如何使用新屬性，請參閱「宣告螢幕大小支援功能」。

螢幕相容模式

Android 3.2 為應用程式提供新的螢幕相容模式，可明確宣告不支援螢幕大小與執行中螢幕大小相同。這個新的「縮放」模式是以像素為單位調整，在較小的螢幕區域中算繪應用程式，然後將像素縮放至填滿目前的螢幕。

根據預設，系統會針對需要螢幕相容模式的應用程式，提供螢幕相容模式做為使用者選項。使用者可以使用系統列中的控制項開啟或關閉縮放模式。

由於新螢幕相容模式可能不適用於所有應用程式，因此平台允許應用程式使用資訊清單屬性停用該模式。如果由應用程式停用，系統不會在應用程式執行時提供「縮放」相容性模式供使用者選擇。

注意：如要瞭解如何控制應用程式中的相容性模式，請參閱 Android 開發人員網誌上的「大螢幕應用程式的新模式」一文。

720p 電視和類似裝置的新螢幕密度

為了滿足在 720p 電視或類似中等密度螢幕上執行的應用程式需求，Android 3.2 推出了新的通用密度 tvdpi，其大致 dpi 為 213。應用程式可在 densityDpi 中查詢新的密度，並使用新的 tvdpi 限定詞為電視和類似裝置的資源加上標記。例如：

res/drawable-tvdpi/my_icon.png   # Bitmap for tv density

一般來說，應用程式不應需要處理這個密度。在需要輸出 720p 螢幕的情況下，平台可自動調整 UI 元素。

UI 架構

• 片段
  • 新的 Fragment.SavedState 類別會透過 saveFragmentInstanceState() 從片段例項擷取的狀態資訊。
  • 新方法 saveFragmentInstanceState() 會儲存指定 Fragment 的目前例項狀態。之後建立與目前狀態相符的 Fragment 執行個體時，可以使用狀態狀態。
  • 新的 setInitialSavedState() 方法會在首次建構時，為 Fragment 設定初始儲存狀態。
  • 新的 onViewCreated() 回呼方法會通知片段，onCreateView() 已傳回，但尚未將任何已儲存的狀態還原至 View。
  • isDetached() 方法會判斷 Fragment 是否已明確從 UI 卸離。
  • 新的 attach() 和 detach() 方法可讓應用程式重新連結或分離 UI 中的片段。
  • 新的 setCustomAnimations() 超載方法可讓您設定特定動畫資源，以便在進入/離開作業 (尤其是彈出返回堆疊時) 時執行。現有的實作方式並未考量片段在彈出返回堆疊時的不同行為。
• ActivityInfo 和 ApplicationInfo 中的螢幕大小資訊
  • ActivityInfo 會在 configChanges 中新增 CONFIG_SCREEN_SIZE 和 CONFIG_SMALLEST_SCREEN_SIZE 做為位元遮罩。這些位元會指出活動本身是否能處理螢幕大小和最小螢幕大小。
  • ApplicationInfo 會新增 largestWidthLimitDp、compatibleWidthLimitDp 和 requiresSmallestWidthDp 欄位，這些欄位是從應用程式資訊清單檔案中的對應 <supports-screens> 屬性衍生而來。
• 從 WindowManager 取得顯示大小的輔助程式
  • 新方法 getSize() 和 getRectSize() 可讓應用程式取得螢幕的原始大小。
• 全新公開「全像」樣式
  • 這個平台現在支援多種公開的「全像」樣式，可用於文字、動作列小工具和分頁等。如需完整清單，請參閱 R.style。
• LocalActivityManager、ActivityGroup 和 LocalActivityManager 現已淘汰
  • 新應用程式應使用 Fragment，而非這些類別。如要繼續在舊版平台上執行，您可以使用 Android SDK 提供的 v4 支援資料庫 (相容性程式庫)。v4 支援資料庫提供的 Fragment API 版本，可向下相容至 Android 1.6 (API 級別 4)。
  • 針對針對 Android 3.0 (API 級別 11) 以上版本開發的應用程式，使用者介面通常會使用新的 ActionBar.newTab() 和相關 API，將分頁放置在動作列區域。

媒體架構

• 使用平台媒體供應器 (MediaStore) 的應用程式，現在可以直接從可移除的 SD 卡讀取媒體資料 (如果裝置支援的話)。應用程式也可以透過 MTP API 直接與 SD 卡檔案互動。

圖形

• Point 和 PointF 中的可分割公用程式
  • Point 和 PointF 類別現在包含 Parcelable 介面和公用程式方法 describeContents()、readFromParcel() 和 writeToParcel()。

IME 架構

• 新的 getModifiers() 方法，用於擷取修飾鍵的目前狀態。

USB 架構

• 新的 getRawDescriptors() 方法，可用於擷取裝置的原始 USB 描述元。您可以使用此方法，存取無法透過較高層級 API 直接存取的描述元。

網路

• 網路類型常數
  • ConnectivityManager 會新增常數 TYPE_ETHERNET 和 TYPE_BLUETOOTH。

電話通訊系統

• 新的 NETWORK_TYPE_HSPAP 網路類型常數。

核心公用程式

• 可分割的公用程式
  • 新介面 Parcelable.ClassLoaderCreator 可讓應用程式接收建立物件的 ClassLoader。
  • 新增 adoptFd、dup() 和 fromFd()，用於管理 ParcelFileDescriptor 物件。
• Binder 和 IBinder
  • Binder 和 IBinder 中的新方法 dumpAsync() 可讓應用程式轉儲至指定檔案，確保目標以非同步方式執行。
  • 新增 IBinder 通訊協定交易代碼 TWEET_TRANSACTION，可讓應用程式將推文傳送至目標物件。

新功能常數

平台會新增硬體功能常數，您可以在應用程式資訊清單中宣告這些常數，以便告知 Google Play 等外部實體所需的硬體和軟體功能。您可以在 <uses-feature> 資訊清單元素中宣告這些和其他功能常數。

Google Play 會根據應用程式的 <uses-feature> 屬性篩選應用程式，確保只有符合應用程式規定的裝置才能使用應用程式。

• 橫向或直向模式的功能常數規定

  Android 3.2 版導入了新功能常數，可讓應用程式指定是否需要橫向或直向顯示螢幕。宣告這些常數表示應用程式不得安裝在未提供相關螢幕方向的裝置上。反之，如果未宣告一個或兩個常數，表示應用程式沒有未宣告的螢幕方向偏好設定，且可能安裝在未提供這些方向的裝置上。

  • android.hardware.screen.landscape：應用程式必須以橫向方向顯示。
  • android.hardware.screen.portrait：應用程式需要直向顯示。

  一般應用程式在橫向和直向模式下都能正常運作，通常不需要宣告方向需求。相反地，如果應用程式主要針對單一螢幕方向設計 (例如針對電視設計的應用程式)，則可以宣告其中一個常數，確保應用程式無法在未提供該螢幕方向的裝置上執行。

  如果資訊清單要求中宣告的任何活動，且使用 android:screenOrientation 屬性以特定方向執行，則這也會宣告應用程式需要該螢幕方向。

• 其他功能常數
  • android.hardware.faketouch.multitouch.distinct：應用程式需要支援模擬多點觸控輸入，並追蹤兩個以上不同點。
  • android.hardware.faketouch.multitouch.jazzhand：應用程式必須支援模擬多點觸控輸入，並追蹤五個以上不同的觸控點。

API 差異報表

如需 Android 3.2 (API 級別 13) 中所有 API 變更的詳細資訊，請參閱 API 差異比較表。

API 級別

Android 3.2 平台提供更新版的架構 API。Android 3.2 API 會獲派一個儲存在系統本身的整數 ID (13)。這個 ID 稱為「API 級別」，可讓系統在安裝應用程式前，正確判斷應用程式是否與系統相容。

如要在應用程式中使用 Android 3.2 中推出的 API，您必須根據 Android 3.2 SDK 平台提供的 Android 程式庫編譯應用程式。視您的需求而定，您可能也需要在應用程式資訊清單的 <uses-sdk> 元素中加入 android:minSdkVersion="13" 屬性。

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