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

語法:
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
包含於:
<manifest>
說明:

供您透過 API 級別數字,表達應用程式與 Android 平台版本的相容性。系統會將應用程式表示的 API 級別與特定 Android 系統的 API 級別進行比較,其結果會因在不同 Android 裝置上而異。

即使名稱如此,這個元素用於指定 API 級別,而「不是」 SDK 軟體的版本號碼 (軟體開發套件) 或 Android 平台。API 級別一律為單一整數。您無法從相關的 Android 版本號碼衍生 API 級別 (例如,API 級別與主要版本不同,也不等於主要版本和子版本號碼的總和)。

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

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

注意:如果未宣告這項屬性,系統會假設其值為預設值「1」,這表示應用程式與所有 Android 版本相容。如果應用程式「並非」與所有版本相容,例如應用程式使用 API 級別 3 中導入的 API,且您未宣告適當的 minSdkVersion,則當應用程式安裝在 API 級別低於 3 的系統上時,會因為嘗試存取未提供的 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 元素和屬性
  • 一組 Intents
  • 一組應用程式可要求的權限,以及系統提供的權限違規處置措施

每個連續版本的 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 14 API 33 → Beta 版 1 UPSIDE_DOWN_CAKE 平台特點
Android 13 33 TIRAMISU 平台特點
Android 12 32 S_V2 平台特點
31 S 平台特點
Android 11 30 R 平台特點
Android 10 29 Q 平台特點
Android 9 28 P 平台特點
Android 8.1 27 O_MR1 平台特點
Android 8.0 26 O 平台特點
Android 7.1.1
Android 7.1
25 N_MR1 平台特點
Android 7.0 24 N 平台特點
Android 6.0 23 M 平台特點
Android 5.1 22 LOLLIPOP_MR1 平台特點
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH KitKat 僅適用於穿戴式裝置
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 級別識別碼內部儲存在 Android 系統本身中。

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

  • android:minSdkVersion — 指定應用程式可執行的最低 API 級別。預設值為「1」。
  • android:targetSdkVersion — 指定應用程式在哪個 API 級別上執行。在某些情況下,這個屬性可讓應用程式使用目標 API 級別中定義的資訊清單元素或行為,而不是只使用最低 API 級別定義的元素或行為。
  • android:maxSdkVersion — 指定應用程式可在其上執行的最高 API 級別。重要提示:請先詳閱 <uses-sdk> 說明文件,再使用這個屬性。

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

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

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

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

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

應用程式要在 android:minSdkVersion 中宣告 API 級別的主要原因是告知 Android 系統,應用程式使用的是指定 API 級別中「導入」的 API。如果應用程式基於不明原因安裝在 API 級別較低的平台上,就會因為嘗試存取不存在的 API 而在執行階段停止運作。如果應用程式需要的最低 API 級別高於目標裝置上的平台版本 API 級別,系統就不允許安裝應用程式,以免產生這種結果。

舉例來說,android.appwidget 套件是隨著 API 級別 3 所導入。如果應用程式使用該 API,則必須使用「3」的值宣告 android:minSdkVersion 屬性。然後,應用程式便可安裝在 Android 1.5 版本 (API 級別 3) 和 Android 1.6 版本 (API 級別 4) 等平台上,但無法安裝在 Android 1.1 (API 級別 2) 和 Android 1.0 (API 級別 1) 平台上。

如需進一步瞭解如何指定應用程式 API 級別相關規定,請參閱資訊清單檔案說明文件的 <uses-sdk> 一節。

開發注意事項

以下各節提供開發應用程式時應納入考量的 API 級別相關資訊。

應用程式前進相容性

Android 應用程式通常與新版本的 Android 平台前進相容。

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

許多搭載 Android 的裝置都會收到無線更新 (OTA) 系統更新,因此請務必設定前進相容性。使用者可能會安裝您的應用程式並成功使用,不久後就會收到新版 Android 平台的 OTA 更新通知。安裝更新之後,應用程式就會在新的執行階段版本環境中執行,但其中包含應用程式所依附的 API 和系統功能。

在某些情況下,該 API「之下」的的變更 (例如基礎系統本身的變更) 可能會影響在新環境中執行的應用程式。因此,應用程式開發人員必須瞭解應用程式在各個系統環境中的外觀和行為。為了協助您在各種版本的 Android 平台上測試應用程式,Android SDK 提供多個可下載的平台。每個平台都包含一個相容系統映像檔,您可以在 AVD 中執行該映像檔,以測試應用程式。

應用程式回溯相容性

如果是比編譯所用版本更舊的 Android 平台,Android 應用程式未必具備回溯相容性。

每個新版本的 Android 平台都可以包含新的架構 API,例如可讓應用程式存取新平台功能或取代現有 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 元素。

如果您不想篩選 API 說明文件,只要使用核取方塊停用這項功能即可。根據預設,API 級別篩選功能處於停用狀態,因此無論 API 級別為何,您都可以檢視完整的架構 API。

另請注意,個別 API 元素的參考說明文件具體說明導入各元素的 API 級別。在每個說明文件頁面內容區塊的右上角,皆會以「Since <api level>」的格式指定套件與類別的 API 級別。位於右邊界的詳細說明標頭中會指定類別成員的 API 級別。