Google Play 會利用在應(yīng)用清單中聲明的 <uses-sdk> 屬性，從不符合其平臺版本要求的設(shè)備上濾除您的應(yīng)用。在設(shè)置這些屬性前，請確保您了解 Google Play 過濾器。

語法：

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

　　

 

包含它的文件：

<manifest>

說明：

您可以通過整數(shù)形式的 API 級別表示應(yīng)用與一個或多個版本的 Android 平臺的兼容性。應(yīng)用表示的 API 級別將與給定 Android 系統(tǒng)的 API 級別進行比較，其結(jié)果在不同 Android 設(shè)備上可能有所差異。

盡管名稱如此，但該元素實際用于指定 API 級別，而非 SDK（軟件開發(fā)工具包）或 Android 平臺的版本號。API 級別始終是單個整數(shù)。您無法通過 API 級別關(guān)聯(lián)的 Android 版本號來推知 API 級別（例如，它不同于主版本號，也不同于主版本號與次版本號之和）。

另請閱讀有關(guān)對應(yīng)用進行版本控制的文檔。

屬性：

android:minSdkVersion

一個用于指定應(yīng)用運行所需最低 API 級別的整數(shù)。如果系統(tǒng)的 API 級別低于該屬性中指定的值，Android 系統(tǒng)將阻止用戶安裝應(yīng)用。您應(yīng)始終聲明該屬性。

注意：如果您不聲明該屬性，系統(tǒng)將假定默認值為“1”，這表示您的應(yīng)用兼容所有 Android 版本。如果您的應(yīng)用并不兼容所有版本（例如，它使用 API 級別 3 中引入的 API），并且您尚未聲明正確的 minSdkVersion，則當應(yīng)用安裝在 API 級別小于 3 的系統(tǒng)上時，應(yīng)用將在運行時嘗試訪問不可用的 API 時發(fā)生崩潰。因此，請務(wù)必在 minSdkVersion 屬性中聲明合適的 API 級別。

android:targetSdkVersion

一個用于指定應(yīng)用的目標 API 級別的整數(shù)。如果未設(shè)置，其默認值與為 minSdkVersion 指定的值相等。

該屬性用于通知系統(tǒng)，您已針對目標版本進行測試，并且系統(tǒng)不應(yīng)通過啟用任何兼容性行為，以保持您的應(yīng)用與目標版本的向前兼容性。應(yīng)用仍可在較低版本上運行（最低版本為 minSdkVersion）。

Android 會隨新版本的推出而逐漸發(fā)展，在此過程中，某些行為乃至外觀可能會發(fā)生變化。不過，如果平臺的 API 級別高于應(yīng)用 targetSdkVersion 所聲明的版本，系統(tǒng)便可通過啟用兼容性行為，確保應(yīng)用繼續(xù)以您所期望的方式工作。您可以將 targetSdkVersion 指定為符合應(yīng)用所運行平臺的 API 級別，從而停用此類兼容性行為。例如，如果將該值設(shè)置為“11”或更高，系統(tǒng)便可在應(yīng)用運行在 Android 3.0 或更高版本的平臺上時對其應(yīng)用新的默認主題 (Holo)，還可在應(yīng)用運行在更大屏幕上時停用屏幕兼容性模式（因為對 API 級別 11 的支持隱含了對更大屏幕的支持）。

系統(tǒng)可根據(jù)您為該屬性設(shè)置的值啟用許多兼容性行為。Build.VERSION_CODES 參考資料中的相應(yīng)平臺版本介紹了其中幾種行為。

如要讓應(yīng)用與各 Android 版本保持同步，您應(yīng)增加該屬性的值，使其與最新 API 級別一致，然后在相應(yīng)平臺版本上對應(yīng)用進行全面測試。

引入的版本：API 級別 4

android:maxSdkVersion

一個指定作為應(yīng)用設(shè)計運行目標的最高 API 級別的整數(shù)。

