了解 Android API 層級

  • 發行項

Xamarin.Android 有數個 Android API 層級設定，可判斷應用程式與多個 Android 版本的相容性。 本指南說明這些設定的意義、如何設定它們，以及在執行時間對您的應用程式有何影響。

快速入門

Xamarin.Android 公開三個 Android API 層級專案設定：

  • 目標 Framework – 指定要在建置應用程式時使用的架構。 Xamarin.Android 會在 編譯 時期使用此 API 層級。

  • 最低 Android 版本 – 指定您想要您的應用程式支援的最舊 Android 版本。 Android 會在 運行 時間使用此 API 層級。

  • 目標 Android 版本 – 指定應用程式要執行所在的 Android 版本。 Android 會在 運行 時間使用此 API 層級。

您必須先安裝該 API 層級的 SDK 平臺元件，才能設定專案的 API 層級。 如需下載及安裝 Android SDK 元件的詳細資訊，請參閱 Android SDK 安裝程式。

注意

從 2021 年 8 月開始，Google Play 主控台要求新的應用程式目標 API 層級 30 (Android 11.0) 或更高版本。 從 2021 年 11 月開始，需要現有的應用程式以 API 層級 30 或更新版本為目標。 如需詳細資訊，請參閱 Play Console 檔中的中的 目標 API 層級需求 。

