<uses-sdk>

Google Play 會利用應用程式資訊清單中宣告的 <uses-sdk> 屬性，篩除不符合應用程式平台版本要求的裝置。設定這些屬性之前，請務必瞭解 Google Play 篩選器。

語法：

<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />

包含於：

<manifest>

說明：

供您透過 API 級別數字，顯示應用程式與 Android 平台版本的相容性。系統會比較應用程式和指定 Android 系統兩者的 API 級別，這在不同的 Android 裝置間可能存在差異。

即使名稱好像無關，這個元素的用途是指定 API 級別，而「不是」軟體開發套件 (SDK) 或 Android 平台的版本號碼。API 級別一律為單一整數。您無法透過相關聯的 Android 版本號碼推知 API 級別，舉例來說，API 級別與主要版本不同，也不等於主要版本和子版本號碼的總和，因此無從得知。

另請參閱應用程式版本管理相關文件。

屬性：

android:minSdkVersion

一個用於指定應用程式執行所需 API 最低級別的整數。如果系統的 API 級別低於此屬性的指定值，Android 系統會禁止使用者安裝應用程式。請務必宣告這個屬性。

注意：如未宣告這項屬性，系統會假設其值為預設值「1」，這表示應用程式與所有 Android 版本相容。如果應用程式「並非」與所有版本相容，且您未宣告適當的 minSdkVersion，則當應用程式安裝在 API 級別不相容的系統上時，會因為嘗試存取未提供的 API 而在執行階段停止運作。因此，請務必在 minSdkVersion 屬性中宣告適當的 API 級別。

android:targetSdkVersion

一個用於指定應用程式目標 API 級別的整數。如果未設定，預設值會是指定給 minSdkVersion 的值。

這項屬性會告知系統您已針對目標版本完成測試，且系統並未啟用任何相容性行為來維持應用程式與目標版本的前瞻相容性。應用程式仍可在較舊的版本上執行 (最低版本為 minSdkVersion)。

隨著 Android 的每個新版本推陳出新，也可能會變更部分行為和外觀。不過，如果平台的 API 級別高於應用程式 targetSdkVersion 所宣告的版本，系統可能會啟用相容性行為，以利應用程式繼續正常運作。如要停用這類相容性行為，請將 targetSdkVersion 指定為符合執行平台的 API 級別。

舉例來說，如果將這個值設定為「11」以上，當應用程式在 Android 3.0 以上版本執行時，系統可以對應用程式套用 Holo 預設主題，而在大螢幕上執行時，系統也會停用螢幕相容模式，因為支援 API 級別 11 就能明確支援大螢幕。

系統可能會根據這項屬性的設定值啟用多種相容性行為。Build.VERSION_CODES 參考資料中的對應平台版本描述了其中幾種行為。

為了維持應用程式與每個 Android 版本的相容性，請依據最新 API 級別提高這項屬性的值，然後在對應的平台版本上仔細測試應用程式。

導入版本：API 級別 4。

android:maxSdkVersion

一個用於指定執行應用程式所需最高 API 級別的整數。

在 Android 1.5、1.6、2.0 和 2.0.1 版本中，系統會在安裝應用程式時，以及在更新完成並重新驗證應用程式時，檢查這個屬性的值。無論是哪一種情況，如果應用程式的 maxSdkVersion 屬性值低於系統本身使用的 API 級別，則系統會禁止安裝應用程式。如果是在系統更新後重新驗證，這項操作實際上是從裝置中移除應用程式。

如要瞭解這項屬性在系統更新後對應用程式的影響，請參考以下範例：

Google Play 上發布了一個在資訊清單中宣告 maxSdkVersion="5" 的應用程式。某位使用者在搭載 Android 1.6 (API 級別 4) 的裝置上下載並安裝了該應用程式，並在數週後透過無線更新的方式，將系統更新至 Android 2.0 (API 級別 5)。安裝更新後，系統檢查應用程式的 maxSdkVersion 並順利完成重新驗證。