在 Android 1.5、1.6、2.0 及 2.0.1 中，系統(tǒng)會在安裝應(yīng)用時，以及系統(tǒng)更新后重新驗證應(yīng)用時檢查該屬性的值。任一情況下，如果應(yīng)用的 maxSdkVersion 屬性低于系統(tǒng)本身使用的 API 級別，則系統(tǒng)將不允許安裝應(yīng)用。在系統(tǒng)更新后重新驗證的情況下，這實際相當于將您的應(yīng)用從設(shè)備中移除。

為說明該屬性在系統(tǒng)更新后對應(yīng)用的影響，請查看以下示例：

Google Play 上發(fā)布了一個在其清單中聲明 maxSdkVersion="5" 的應(yīng)用。一位設(shè)備運行 Android 1.6（API 級別 4）的用戶下載并安裝了該應(yīng)用。幾周后，該用戶收到 Android 2.0（API 級別 5）OTA 系統(tǒng)更新。更新安裝后，系統(tǒng)檢查該應(yīng)用的 maxSdkVersion 并順利對其完成重新驗證。應(yīng)用仍可照常工作。不過，一段時間后，設(shè)備再次收到系統(tǒng)更新，這次是更新到 Android 2.0.1（API 級別 6）。更新完成后，系統(tǒng)無法再重新驗證應(yīng)用，因為此時系統(tǒng)本身的 API 級別 (6) 已超過該應(yīng)用支持的最高級別 (5)。系統(tǒng)會使該應(yīng)用對用戶不可見，實際相當于將應(yīng)用從設(shè)備上刪除。

警告：不建議聲明該屬性。首先，您沒有必要設(shè)置該屬性，并將其作為阻止您的應(yīng)用部署至新版本 Android 平臺的一種手段。從設(shè)計上講，新版本平臺完全向后兼容。只要您的應(yīng)用僅使用標準 API 并遵循部署最佳實踐，其應(yīng)能夠在新版本平臺上正常工作。其次，請注意在某些情況下，聲明該屬性可能會導致您的應(yīng)用在系統(tǒng)更新至更高 API 級別后從用戶設(shè)備中移除。大多數(shù)可能安裝您應(yīng)用的設(shè)備都會定期收到 OTA 系統(tǒng)更新，因此您應(yīng)在設(shè)置該屬性前考慮這些更新對應(yīng)用的影響。

引入的版本：API 級別 4

在安裝或重新驗證時，未來的 Android 版本（Android 2.0.1 之后的版本）將不再檢查或強制執(zhí)行 maxSdkVersion 屬性。不過，在向用戶呈現(xiàn)可供下載的應(yīng)用時，Google Play 會繼續(xù)使用該屬性作為過濾器。

引入的版本：

API 級別 1

什么是 API 級別？

API 級別是對 Android 平臺版本提供的框架 API 修訂版進行唯一標識的整數(shù)值。

Android 平臺提供一種框架 API，應(yīng)用可利用它與底層 Android 系統(tǒng)進行交互。該框架 API 由以下部分組成：

• 一組核心軟件包和類
• 一組用于聲明清單文件的 XML 元素和屬性
• 一組用于聲明和訪問資源的 XML 元素和屬性
• 一組 Intent
• 一組應(yīng)用可請求的權(quán)限，以及系統(tǒng)中包括的權(quán)限強制執(zhí)行

Android 平臺的每個后續(xù)版本均可包括其提供的 Android 應(yīng)用框架 API 的更新。

框架 API 更新的設(shè)計用途是使新 API 與早期版本的 API 保持兼容。換言之，大多數(shù) API 更改都是新增更改，并且會引入新功能或替代功能。在 API 的某些部分得到升級時，系統(tǒng)會棄用經(jīng)替換的舊版部分，但不會將其移除，以便其仍可供現(xiàn)有應(yīng)用使用。在極少數(shù)情況下，系統(tǒng)可能會修改或移除 API 的某些部分，但通常只有在為確保 API 穩(wěn)健性以及應(yīng)用或系統(tǒng)安全性時，才需要進行此類更改。所有其他來自早期修訂版的 API 部分都將繼續(xù)保留，不做任何修改。

