Android開發-API指南-<uses-sdk>

標籤：

<uses-sdk>

英文原文：http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
採集（更新）日期：2014-5-7
搬遷自原部落格：http://blog.sina.com.cn/s/blog_48d491300100zmx9.html

在本文中

1. 什麼是 API 層級
2. API 層級在 Android 中的用途
3. 開發時的注意事項
   1. 應用程式的向前相容性
   2. 應用程式的向後相容性
   3. 選擇平台版本和 API 層級
   4. 聲明最低 API 層級
   5. 針對高版本 API 層級進行測試
4. 使用臨時 API 層級
5. 根據 API 層級篩選參考文檔

Google Play 過濾機制

Google Play 使用 manifest 中的 < uses-sdk >屬性對應用程式進行過濾，將不符合系統版本需求的裝置排除掉。在設定此屬性之前，請確認自己已經完全理解了Google Play 過濾器

文法：

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

包含於：

<manifest>

說明：

用於表明應用程式與一個或多個版本 Android 平台的相容性，以整數型的 API 層級來表示。 應用程式聲明的 API 層級將與給定的 Android 系統進行比較，不同 Android 裝置的 API Level 可能各不相同。

不要去理會名稱（指 uses-sdk），本元素是用於指定 API 層級 的，而不是指 SDK （軟體開發包）或 Android 平台的版本號碼。 API 層級總是以一個整數值來表示。 API 層級是無法從相應的 Android 版本號碼推匯出來的（比如，它既不是主要版本號，也不是主要版本號加小版本號碼）。

請參閱文檔 將應用程式版本化。

屬性：

android:minSdkVersion

整數值，指定運行應用程式所需的最低 API 層級。 如果系統 API 層級低於本屬性設定的值， Android 系統將阻止使用者安裝此應用程式。 本屬性必需指定。

提醒： 如果未聲明本屬性，系統假定預設值為“1”，這表示應用程式與所有版本的 Android 相容。 如果應用程式無法相容所有版本（比如，用到了 API 層級 3 才開始引入的 API ）， 也沒有聲明正確的 android:minSdkVersion， 那麼安裝在低於 API 層級 3 的系統中後，一旦在運行過程中試圖訪問停用 API，應用程式就會崩潰。 因此，請確保在 minSdkVersion 屬性中聲明正確的 API 層級。

android:targetSdkVersion

整數值，指定應用程式的目標 API 層級。如果不設定本屬性，預設值等於已給定的 minSdkVersion。

本屬性將告知系統應用程式已經針對此目標版本進行了測試，系統不會啟用任何與此目標版本相關的向前相容特性。 應用程式仍然能夠在較低版本（最低至 minSdkVersion）的系統上運行。

隨著 Android 的版本更新，某些特性甚至組件外觀都會發生變化。 不過，當平台的 API 層級高於應用程式聲明的 targetSdkVersion時，系統會啟用相容性特性，應用程式仍然可以按預計方式運行。 通過把 targetSdkVersion 設定為所需的平台版本，你可以禁用相容特性。 比如，將本值設定為大於等於“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 層級，系統就會阻止該程式的安裝。 實際上，當系統更新後對應用程式進行重校正時，系統將會從裝置上刪除該應用程式。

為了說明本屬性在系統更新後對應用程式的影響，請參閱以下例子：

某應用程式在 manifest 中聲明了 maxSdkVersion="5" ，並已在 Google Play 進行了發布。 有一個使用者下載並安裝了此應用程式，他的裝置啟動並執行是 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，應用程式可以用這些 API 與底層系統進行互動。 這套API由以下部分組成：

• 核心包和類
• Manifest 檔案中使用的 XML 格式的元素和屬性聲明
• 聲明和訪問資源時所用的 XML 格式的元素和屬性
• 一些預設的 Intent
• 應用程式可請求的許可權以及系統預設的許可權

Android 平台每個較高版本都會包含之前的 API 更新。