一般而言，這三個 Xamarin.Android API 層級都會設定為相同的值。 在 [ 應用程式 ] 頁面上，將 [使用 Android 版本編譯 (Target Framework) 為最新的穩定 API 版本 (，或至少設定為具有您需要) 之所有功能的 Android 版本。 在下列螢幕擷取畫面中，目標 Framework 設定為 Android 7.1 (API 層級 25 - Nougat) ：

目標 Framework 版本預設為使用 Android 版本編譯

在 [Android 資訊清單 ] 頁面上，將 [最低 Android 版本] 設定為 [使用 SDK 編譯] 版本 ，並將 [目標 Android 版本] 設定為與下列螢幕擷取畫面中 [目標 Framework 版本] (相同的值，[目標 Android Framework] 會設定為 [Android 7.1 (Nougat) ) ：

最低和目標 Android 版本設定為 Target Framework 版本

如果您想要維持與舊版 Android 的回溯相容性，請將 [最低 Android 版本 ] 設定為您想要應用程式支援的舊版 Android。 (請注意，API 層級 14 是 Google Play 服務和 Firebase 支援所需的最低 API 層級。) 下列範例設定支援從 API 層級 14 到 API 層級 25 的 Android 版本：

使用 API 層級 25 Nougat 進行編譯，最低 Android 版本設定為 API 層級 14

如果您的應用程式支援多個 Android 版本，您的程式碼必須包含執行時間檢查，以確保您的應用程式適用于 [最低 Android 版本] 設定 (請參閱下方 的 [Android 版本的執行時間檢查 ] 以取得詳細資料) 。 如果您要取用或建立程式庫，請參閱下面的 API 層級和程式庫 ，以取得設定程式庫 API 層級設定的最佳做法。

Android 版本和 API 層級

隨著 Android 平臺演進及發行新的 Android 版本，每個 Android 版本都會獲指派唯一的整數識別碼，稱為 API 層級。 因此，每個 Android 版本都會對應至單一 Android API 層級。 因為使用者必須在較舊版本和最新版本的 Android 上安裝應用程式，所以實際 Android 應用程式必須設計成使用多個 Android API 層級。

Android 版本

每個 Android 版本都會使用多個名稱：

  • Android 版本，例如 Android 9.0
  • 程式碼 (或) 名稱，例如 Pie
  • 對應的 API 層級，例如 API 層級 28

Android 程式碼名稱可能會對應至多個版本和 API 層級 (，如下表) 所示，但每個 Android 版本都對應至一個 API 層級。

此外，Xamarin.Android 會定義對應至目前已知 Android API 層級的 組建版本代碼 。 下表可協助您在 API 層級、Android 版本、程式碼名稱和 Xamarin.Android 組建版本代碼之間轉譯， (組建版本代碼定義在 Android.OS 命名空間中) ：

名稱 版本 API 層級 已發行 組建版本代碼
Q 10.0 29 2020 年 8 月 BuildVersionCodes.Q
Pie 9.0 28 2018 年 8 月 BuildVersionCodes.P
Oreo 8.1 27 2017 年 12 月 BuildVersionCodes.OMr1
Oreo 8.0 26 2017 年 8 月 BuildVersionCodes.O
Nougat 7.1 25 2016 年 12 月 BuildVersionCodes.NMr1
Nougat 7.0 24 2016 年 8 月 BuildVersionCodes.N
Marshmallow 6.0 23 2015 年 8 月 BuildVersionCodes.M
Lollipop 5.1 22 2015 年 3 月 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 2014 年 11 月 BuildVersionCodes.Lollipop
Kitkat Watch 4.4W 20 2014 年 6 月 BuildVersionCodes.KitKatWatch
Kitkat 4.4 19 2013 年 10 月 BuildVersionCodes.KitKat
Jelly Bean 4.3 18 2013 年 7 月 BuildVersionCodes.JellyBeanMr2
Jelly Bean 4.2-4.2.2 17 2012 年 11 月 BuildVersionCodes.JellyBeanMr1
Jelly Bean 4.1-4.1.1 16 2012 年 6 月 BuildVersionCodes.JellyBean
霜淇淋三明治 4.0.3-4.0.4 15 2011 年 12 月 BuildVersionCodes.IceCreamSandwichMr1
霜淇淋三明治 4.0-4.0.2 14 2011 年 10 月 BuildVersionCodes.IceCreamSandwich
蜂窩 3.2 13 2011 年 6 月 BuildVersionCodes.HoneyCombMr2
蜂窩 3.1.x 12 2011 年 5 月 BuildVersionCodes.HoneyCombMr1
蜂窩 3.0.x 11 2011 年 2 月 BuildVersionCodes.HoneyComb
姜 餅 2.3.3-2.3.4 10 2011 年 2 月 BuildVersionCodes.GingerBreadMr1
姜 餅 2.3-2.3.2 9 2010 年 11 月 BuildVersionCodes.GingerBread
Fr 2.2.x 8 2010 年 6 月 BuildVersionCodes.Froyo
Eclair 2.1.x 7 2010 年 1 月 BuildVersionCodes.EclairMr1
Eclair 2.0.1 6 2009 年 12 月 BuildVersionCodes.Eclair01
Eclair 2.0 5 2009 年 11 月 BuildVersionCodes.Eclair
環圈圖 1.6 4 2009 年 9 月 BuildVersionCodes.Donut
蛋糕 1.5 3 2009 年 5 月 BuildVersionCodes.Cupcake
基本 1.1 2 2009 年 2 月 BuildVersionCodes.Base11
基本 1.0 1 2008 年 10 月 BuildVersionCodes.Base

如下表所示，新的 Android 版本會經常發行，有時每年發行一個以上的版本。 因此，可能會執行您應用程式之 Android 裝置的宇宙包含各種較舊和較新版本的 Android 版本。 如何保證您的應用程式會在許多不同的 Android 版本上以一致且可靠地方式執行？ Android 的 API 層級可協助您管理此問題。

Android API 層級

每個 Android 裝置只會在 一個 API 層級執行 – 此 API 層級保證每個 Android 平臺版本都是唯一的。 API 層級可精確地識別應用程式可呼叫的 API 集合版本;它會識別資訊清單專案、許可權等的組合。您以開發人員身分撰寫程式碼。 Android 的 API 層級系統可協助 Android 在裝置上安裝應用程式之前，先判斷應用程式是否與 Android 系統映射相容。

建置應用程式時，它會包含下列 API 層級資訊：

  • 應用程式要執行 的目標 Android API 層級。

  • Android 裝置必須執行應用程式 的最低 Android API 層級。

這些設定可用來確保安裝時可在 Android 裝置上正確執行應用程式所需的功能。 如果沒有，則會封鎖應用程式在該裝置上執行。 例如，如果 Android 裝置的 API 層級低於您為應用程式指定的最低 API 層級，則 Android 裝置會防止使用者安裝您的應用程式。

專案 API 層級設定

下列各節說明如何使用 SDK 管理員來準備您想要設定之 API 層級的開發環境，以及如何在 Xamarin.Android 中設定 目標 Framework、 最低 Android 版本和 目標 Android 版本 設定的詳細說明。

Android SDK 平臺

您必須先安裝對應至該 API 層級的 Android SDK 平臺版本，才能在 Xamarin.Android 中選取目標或最低 API 層級。 目標 Framework、最低 Android 版本和目標 Android 版本的可用選項範圍僅限於您已安裝的 Android SDK 版本範圍。 您可以使用 SDK 管理員來確認已安裝必要的 Android SDK 版本，而且您可以使用它來新增應用程式所需的任何新 API 層級。 如果您不熟悉如何安裝 API 層級，請參閱 Android SDK 安裝程式。

目標 Framework

目標 Framework (也稱為 compileSdkVersion) 是應用程式在建置時間編譯的特定 Android 架構版本 (API 層級) 。 此設定會指定應用程式 在執行時預期 使用哪些 API，但不會影響安裝應用程式時實際可用的 API。 因此，變更目標 Framework 設定並不會變更執行時間行為。

Target Framework 會識別應用程式連結至哪個程式庫版本–此設定會決定您可以在應用程式中使用的 API。 例如，如果您想要使用 Android 5.0 Lollipop 中引進的 NotificationBuilder.SetCategory 方法，您必須將目標架構設定為 API 層級 21 (Lollipop) 或更新版本。 如果您將專案的目標 Framework 設定為 API 層級 19 (KitKat) ，並嘗試在程式碼中呼叫 SetCategory 方法，您將會收到編譯錯誤。

建議您一律使用 最新的 可用 Target Framework 版本進行編譯。 這麼做可讓您針對任何可能由程式碼呼叫的已淘汰 API 提供有用的警告訊息。 當您使用最新的支援程式庫版本時，使用最新的目標 Framework 版本特別重要– 每個程式庫預期您的應用程式在支援程式庫的最低 API 層級或更高層級進行編譯。

若要存取 Visual Studio 中的 [目標 Framework] 設定，請在方案總管中開啟專案屬性，然後選取 [應用程式] 頁面：

專案屬性的應用程式頁面

在 [ 使用 Android 編譯使用 Android 版本編譯 ] 下的下拉式功能表中選取 API 層級，以設定目標 Framework，如下所示。

最低 Android 版本

最低 Android 版本 (也稱為 minSdkVersion) 是舊版的 Android OS (，也就是可以安裝和執行應用程式的最低 API 層級) 。 根據預設，應用程式只能安裝在符合目標 Framework 設定或更新版本的裝置上;如果 [最低 Android 版本] 設定低於 [ 目標 Framework] 設定，則您的應用程式也可以在舊版 Android 上執行。 例如，如果您將 Target Framework 設定為 Android 7.1 (Nougat) ，並將最低 Android 版本設定為 Android 4.0.3 (Ice Cream Sandwich) ，則您的應用程式可以安裝在 API 層級 15 到 API 層級 25 的任何平臺上。

雖然您的應用程式可以成功建置並安裝在此範圍的平臺上，但這並不保證它會在所有平臺上順利 執行 。 例如，如果您的應用程式安裝在 Android 5.0 (Lollipop 上) ，而且您的程式碼會呼叫只能在 Android 7.1 (Nougat) 和更新版本中使用的 API，您的應用程式將會收到執行階段錯誤，而且可能當機。 因此，您的程式碼必須在執行時間確保它只會呼叫其執行所在的 Android 裝置所支援的 API。 換句話說，您的程式碼必須包含明確的執行時間檢查，以確保您的應用程式只在最近足以支援這些 API 的裝置上使用較新的 API。 本指南稍後的 Android 版本執行時間檢查說明如何將這些執行時間檢查新增至您的程式碼。

若要存取 Visual Studio 中的 [最低 Android 版本] 設定，請在方案總管中開啟專案屬性，然後選取[Android 資訊清單] 頁面。 在 [ 最低 Android 版本 ] 下的下拉式功能表中，您可以選取應用程式的最低 Android 版本：

設定為使用 SDK 版本編譯的 Android 到目標選項下限

如果您選取 [使用 SDK 編譯] 版本，[最低 Android 版本] 會與 [目標 Framework] 設定相同。

目標 Android 版本

目標 Android 版本 (也稱為 targetSdkVersion) 是應用程式預期執行之 Android 裝置的 API 層級。 Android 使用此設定來判斷是否要啟用任何相容性行為 – 這可確保您的應用程式能繼續以預期的方式運作。 Android 使用應用程式的目標 Android 版本設定，找出哪些行為變更可以套用至您的應用程式，而不需中斷 (這是 Android 提供向前相容性) 的方式。

目標 Framework 和目標 Android 版本雖然具有非常類似的名稱，但不是相同的專案。 [目標架構] 設定會將目標 API 層級資訊傳達給 Xamarin.Android，以供 編譯時間使用，而目標 Android 版本會將目標 API 層級資訊傳達給 Android，以在運行 時間 使用， (在裝置上安裝並執行時) 。

若要在 Visual Studio 中存取此設定，請在方案總管中開啟專案屬性，然後選取[Android 資訊清單] 頁面。 在 [ 目標 Android 版本 ] 下的下拉式功能表中，您可以選取應用程式的 [目標 Android 版本]：

將目標 Android 版本設定為使用 SDK 版本編譯

建議您明確地將目標 Android 版本設定為您用來測試應用程式的最新版本 Android。 在理想情況下，它應該設定為最新的 Android SDK 版本 –這可讓您在處理行為變更之前使用新的 API。 對於大部分的開發人員，我們 不建議 將 [目標 Android 版本] 設定為 [使用 SDK 編譯] 版本。

一般而言，目標 Android 版本應該受限於最低 Android 版本和目標 Framework。 也就是說：

最低 Android 版本 = 目標 Android 版本 << = 目標 Framework

如需 SDK 層級的詳細資訊，請參閱 Android 開發人員 uses-sdk 檔。

Android 版本的執行時間檢查

隨著每個新版本的 Android 發行，架構 API 會更新以提供新的或取代功能。 除了少數例外狀況，舊版 Android 的 API 功能會轉送到較新的 Android 版本，而不需修改。 因此，如果您的應用程式在特定 Android API 層級上執行，通常能夠在較新的 Android API 層級上執行，而不需要修改。 但是，如果您也想要在舊版 Android 上執行您的應用程式，該怎麼辦？

如果您 選取低於目標 Framework 設定的最低 Android 版本，某些 API 可能無法在執行時間供您的應用程式使用。 不過，您的應用程式仍然可以在先前的裝置上執行，但功能降低。 對於對應至最低 Android 版本設定之 Android 平臺上無法使用的每個 API，您的程式碼必須明確檢查 屬性的值 Android.OS.Build.VERSION.SdkInt ，以判斷應用程式執行所在的平臺 API 層級。 如果 API 層級低於支援 您要呼叫之 API 的最低 Android 版本，則您的程式碼必須尋找正常運作的方式，而不需進行此 API 呼叫。

例如，假設我們想要使用 NotificationBuilder.SetCategory 方法來分類 在 Android 5.0 Lollipop (和更新版本) 上執行的通知，但仍希望我們的應用程式在舊版 Android 上執行，例如 Android 4.1 Jelly Bean (，其中 SetCategory 無法使用) 。 請參閱本指南開頭的 Android 版本資料表，我們會看到 Android 5.0 Lollipop 的組建版本代碼是 Android.OS.BuildVersionCodes.Lollipop 。 為了支援無法使用的舊版 Android SetCategory ，我們的程式碼可以在執行時間偵測 API 層級，而且只有在 API 層級大於或等於 Lollipop 組建版本代碼時，才會有條件地呼叫 SetCategory ：

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

在此範例中，應用程式的目標 Framework 設定為 Android 5.0 (API 層級 21) ，而其最低 Android 版本會設定為 Android 4.1 (API 層級 16) 。 因為 SetCategory API 層級和更新版本中 Android.OS.BuildVersionCodes.Lollipop 提供，所以此範例程式碼只會在實際可用時呼叫 SetCategory ， 而不會嘗試在 API 層級為 16、17、18、19 或 20 時呼叫 SetCategory 。 這些舊版 Android 上的功能只會減少到通知未正確排序 (的程度，因為它們未依類型分類) ，但通知仍會發佈給警示使用者。 我們的應用程式仍可運作，但其功能會稍微降低。

一般而言，組建版本檢查可協助您的程式碼在執行時間決定執行新方式與舊方式之間的動作。 例如：

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

沒有快速且簡單的規則說明如何在缺少一或多個 API 的舊版 Android 上執行時，減少或修改應用程式的功能。 在某些情況下， (例如 SetCategory 上述範例) ，就足以在無法使用 API 呼叫時省略它。 不過，在其他情況下，當偵測到時，您可能需要實 Android.OS.Build.VERSION.SdkInt 作替代功能，使其小於應用程式必須呈現最佳體驗的 API 層級。

API 層級和程式庫

當您建立 Xamarin.Android 程式庫專案 (例如類別庫或系結庫) 時，您只能設定 [目標 Framework] 設定 – [最低 Android 版本] 和 [目標 Android 版本] 設定無法使用。 這是因為沒有 Android 資訊清單 頁面：

只有 [使用 Android 編譯版本] 選項可用

由於產生的程式庫不是獨立應用程式，所以無法使用 [最低 Android 版本] 和 [目標 Android 版本設定] – 程式庫可以根據它封裝的應用程式，在任何 Android 版本上執行。 您可以指定程式庫的 編譯方式，但您無法預測程式庫將執行所在的平臺 API 層級。 請記住，在取用或建立程式庫時，應該觀察下列最佳做法：

  • 取用 Android 程式庫時 – 如果您要在應用程式中取用 Android 程式庫，請務必將應用程式的目標 Framework 設定設為 至少與 程式庫的目標 Framework 設定相同的 API 層級。

  • 建立 Android 程式庫時 – 如果您要建立 Android 程式庫以供其他應用程式使用，請務必將其目標 Framework 設定設為所需的最低 API 層級，才能進行編譯。

建議使用這些最佳做法來協助防止程式庫嘗試呼叫執行時間無法使用的 API (，這可能會導致應用程式當機) 。 如果您是程式庫開發人員，您應該致力於將 API 呼叫的使用限制在 API 介面區總計的小型且妥善建立的子集。 這麼做有助於確保您的程式庫可以安全地用於更廣泛的 Android 版本。

總結

本指南說明如何使用 Android API 層級來管理不同 Android 版本的應用程式相容性。 它提供設定 Xamarin.Android 目標 Framework、 最低 Android 版本和 目標 Android 版本 專案設定的詳細步驟。 它提供使用 Android SDK 管理員來安裝 SDK 套件的指示，包含如何在執行時間撰寫程式碼來處理不同 API 層級的範例，並說明如何在建立或取用 Android 程式庫時管理 API 層級。 它也提供一份完整的清單，將 API 層級與 Android 版本號碼 (相關，例如 Android 4.4) 、Android 版本名稱 (，例如 Kitkat) 和 Xamarin.Android 組建版本代碼。