原先應用程式照常運作。不過，一段時間後，裝置再次收到系統更新，這次是更新至 Android 2.0.1 版 (API 級別 6)。更新後，系統就無法再重新驗證應用程式，因為系統當下的 API 級別 (6) 高於應用程式支援的最高級別 (5)。系統會讓使用者看不見應用程式，實際上等同於從裝置移除應用程式。

警告：我們不建議宣告這個屬性。首先，您不需要透過設定這項屬性，在 Android 平台發布新版本時，封鎖應用程式的部署作業。從設計上來說，新版平台可完全回溯相容。如果應用程式只使用標準 API 並遵循開發作業最佳做法，就能在新版本中正常運作。其次，在某些情況下，宣告這項屬性可能會導致系統在更新至更高的 API 級別後，將應用程式從使用者的裝置中移除。大多數可能安裝應用程式的裝置都會透過無線更新的方式定期接收系統更新，因此在設定這項屬性之前，請先考量這類更新對應用程式的影響。

導入版本：API 級別 4。

部分 Android 版本 (Android 2.0.1 之後的版本) 不會在安裝或重新驗證期間檢查或強制執行 maxSdkVersion 屬性。不過，Google Play 向使用者顯示有可供下載的應用程式時，仍會繼續使用屬性做為篩選條件。

導入版本：

API 級別 1

什麼是 API 級別？

API 級別是一個整數值，專門用於識別 Android 平台版本提供的架構 API 修訂版本。

Android 平台提供一種架構 API，讓應用程式用於與基礎 Android 系統互動。架構 API 包含：

• 一組核心套件和類別
• 一組用於宣告資訊清單檔案的 XML 元素和屬性
• 一組用於宣告及存取資源的 XML 元素和屬性
• 一組意圖
• 一組應用程式可要求的權限，以及系統提供的權限違規處置措施

每個連續版本的 Android 平台均可包含其提供的 Android 應用程式架構 API 更新。

架構 API 的更新設計目的是為了讓新 API 仍與舊版的 API 相容。也就是說，API 的大部分變更都是加入更動，並推出全新或替換功能。API 的部分功能升級後，遭取代的舊版功能雖已淘汰但並未移除，因此仍可供現有應用程式使用。

在極少數情況下，API 的某些部分會遭到修改或移除。不過，通常只有為了確保 API 穩定性和應用程式/系統安全性時，才需要進行這類變更。其他來自早期修訂版本的 API 部分全都會原封不動，不做任何修改。

Android 平台提供的架構 API 是以名為「API 級別」的整數識別碼指定。每個 Android 平台版本恰好支援一個 API 級別，但都隱含對所有早期 API 級別 (低至 API 級別 1) 的支援。Android 平台的初始版本提供 API 級別 1，後續版本則依次提高 API 級別。

下表列出各 Android 平台版本支援的 API 級別。如要進一步瞭解執行各版本的裝置數量，請參閱「發布資訊主頁」。

API 級別在 Android 中的應用

為盡可能確保使用者和應用程式開發人員都能享有最佳體驗，API 級別 ID 扮演了關鍵角色：

• 讓 Android 平台可說明自身支援的最高架構 API 修訂版本。
• 讓應用程式可說明自身需要的架構 API 修訂版本。
• 讓系統可判定是否要在使用者裝置上安裝應用程式，避免安裝版本不相容的應用程式。

每個 Android 平台版本都將自身的 API 級別 ID 儲存在內部，也就是 Android 自身系統中。

應用程式可以使用架構 API 提供的資訊清單元素 (<uses-sdk>)，描述其執行所需的最低和最高 API 級別，以及支援的建議 API 級別。該元素提供以下三個主要屬性：