API 的更新機制使得新版本的 API 可以與早期版本保持相容。 也就是說，大部分的 API 改動都是新增功能，或是引入新 API ，或是替代原有功能。 作為 API 升級過程中的一部分工作，被替換的舊功能被視為過時功能但不會被刪除。 因此，現有的應用程式仍然可以使用這些過時的功能。 在極少數情況下，一部分 API 可能會被修改或刪除，通常這種改動只是為了確保 API 的穩定性及應用程式或系統的安全性。 早期版??本的 API 剩餘部分都將原封不動地帶入新版本。

Android 平台提供的每個版本的 API 都用一個整數值標識，名為“API層級”。 每個版本的 Android 平台只對應支援一個 API 層級，雖然這隱含了對所有之前版本 API 層級的支援（直至 API 層級 1）。 Android 平台的第一個版本提供了 API 層級 1 ，後續版本的層級依次遞增。

下表給出了 Android 平台每個版本對應支援的 API 層級。 有關各個版本 Android 裝置的數量佔比情況，請參閱 平台版本統計。

平台版本	API 層級	VERSION_CODE	備忘
Android 4.4	19	KITKAT	特點
Android 4.3	18	JELLY_BEAN_MR2	特點
Android 4.2, 4.2.2	17	JELLY_BEAN_MR1	特點
Android 4.1, 4.1.1	16	JELLY_BEAN	特點
Android 4.0.3, 4.0.4	15	ICE_CREAM_SANDWICH_MR1	特點
Android 4.0, 4.0.1, 4.0.2	14	ICE_CREAM_SANDWICH
Android 3.2	13	HONEYCOMB_MR2
Android 3.1.x	12	HONEYCOMB_MR1	特點
Android 3.0.x	11	HONEYCOMB	特點
Android 2.3.4 Android 2.3.3	10	GINGERBREAD_MR1	特點
Android 2.3.2 Android 2.3.1 Android 2.3	9	GINGERBREAD
Android 2.2.x	8	FROYO	特點
Android 2.1.x	7	ECLAIR_MR1	特點
Android 2.0.1	6	ECLAIR_0_1
Android 2.0	5	ECLAIR
Android 1.6	4	DONUT	特點
Android 1.5	3	CUPCAKE	特點
Android 1.1	2	BASE_1_1
Android 1.0	1	BASE

API 層級在 Android 中的用途

API 層級在保證使用者和應用程式開發人員的最佳體驗方面發揮了關鍵性作用：

• Android 平台可以用它描述所支援的最高 API 版本。
• 應用程式可以用它描述所需要的 API 版本。
• 系統可以用它檢驗應用程式在使用者裝置上的可安裝性，版本不相容的應用程式將不會安裝。

每個版本的Android平台都在其內部儲存了自己的 API 層級號。

應用程式可以用 API 提供的 manifest 元素 — <uses-sdk> — 描述可正常啟動並執行最低、最高 API 層級，以及預期應支援的 API 層級。該元素給出了三個關鍵屬性：

• android:minSdkVersion — 指明應用程式可以啟動並執行最低 API 層級。預設值是“1”。
• android:targetSdkVersion — 指明設計應用程式時期望啟動並執行 API 層級。某些情況下，應用程式可通過本屬性使用目標 API 層級中定義的 manifest 元素或特性，而不限於使用最低 API 層級定義的內容。
• android:maxSdkVersion — 指明該應用程式可以啟動並執行最高 API 層級。重點： 使用該屬性之前請先閱讀文檔<uses-sdk>。

例如，為了指定運行所需的最低 API 層級，應用程式應該在其 manifest 的 <uses-sdk> 元素中包含 android:minSdkVersion 屬性。android:minSdkVersion 的值應該是一個整數，對應於應用程式可啟動並執行最早 Android 版本 的 API 層級。

當使用者嘗試安裝某應用程式時，或者在系統升級後對應用程式重新校正時，Android 系統首先會檢查應用程式 manifest 中的 <uses-sdk> 屬性，並將其值與系統內部的 API 層級進行比較。只有滿足以下條件時，系統才會允許應用程式的安裝：

• 如果聲明了android:minSdkVersion屬性，則其值必須小於等於當前系統的 API 層級值。如果未聲明，系統就會假定該應用程式運行需要的最低 API 層級是 1 。
• 如果聲明了android:maxSdkVersion屬性，則其值必須大於等於當前系統的 API 層級值。如果未聲明，系統就會假定該應用程式沒有最高 API 層級的限制。關於系統如何處理該屬性的更多資訊，請閱讀文檔<uses-sdk>。

