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 級別 (例如,不同於主要版本或主要版本和次要版本的總和)。

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

屬性:
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 13 (Beta 版) 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 級別>」形式指定套件與類別的 API 級別。位於右邊界的詳細說明標頭中會指定類別成員的 API 級別。