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 總覽

Screens Support API

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

設計應用程式的 UI 時，您仍然可以依賴平台提供密度抽象化，這表示應用程式不需要彌補各裝置的實際像素密度的差異。您可以根據可用的水平或垂直空間量設計應用程式 UI。平台會使用三個新特性來表示可用的空間量：smallestWidth、width 和 height。

• 螢幕的 smallestWidth 是其基本大小，以密度獨立像素 (「dp」) 為單位計算。也就是螢幕高度或寬度對於直向的螢幕，smallestWidth 通常會以寬度為依據，在橫向模式下則是以其高度為依據。在所有情況下，smallestWidth 都衍生自螢幕的固定特徵，且無論方向為何，這個值都不會改變。smallestWidth 對應用程式而言非常重要，因為其代表繪製應用程式 UI 所需的最短寬度，不包括系統保留的螢幕區域。
• 相反地，螢幕的「寬度」和「高度」代表應用程式版面配置目前可用的水平或垂直空間，測量單位為「dp」單位，不含系統保留的畫面區域。當使用者在橫向和直向之間切換時，螢幕的寬度和高度會隨之變更。

新的螢幕支援 API 旨在讓您根據目前畫面的 smallestWidth 管理應用程式 UI。您也可以視需要根據目前的寬度或高度管理 UI。針對這些目的，API 提供下列工具：

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

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

這個新 API 可讓您更直接地指定螢幕，方法是最小寬度、寬度和高度，因此建議您瞭解不同螢幕類型的一般特性。下表提供一些範例，以「dp」為單位。

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

類型	密度 (一般化)	尺寸 (dp)	最小寬度 (dp)
基準電話	mdpi	320x480	320
小型平板電腦/大型手機	mdpi	480x800	480
7 吋平板電腦	mdpi	600x1024	600
10 吋平板電腦	mdpi	800x1280	800

以下各節將提供新螢幕限定詞和資訊清單屬性的詳細資訊。如需螢幕支援 API 的完整使用資訊，請參閱「支援多個螢幕」。

適用於螢幕支援的新資源限定詞

Android 3.2 中的新資源限定詞可讓您更有效地針對各種螢幕大小範圍指定版面配置。使用限定詞時，您可以建立資源設定，專門用於特定最小最小寬度、目前寬度或目前高度 (以密度獨立像素為單位)。

新的限定詞如下：

• 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> 資訊清單屬性，可讓您管理應用程式對不同螢幕大小的支援功能。具體來說，您可以指定執行應用程式所需的最大、最小螢幕，以及系統設計執行的最大螢幕，無需使用系統新的螢幕相容模式。如同上述的資源限定詞，新的資訊清單屬性會指定應用程式支援的畫面範圍，如 minestWidth 所指定。

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

• android:compatibleWidthLimitDp="numDp"：這個屬性可讓您指定應用程式可在沒有相容性模式的情況下執行的最大 smallestWidth。如果目前的畫面大於指定的值，系統會將應用程式顯示為一般模式，但允許使用者選擇透過系統列中的設定切換至相容模式。
• android:largestWidthLimitDp="numDp"：這個屬性可讓您指定執行應用程式所需的最小最小寬度。如果目前的畫面大於指定的值，系統會強制應用程式進入螢幕相容模式，以確保目前的螢幕能完整顯示。
• android:requiresSmallestWidthDp="numDp"：這個屬性可讓您指定應用程式執行的最小最小寬度。如果目前的畫面小於指定的值，系統會判定應用程式與裝置不相容，但不會禁止安裝及執行應用程式。

注意：Google Play 目前不會根據上述任一屬性篩選應用程式。日後的平台版本將新增篩選功能。需要根據螢幕大小篩選的應用程式可使用現有的 <supports-screens> 屬性。

如需使用新屬性的完整資訊，請參閱「宣告螢幕大小支援」。

螢幕相容模式

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

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

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

注意：如要取得有關如何控制應用程式相容性模式的重要資訊，請參閱 Android 開發人員網誌的「適用於大螢幕應用程式的新模式」一文。

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

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

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

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

UI 架構

• 片段
  • 新的 Fragment.SavedState 類別會透過 saveFragmentInstanceState() 保留從片段執行個體擷取的狀態資訊。
  • 新方法 saveFragmentInstanceState() 會儲存指定片段目前的例項狀態。之後建立符合目前狀態的片段例項時，可以使用此狀態。
  • 新方法 setInitialSavedState() 會在首次建構 Fragment 時設定初始儲存狀態。
  • 新的 onViewCreated() 回呼方法會通知片段，指出 onCreateView() 已傳回，但在任何儲存狀態還原至檢視畫面中。
  • 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 提供的第 4 版支援資料庫 (相容性程式庫)。v4 支援資料庫提供與 Android 1.6 (API 級別 4) 相容的 Fragment API 版本，
  • 如果是針對 Android 3.0 (API 級別 11) 或以上版本開發的應用程式，使用者介面通常會使用新的 ActionBar.newTab() 和相關 API，將分頁放在動作列區域內。

媒體架構

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

圖像

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

輸入法編輯器架構

• 新增 getModifiers() 方法，用於擷取輔助鍵的目前狀態。

USB 架構

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

網路

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

電話通訊系統

• 新增 NETWORK_TYPE_HSPAP 網路類型常數。

核心公用程式

• Parcelable 公用程式
  • 新的介面 Parcelable.ClassLoaderCreator 可讓應用程式接收建立物件的 ClassLoader。
  • 新增用於管理 ParcelFileDescriptor 物件的 adoptFd、dup() 和 fromFd()。
• 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 儲存在系統本身中。這個 ID 稱為「API 級別」，可讓系統在安裝應用程式之前正確判斷應用程式是否與系統相容。

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

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