如果應用程式的 manifest 檔案中進行了聲明，則 <uses-sdk> 元素看起來應如下所示：

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

應用程式都應該在 android:minSdkVersion 中聲明 API 層級， 主要目的是為了告訴 Android 系統，它將會用到給定 API 層級引入的 API。 如果由於某種原因應用程式被安裝到了 API 層級較低的平台上，那麼一旦去訪問那些不存在的API時，它就會崩潰。 如果所需的最低 API 層級高於目標裝置的平台版本，則系統就會禁止應用程式的安裝，這樣就防止了上述情況的發生。

例如， android.appwidget 包是 API 層級 3 開始引入的。 如果某應用程式用到了此 API，就必須聲明 android:minSdkVersion 屬性為 3。 這樣，該應用程式就可以在 Android 1.5（API 層級 3 ）、Android 1.6 （API 層級 4） 等平台上安裝， 而無法安裝到 Android 1.1 （API 層級 2）和 Android 1.0 （API 層級 1）平台上。

關於指定應用程式所需 API 層級的更多資訊，請參閱 manifest 檔案的 <uses-sdk> 部分。

開發時的注意事項

以下章節描述了開發應用程式時應該考慮的有關 API 層級的內容。

應用程式的向前相容性

Android 應用程式通常向前相容較新版本的 Android 平台

幾乎所有的 API 變動都是遞增的，因此使用給定版本 API （由 API 層級來指定）開發的應用程式都是與後續版本 Android 及更進階別 API 相相容的。 應用程式應該可以在任何高版本的 Android 平台上運行，除非它用到了之後因某種原因被移除的 API。

向前相容性非常重要，因為很多 Android 裝置會收到無線（over-the-air ，OTA）系統更新提醒。 使用者可能在安裝和使用應用程式時一切正常，然後收到 OTA 更新並升級到新版本的 Android 平台。 一旦升級完成，應用程式就要在一個新版本的環境下運行，這個環境也包含了應用程式所需的 API 和系統功能。

某些情況下，隱藏在 API 背後的變化（比如系統底層的變化）可能會對運行於新環境下的應用程式造成影響。 因此，作為開發人員有一點非常重要，就是瞭解應用程式在各種系統內容下的外觀和行為。 為了協助你在各種版本的 Android 平台上測試應用程式，Android SDK 包含了多個版本的平台以供下載。 每個版本的平台都包含了相容的系統鏡像，你可以在相應版本的 AVD （模擬器）運行這些鏡像，以便對應用程式進行測試。

應用程式的向後相容性

Android 應用程式並不是非要向後相容於比編譯環境更早的 Android 平台版本。

Android 平台的每個新版本都可能包含新的 API ，比如提供新的平台功能，或者替代部分已有的 API 。 應用程式可以在新版本及後續版本的平台中使用這些新的API，版本的更新可以由 API 層級來反映。 反之，由於早期版本的平台不包含這些新的 API，用到新 API 的應用程式在舊版的平台上是無法啟動並執行。

雖然 Android 裝置不太可能會降級到以前的系統版本，但你必須意識到：會有很多裝置仍然運行著老版本的系統。 即便是那些收到 OTA 更新訊息的裝置，有些仍然會延遲更新甚至長時間未完成更新。

選擇平台版本和 API 層級

在開發應用程式時，你需要選擇一個平台版本，以便基於此版本 Android 平台進行編譯。 通常，你應該選擇可支援的最低版本進行編譯。

你可以逐次遞減目標版本並進行編譯，以便確定最低可支援的平台版本。 一旦確定了最低的版本，你就應該建立相應版本（即 API 層級）的 AVD ，並全面測試你的應用程式。 請確保在應用程式的 manifest 中申明 android:minSdkVersion屬性，並賦予相應版本的 API 層級。

聲明最低 API 層級

如果你的應用程式用到了最新版本平台才引入的 API 或系統特性，你就應該將 android:minSdkVersion 屬性設為該版本對應的 API 層級。 這將確保使用者只能在運行所需相容版本 Android 的裝置上安裝你的應用程式。 進而保證能在他們的裝置上正常使用你的應用程式。