Android 平臺提供的框架 API 使用稱為“API 級別”的整數(shù)標識符指定。每個 Android 平臺版本恰好支持一個 API 級別，但隱含對所有早期 API 級別（低至 API 級別 1）的支持。Android 平臺初始版本提供的是 API 級別 1，后續(xù)版本的 API 級別則依次增加。

下表列出了各 Android 平臺版本所支持的 API 級別。如需了解有關(guān)運行各版本的設(shè)備相對數(shù)量的信息，請參閱“平臺版本”信息中心頁面。

API 級別在 Android 中的使用

在確保盡可能為用戶和應(yīng)用開發(fā)者提供最佳體驗方面，API 級別標識符發(fā)揮著重要作用：

• 它允許 Android 平臺描述其支持的最高框架 API 修訂版
• 它允許應(yīng)用描述其需要的框架 API 修訂版
• 它允許系統(tǒng)協(xié)商在用戶設(shè)備上安裝應(yīng)用，從而不安裝非兼容版本的應(yīng)用。

每個 Android 平臺版本都將其 API 級別標識符存儲在 Android 系統(tǒng)自身內(nèi)部。

應(yīng)用可利用框架 API 提供的清單元素 (<uses-sdk>) 來說明其可運行的最低和最高 API 級別，以及其支持的首選 API 級別。該元素具有以下三個重要屬性：

• android:minSdkVersion — 指定能夠運行應(yīng)用的最低 API 級別。默認值為“1”。
• android:targetSdkVersion — 指定運行應(yīng)用的目標 API 級別。在某些情況下，此屬性允許應(yīng)用使用在目標 API 級別中定義的清單元素或行為，而非僅限于使用針對最低 API 級別定義的元素或行為。
• android:maxSdkVersion — 指定能夠運行應(yīng)用的最高 API 級別。重要說明：在使用該屬性之前，請先閱讀 <uses-sdk> 文檔。

例如，如要指定應(yīng)用運行所需的最低系統(tǒng) API 級別，應(yīng)用需在其清單中加入帶 android:minSdkVersion 屬性的 <uses-sdk> 元素。android:minSdkVersion 是一個整數(shù)值，對應(yīng)能夠運行應(yīng)用的最低版本 Android 平臺的 API 級別。

當用戶試圖安裝應(yīng)用，或在系統(tǒng)更新后重新驗證應(yīng)用時，Android 系統(tǒng)會先檢查應(yīng)用清單中的 <uses-sdk> 屬性，然后將這些屬性的值與其自己的內(nèi)部 API 級別進行對比。只有在符合以下條件時，系統(tǒng)才允許安裝開始：

• 如果聲明 android:minSdkVersion 屬性，其值必須小于或等于系統(tǒng)的 API 級別整數(shù)。如果未聲明，則系統(tǒng)假定應(yīng)用需要 API 級別 1。
• 如果聲明 android:maxSdkVersion 屬性，其值必須大于或等于系統(tǒng)的 API 級別整數(shù)。如果未聲明，則系統(tǒng)假定應(yīng)用沒有最高 API 級別。如需了解有關(guān)系統(tǒng)如何處理該屬性的詳細信息，請閱讀 <uses-sdk> 文檔。

如果在應(yīng)用清單中進行聲明，則 <uses-sdk> 元素的內(nèi)容可能如下所示：

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

應(yīng)用在 android:minSdkVersion 中聲明 API 級別的主要原因是，告知 Android 系統(tǒng)，其正使用在指定 API 級別引入的 API。如果由于某種原因?qū)?yīng)用安裝在 API 級別較低的平臺上，則它會在運行時試圖訪問不存在的 API 時發(fā)生崩潰。如果應(yīng)用所需的最低 API 級別高于目標設(shè)備上平臺版本的 API 級別，則系統(tǒng)不允許安裝該應(yīng)用，以防出現(xiàn)這種結(jié)果。