• android:minSdkVersion：指定執行應用程式所需的最低 API 級別。預設值是「」。
• android:targetSdkVersion：指定執行應用程式所需的 API 級別。在某些情況下，這個屬性可讓應用程式使用目標 API 級別中定義的資訊清單元素或行為，而不是只使用最低 API 級別定義的元素或行為。
• android:maxSdkVersion：指定應用程式執行所需的最高 API 級別。重要事項：使用這項屬性前，請先詳閱本頁有關該屬性的資訊。

舉例來說，如要指定應用程式執行所需的最低系統 API 級別，應用程式須在資訊清單中加入含有 android:minSdkVersion 屬性的 <uses-sdk> 元素。android:minSdkVersion 是一個整數值，對應能執行應用程式最低 Android 平台版本的 API 級別。

無論是使用者嘗試安裝應用程式，還是系統在更新後重新驗證應用程式，Android 系統都會先檢查應用程式資訊清單中的 <uses-sdk> 屬性，並將這些值與系統本身的內部 API 級別相互比較。只有在符合下列條件時，系統才允許開始安裝：

• 如果已宣告 android:minSdkVersion 屬性，其值須小於或等於系統的 API 級別整數。如未宣告，系統會假設應用程式需要 API 級別 1。
• 如果已宣告 android:maxSdkVersion 屬性，其值須等於或大於系統的 API 級別整數。如未宣告，系統會假設應用程式沒有 API 級別上限。如需進一步瞭解系統如何處理這個屬性，請參閱這項屬性的說明。

如果是在應用程式資訊清單中宣告 <uses-sdk>，這項元素可能會如下所示：

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

應用程式在 android:minSdkVersion 中宣告 API 級別的主要原因，是要向 Android 系統說明其所用的是指定 API 級別中「導入」的 API。

如果應用程式基於不明原因安裝在 API 級別較低的平台上，就會因嘗試存取不存在的 API 而在執行階段停止運作。但假如應用程式需要的最低 API 級別高於目標裝置上平台版本的　API 級別，系統就會禁止安裝應用程式，以防出現這種結果。

開發作業注意事項

當您開發應用程式時，需將 API 級別納入考量，以下各節提供相關資訊方便您參閱。

應用程式前瞻相容性

Android 應用程式通常具有與新版本 Android 平台的前瞻相容性。

由於架構 API 的所有變更幾乎都是外加性質，使用任何指定 API 版本 (如其 API 級別指定版本) 開發的 Android 應用程式，均具有與後續 Android 平台版本和更高 API 級別的前瞻相容性。也就是說，除非在罕見情況下，應用程式所用的部分 API 後來因某種原因遭到移除，否則應用程式都能在所有較新版本的 Android 平台上執行。

前瞻相容性十分重要，因為許多搭載 Android 系統的裝置都會收到系統無線更新 (OTA)。使用者可能會安裝您的應用程式並順利使用，然後收到更新至新版 Android 平台的 OTA 通知。安裝更新之後，應用程式就會在新的執行階段版本環境中執行，但其中仍含應用程式所依附的 API 和系統功能。

該 API「之下」的變更 (例如基礎系統本身的變更) 可能會影響在新環境中執行的應用程式。應用程式開發人員必須瞭解應用程式在各個系統環境中的外觀和行為。

為了協助您在各種版本的 Android 平台上測試應用程式，Android SDK 提供多個可下載的平台。每個平台都包含一個相容系統映像檔，您可以在 AVD 中執行該映像檔，以測試應用程式。

應用程式回溯相容性

如果是比編譯所用版本更舊的 Android 平台，Android 應用程式未必能與其回溯相容。

這是因為每個新版本的 Android 平台都可以包含新的架構 API，例如可讓應用程式存取新平台功能或取代現有 API 部分的 API。因此，無論是在新平台還是後續版本的平台 (如 API 級別指定的版本) 上執行，應用程式都可以存取新的 API。不過，由於舊版平台並未提供新的 API，因此採用新 API 的應用程式無法在這些平台上執行。