如果應用程式用到了最新版本平台引入的 API，但卻沒有聲明 android:minSdkVersion 屬性， 那它在最新平台上是會正常運行，但是在早期版本的平台上卻不行。 在後一種情況下，一旦應用程式試圖訪問舊平台上不存在的 API，它就會崩潰。

針對高版本 API 層級進行測試

應用程式編譯完畢後，你必須在 android:minSdkVersion 屬性設定的版本上進行測試。 請用相應的版本建立 AVD 來完成測試。 此外，為了確保向前相容性，你還應該在所有高於所需 API 層級的版本上運行和測試應用程式。

Android SDK 包含了包括最新版本在內的多版本平台以供使用，並且還提供了升級工具，用於下載所需要的其他版本。

要使用升級工具，請使用 android 命令列工具，該工具位於 <sdk>/tools 目錄中。 你可以執行 android sdk 命令來啟動 SDK 升級工具，也可以簡單地雙擊 android.bat （Windows下）或 android （OS X/Linux）檔案。 在 ADT 中，你還可以選擇菜單Window > Android SDK Manager來訪問升級工具。

為了讓應用程式能在多個版本的模擬器上運行，請為每個要測試的版本都建立一個 AVD 裝置。 關於 AVD 的更多資訊，請參閱 建立並管理模擬器。 如果你使用物理裝置進行測試，請確認它的 Android 平台的 API 層級。 請參閱本文開頭的平台版本和 API 層級對照表。

使用臨時 API 層級

有時候，可能會存在一種“早期預覽”（Early Look）版的 Android 平台 SDK。 儘管這時的 API 可能不是最終版本，但為了能在此版本上著手開發，就不會設定此類平台的 API 層級。 你必須在 manifest 中換用此版本平台的 provisional API Level ，以便建立與此版本對應的應用程式。 臨時 API層級 不是一個整數，而是一個表示未發布平台版本的字串名稱。 “早期預覽”版本的臨時 API 層級將會在發布說明中進行設定，且為大小寫敏感的。

臨時 API 層級的用途是為了防止開發人員無意中發布或使用者不小心安裝了基於“早期預覽”版 API 開發的應用程式， 這些應用程式可能無法穩定運行於最終的系統上。

臨時 API 層級僅在使用早期預覽版的 SDK 時才有效，並且只能運行於模擬器之中。 使用臨時 API 層級的應用程式永遠都無法安裝到 Android 裝置中。 在最終版本發布後，你必須將 manifest 中的所有臨時 API 層級替換成最終平台的實際 API 層級值。

根據 API 層級過濾參考文檔

在 Android Developers 網站的參考文檔頁面的右上方，有一個“根據 API 層級篩選 ”（“Filter by API Level”）的選項。 （譯者注：經核實，此選項目前在頁面左側，可直接下拉選擇各 API Level 。） 利用這個選項，你可以只顯示應用程式實際用到的那部分 API 文檔，這是根據 Manifest 檔案中的 android:minSdkVersion 屬性值指定的 API 層級來確定的。

要使用篩選功能，請選中搜尋方塊下面的勾選框。 （譯者注：經核實，未找到此勾選框，也許是文檔未更新。） 然後將“Filter by API Level”選項設定為應用程式指定的 API 層級。 你可以看到，因為應用程式無法訪問指定層級之後才引入的 API ，這些新 API 的內容會標記為灰色。

根據 API 層級進行篩選的功能並不會為每個 API 層級的新增內容都提供一個新的頁面， 它只是給出一種完整展現某層級 API 內容的方法，並去除了後續版本引入的 API 內容。

如果你不需要篩選 API 文檔，只要通過勾選框禁用即可。 API 層級篩選預設是被禁用的，因此你可以看到全部的 API，而不必去關心 API 層級。

還有一點需要注意，每個單獨的 API 參考文檔頁面都指明了該 API 是從哪個層級開始引入的。 包和類的 API 層級在每個文檔頁面的右上方“Since <api level>”部分進行了說明。 類成員的 API 層級在其詳細資料的上部右側進行了說明。

Android開發-API指南-<uses-sdk>