例如，android.appwidget 軟件包是隨 API 級別 3 引入的。如果應(yīng)用使用該 API，則必須使用“3”一值聲明 android:minSdkVersion 屬性。隨后，應(yīng)用便可安裝在 Android 1.5（API 級別 3）和 Android 1.6（API 級別 4）等平臺上，但不能安裝在 Android 1.1（API 級別 2）和 Android 1.0（API 級別 1）平臺上。

如需了解有關(guān)如何指定應(yīng)用 API 級別要求的詳細信息，請參閱清單文件文檔的 <uses-sdk> 部分。

開發(fā)注意事項

下文提供您在開發(fā)應(yīng)用時應(yīng)考慮的 API 級別的相關(guān)信息。

應(yīng)用向前兼容性

Android 應(yīng)用一般向前兼容新版本的 Android 平臺。

由于幾乎所有對框架 API 的更改都是新增更改，所以使用 API 任何給定版本（其 API 級別所指定版本）開發(fā)的 Android 應(yīng)用均向前兼容更新版本的 Android 平臺以及更高 API 級別。應(yīng)用應(yīng)能在所有后期版本的 Android 平臺上運行，除非在個別情況下，系統(tǒng)后來因某種原因?qū)?yīng)用使用的某個 API 部分移除。

向前兼容性非常重要，因為許多 Android 設(shè)備都會接收 OTA 系統(tǒng)更新。用戶可以安裝您的應(yīng)用并順利使用，然后通過接收 OTA 更新升級到新版本的 Android 平臺。安裝更新后，您的應(yīng)用將在新運行時版本的環(huán)境中運行，但此版本包含您應(yīng)用所依賴的 API 和系統(tǒng)功能。

在某些情況下，在該 API 之下所做的更改（例如對底層系統(tǒng)本身的更改）可能會影響在新環(huán)境中運行的應(yīng)用。因此，作為應(yīng)用開發(fā)者，您必須了解應(yīng)用在各系統(tǒng)環(huán)境中的外觀和行為。為幫助您在各種版本的 Android 平臺上測試應(yīng)用，Android SDK 提供多個可供您下載的平臺。每個平臺均包含兼容的系統(tǒng)映像，您可通過在 AVD 中運行該映像來測試應(yīng)用。

應(yīng)用向后兼容性

Android 應(yīng)用未必向后兼容比其編譯時所用目標版本更舊的 Android 平臺版本。

每個新版本的 Android 平臺都可能包含新的框架 API，例如能夠讓應(yīng)用使用新的平臺功能或替換現(xiàn)有 API 部分的 API。在新平臺上運行時，應(yīng)用可以使用這些新 API；且如上所述，在更新版本的平臺（API 級別所指定的平臺）上運行時，應(yīng)用也可使用這些新 API。反之，由于早期版本的平臺未包含新 API，因此使用新 API 的應(yīng)用無法在這些平臺上運行。

盡管 Android 設(shè)備降級至先前版本平臺的情況不太可能發(fā)生，但您必須認識到，可能有許多設(shè)備運行的是早期版本的平臺。即便是在接收 OTA 更新的設(shè)備中，有些設(shè)備的更新也可能會滯后，而且可能在相當長的時間內(nèi)無法接收更新。

選擇平臺版本和 API 級別

在開發(fā)應(yīng)用時，您需要選擇編譯應(yīng)用所用的平臺版本。一般而言，您應(yīng)根據(jù)應(yīng)用所支持平臺的最低版本編譯應(yīng)用。