雖然不可能將搭載 Android 系統的裝置降級至舊版平台，但您必須瞭解，可能有許多裝置執行的是舊版平台。即使是透過 OTA 更新的裝置，有些也可能會延遲更新，而且可能已經長時間沒有接收更新。

選擇平台版本和 API 級別

開發應用程式時，您需要選擇是根據哪個平台版本來編譯應用程式。一般來說，您應依據應用程式可支援的最低平台版本編譯應用程式。

您可以依次遞降建構目標並據此編譯應用程式，判斷可能的最低平台版本。決定最低版本後，請使用對應的平台版本和 API 級別建立 AVD，然後對應用程式進行全面測試。請務必在應用程式的資訊清單中宣告 android:minSdkVersion 屬性，並將其值設為平台版本的 API 級別。

宣告最低 API 級別

如要您建構的應用程式使用最新平台版本中導入的 API 或系統功能，請將 android:minSdkVersion 屬性設為最新平台版本的 API 級別。這樣可讓使用者只能在搭載相容 Android 平台版本的裝置上安裝應用程式，進而確保您的應用程式可以在使用者的裝置上正常運作。

如果應用程式使用最新平台版本中導入的 API，但「並未」宣告 android:minSdkVersion 屬性，則應用程式可在搭載最新平台版本的裝置上正常運作，但「無法」在搭載較舊平台版本的裝置上執行。在第二種情況下，當應用程式嘗試使用舊版上沒有的 API 時，會在執行階段停止運作。

針對更高的 API 級別進行測試

編譯應用程式之後，請務必在應用程式 android:minSdkVersion 屬性所指定的平台上進行測試。為此，請建立採用應用程式所需平台版本的 AVD。此外，為檢查前瞻相容性，請一律在 API 級別高於您應用程式的平台上執行及測試應用程式。

Android SDK 包含多個可用平台版本 (包括最新版本)，並且提供更新工具，以便您視需要下載其他平台版本。

如要存取更新工具，請使用位於 <sdk>/tools 目錄的 android 指令列工具。您可以透過執行 android sdk 啟動 SDK 更新工具，也可以直接按兩下 android.bat (Windows) 或 android (OS X/Linux) 檔案。

如要透過模擬器在不同平台版本中執行應用程式，請為要測試的每個平台版本建立 AVD。如要進一步瞭解 AVD，請參閱「建立及管理虛擬裝置」。如果您要使用實體裝置進行測試，請務必瞭解其執行 Android 平台的 API 級別。建議您參閱本文件表格中列出的平台版本及其 API 級別。

按照 API 級別篩選參考文件

在 Android 平台的參考說明文件中，每頁左上方都有一個「API 級別」控制項。您可以使用這個控制項，根據應用程式在資訊清單檔案 android:minSdkVersion 屬性中指定的 API 級別，讓系統只顯示該應用程式實際可用 API 部分的對應說明文件。

如要使用篩選功能，請從選單中選取應用程式指定的 API 級別。在較新 API 級別中導入的 API 隨即會顯示為灰色，內容也會遭到遮蓋，因為您的應用程式無法存取這些 API。

依 API 級別篩選說明文件時，畫面上並不會顯示各個 API 級別新增或導入的項目，這個方法只是方便您查看與指定 API 級別相關聯的整個 API，但不包括後續 API 級別中導入的 API 元素。

如想回到完整說明文件的檢視畫面，請在 API 級別選單頂端選取「REL」。根據預設，API 級別篩選功能處於停用狀態，因此無論 API 級別為何，您都可以檢視完整的架構 API。

個別 API 元素的參考說明文件會具體說明導入各元素的 API 級別。在每個說明文件頁面內容區塊的右上角，皆會以「Added in API level」的格式指定套件與類別的 API 級別。右側邊界的詳細說明標頭中會指定類別成員的 API 級別。