您可以在編譯應(yīng)用時依次降低其使用的目標版本，從而確定可能的最低平臺版本。確定最低版本后，您應(yīng)使用相應(yīng)平臺版本（和 API 級別）創(chuàng)建 AVD，然后對您的應(yīng)用進行全面測試。請務(wù)必在應(yīng)用的清單中聲明 android:minSdkVersion 屬性，并將其值設(shè)置為平臺版本的 API 級別。

聲明最低 API 級別

構(gòu)建應(yīng)用時，如果您使用最新平臺版本中引入的 API 或系統(tǒng)功能，則應(yīng)將 android:minSdkVersion 屬性設(shè)置為最新平臺版本的 API 級別。如此一來，便可確保用戶只能在運行兼容版 Android 平臺的設(shè)備上安裝您的應(yīng)用，并進而確保您的應(yīng)用可以在用戶設(shè)備上正常工作。

如果您的應(yīng)用使用最新平臺版本中引入的 API，但未聲明 android:minSdkVersion 屬性，則該應(yīng)用可在運行最新版本平臺的設(shè)備上正常工作，但無法在運行早期版本平臺的設(shè)備上正常工作。在后一種情況下，當在運行時試圖使用早期版本上不存在的 API 時，應(yīng)用將發(fā)生崩潰。

針對更高 API 級別進行測試

編譯應(yīng)用之后，您應(yīng)確保在應(yīng)用的 android:minSdkVersion 屬性所指定的平臺上對其進行測試。為此，請使用您應(yīng)用所需的平臺版本創(chuàng)建 AVD。此外，為確保向前兼容性，您還應(yīng)在所有 API 級別高于您應(yīng)用 API 級別的平臺上運行并測試您的應(yīng)用。

Android SDK 提供多個可供您使用的平臺版本（包括最新版本），以及可供您在必要時下載其他平臺版本的更新器工具。

如要訪問該更新器，請使用位于 <sdk>/tools 目錄的 android 命令行工具。您可以通過執(zhí)行 android sdk 來啟動 SDK 更新器。您還可直接雙擊 android.bat (Windows) 或 Android (OS X/Linux) 文件。

如要在模擬器中的不同平臺版本上運行應(yīng)用，請為您想測試的每個平臺版本創(chuàng)建 AVD。如需了解有關(guān) AVD 的詳細信息，請參閱創(chuàng)建和管理虛擬設(shè)備。如要使用物理設(shè)備進行測試，請確保您知曉其所運行 Android 平臺的 API 級別。請參閱本文頂部表格中所列的平臺版本及其 API 級別。

按 API 級別過濾參考文檔

Android Developers 網(wǎng)站在每個參考文檔頁面的右上角提供一個“Filter by API Level”控件。利用該控件，您可根據(jù)應(yīng)用在其清單文件的 android:minSdkVersion 屬性中所指定的 API 級別，只顯示該應(yīng)用實際可訪問 API 部分的對應(yīng)文檔。

如要使用過濾功能，請選擇頁面搜索框下方用于啟用過濾功能的復選框。然后將“Filter by API Level”控件設(shè)置為應(yīng)用所指定的同一 API 級別。請注意，后期 API 級別中引入的 API 隨即會灰顯，并且系統(tǒng)會屏蔽其內(nèi)容，因為您的應(yīng)用將無法訪問它們。

如果在文檔中按 API 級別進行過濾，則您并不能查看各 API 級別新增或引入的 API — 它僅僅是提供一種途徑，讓您能夠查看與給定 API 級別關(guān)聯(lián)的整個 API，同時將后期 API 級別中引入的 API 元素排除在外。

如果您決定不想過濾 API 文檔，只需使用復選框停用該功能。默認情況下，系統(tǒng)會停用 API 級別過濾，這樣無論 API 級別如何，您都能查看完整的框架 API。

另請注意，各 API 元素的參考文檔指定引入各元素的 API 級別。各文檔頁面內(nèi)容區(qū)域的右上角會以“Since <api 級別>”的形式指定軟件包和類的 API 級別。詳細說明標頭（位于右邊距處）中會指定類成員的 API 級別。