Android開發者指南(10) —— Android API Levels

前言

　　本章內容為開發者指南(Dev Guide)/Appendix/Android API Levels，版本為Android3.0 r1，翻譯來自："jackeylu。

 

原文

         http://developer.android.com/guide/appendix/api-levels.html

 

Android API Levels

在本文中

API的級別是什麼?

在Android中使用API級別

開發者需要考慮的內容

應用程序的向前兼容性

應用程序的向後兼容性

平台版本和API級別的選擇

聲明最低API級別

針對高版本的API級別測試

使用臨時的API級別

通過API級別進行文檔內容過濾

參見

<uses-sdk> manifest element

當你開發你的Android應用程序時，了解該平台API變更管理的基本方法和概念是很有幫助的。同樣的，知道API級別標識以及該標識如何保障你的應用與實際硬件設備相兼容對於開發及後續的發布、維護都是有益的。

本節內容告訴你API級別的知識，以及它如何影響你開發和使用的應用。

關於如何使用“以API級別進行過濾”來使用API參考手冊，從本文末尾的文檔過濾(Filtering the documentation)中可以得到更多信息。

 

 

API級別是什麼？(What is API Level?)

API級別是一個整數值，它唯一標識了一個具體版本的Android平台，及其框架的API的版本。

Android平台提供了一套框架API，使得應用程序可以與系統底層進行交互。該框架API由以下模塊組成：

• 一組核心的包和類
• 清單(manifest)文件的XML元素和屬性聲明
• 資源文件的XML元素和屬性聲明及訪問形式
• 各類意圖(Intents)
• 應用程序可以請求的各類授權，以及系統中包含的授權執行

每個Android平台的後續版本會包括它提供的更新的Andr​​oid應用程序框架的API。

該框架的API的更新設計，使高版本的API與早期版本兼容。也就是說，在新版本API中大多數都是新增功能，和引進新的或替代的功能。作為API的部分升級，老的替換的部分已過時，但不會從新版本中刪除，使得已有的應用程序仍然可以使用它們。在極少數情況下，舊版本API的部分可能被修改或刪除，通常這種變化是為了保障API的穩定性及應用程序或系統的安全。所有其他早期版​​本的API將不做修改的保留。

一個Android平台提供的框架API，被指定一個整數標識符，稱為“API級別”。每一個版本的Android平台只支持有一個API級別，雖然該支持是隱含地包括了所有早期的API級別（一直到API級別1級）。 Andr​​oid平台的最初版本提供的框架API級別是1級，隨後的版本依次遞增。

下表說明了具體平台版本和支持的API級別的對應關系。

平台版本

API級別

Android 3.0

11

Android 2.3.3

10

Android 2.3

9

Android 2.2

8

Android 2.1

7

Android 2.0.1

6

Android 2.0

5

Android 1.6

4

Android 1.5

3

Android 1.1

2

Android 1.0

1

 

 

在Android中使用API級別(Uses of API Level in Android)

API級別標識為保證用戶和應用程序開發者的最佳體驗，起了關鍵作用：

• 它讓Android平台可以描述它支持的框架API的最高版本
• 它讓應用程序可以描述它需要的框架API版本
• 它使得系統可以在硬件設備上安裝應用程序時能夠檢查版本是否匹配，使得版本不兼容的應用程序不會被錯誤安裝在設備之上.

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

應用程序可以用框架API提供的清單文件元素 — <uses-sdk> 來描述該應用程序可以運行的最小和最大API級別，以及應用程序開發者設計期望運行的平台版本。三種屬性分別描述如下:

• android:minSdkVersion — 指明該應用程序可以運行的API最低版本。默認是“1”。
• android:targetSdkVersion — 指明該應用程序設計時期望運行的目標API版本。在某些情況下，這允許應用程序使用目標API級別下定義的清單元素或行為，而不是只限於使用最低API級別定義的內容。(譯者注：android之targetsdkversion的理解---兼容性問題)
• android:maxSdkVersion — 指明該應用程序可以運行的最高API級別。重要聲明: 使用該屬性之前請閱讀<uses-sdk>文檔。

比如，要指明一個應用程序能夠運行的最低API級別，應當在該應用程序的清單文件的<uses-sdk>元素中加入android:minSdkVersion屬性。android:minSdkVersion的值是一個正整數，對應的是該應用程序能夠運行的最低平台的API級別標識。

用戶嘗試安裝一個應用程序，或者在系統升級後重驗證應用程序的時候，Android系統首先會檢查應用程序的清單文件中的<uses-sdk>屬性，將其與系統內部API級別對比。系統只有在滿足下列情況時才允許進行應用程序安裝：

• 如果聲明了android:minSdkVersion屬性，其屬性值必須小於或等於該系統的API級別對應的整數值。如果未聲明，系統會默認該應用程序運行需要的最低API級別是1。
• 如果聲明了android:maxSdkVersion屬性，其屬性值必須等於或大於該系統的API級對應的整數值。如果未聲明，系統會默認該應用程序沒有最高API級別限制。請通過閱讀文檔<uses-sdk>以獲得系統如何處理該屬性的更多信息。

應用程序清單文件中聲明該屬性後， <uses-sdk>元素看起來應類似於下面的例子：

 

這樣做的主要原因是，應用程序會通過android:miniSdkVersion聲明的API級別來告知系統——該應用程序使用的API是指定引入的API級別。假如沒有這種屬性聲明，一個應用程序如果因為某些不知名的原因被安裝在低級別API系統之上，那麼該應用程序會在運行時因為嘗試訪問不存在的API而崩潰。為此，Android系統通過不允許應用程序被安裝在不滿足其最低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級別需求的更多信息，請閱讀文檔中關於清單文件的<uses-sdk>章節。

 

 

開發者需要考慮的內容(Development Considerations)

本節屬於應用程序開發者需要了解的內容。

應用程序的向前兼容性(Application forward compatibility)

Android應用程序一般向前兼容於Android平台的新版本。

這是因為幾乎所有的框架API變更都是添加性質的，一個以某種版本的API開發的應用程序是向前兼容與後續Android系統及高版本API。應用程序應當可以運行於高版本的平台，除非使用了未來因某種原因移除的API。

向前兼容性的特性如此重要，是因為很多的Android驅動的設備能夠使用OTA遠程下載技術進行系統更新。用戶開始時能夠很好的安裝和使用你開發的應用程序，後來進行了OTA升級到新版本的Android平台。一旦升級完畢，你的應用程序將運行在一個新的版本環境下，而這個環境應當包含了你的應用程序所需的API和系統功能。

某些情況下，API背後的變化，例如系統底層的變化，可能會影響到你的應用程序運行在新的環境下。為此，作為應用程序開發人員，應當了解應用程序在不同系統環境下將會有如何的外觀和行為。Android SDK包含了多個平台版本，開發人員可以下載下來，用於測試自己的應用程序在不同版本下的運行情況。每個版本的平台都提供了兼容的系統鏡像，你可以將應用程序運行在對應的Android虛擬設備（模擬器）上進行測試。

應用程序的向後兼容性(Application backward compatibility)

Android應用程序不一定向後兼容於那些比這些應用程序開發環境低的平台環境。

Android平台的每個新版本包含了新的框架API，例如新的平台功能，或者替代部分已有的API。應用程序在新平台上可以訪問這些新的API，就像之前提到的，在後續更新的版本中，這些新功能API也是可以繼續使用。相反的，因為早期版本的平台不會包含新的API功能，使用了新API的應用程序在那些舊平台上是無法運行的。

雖然一個Android平台設備不太可能降級到以前的版本，但是需要了解的是：實際生活中可能會有很多設備運行的是較舊的平台版本。即使在設備接收到OTA遠程下載升級，有些人仍然可能會滯後甚至可能不會收到更新。

平台版本和API級別的選擇(Selecting a platform version and API Level)

當你開發應用程序時，你需要選擇一個平台用於編譯該應用程序。通常，你應該在你的應用程序可以支持的最低版本的平台上進行編譯。

你可以通過尋找最低的可以支持你的應用程序編譯的平台方式來決定你將會支持的最低平台版本。一旦你確定了支持的最低版本後，你就可以創建對應版本的AVD模擬器來全面測試你的應用程序。你需要注意的是不要忘記在應用程序清單文件中申明android:minSdkVersion屬性，並賦上正確的API級別標識。

聲明最低API級別(Declaring a minimum API Level)

如果你開發的應用程序使用了最新平台上引入的API或平台特性，你就需要將android:minSdkVersion屬性賦最新平台的API級別標識。這將保證用戶只能在他們的設備與你的應用程序平台版本兼容情況下安裝。反過來說，這樣能夠保證你的應用程序在他們的設備上表現正常。

如果你用了最新的API或平台特性，但是沒有申明android:minSdkVersion屬性，那麼你的應用程序在最新平台上運行是沒有穩定，但是在早期版本的平台上是會出錯的。在後一種情況，應用程序在嘗試訪問舊平台上不存在的API時會崩潰。

針對高版本的API級別測試(Testing against higher API Levels)

編譯完你的應用程序，你應當在支持的最低版本平台上詳細測試應用程序的表現。可以通過創建對應平台的AVD模擬器進行測試。此外，要保證向前兼容性，你應當在你的應用程序可能運行的更高平台版本上進行運行和測試。

Android SDK包含了多個平台版本供開發者使用，其中包括了最新的版本，並且提供了升級工具使得開發者可以獲取其他的版本。

要使用升級工具，可以通過Android命令行方式，該工具位於<sdk>/tools路徑下。你可以用敲入android指令運行該升級工具，而不用指定任何參數。你也可以簡單地通過雙擊Windows下的android.bat或OS X/Linux下的android文件來啟動升級工具。在ADT工具界面，你可以通過菜單的Window > Android SDK and AVD Manager來訪問升級工具。

要想將你的應用程序在不同平台版本的模擬器上運行，需要創建對應的AVD設備。關於AVD的更多信息，請參見Creating and Managing Virtual Devices。如果你用物理設備進行測試，確保清楚運行的具體平台版本。通過本文開始部分的映射表格可以知道平台版本對應的API級別標識。

 

 

使用臨時的API級別(Using a Provisional API Level)

某些情況下，有可能會發布“早期預覽(Early Look)”版的Android 平台SDK。在此平台版本上開發使用的API將不會是最終發布版，平台的API級別標識數字就不會指定。你必須在程序清單文件中使用臨時的API級別進行標識，以便建立對應的平台應用。臨時API級別不是一個整數，而是一個表示未發布的平台版本的字符串代號。“早期預覽”版本的API級別在發布說明中會申明，該代號是大小寫敏感的。

臨時API級別標識的用途是保護開發者和設備使用者免於無意中發布或安裝在“早期預覽”平台版本上開發的應用程序，這些應用程序可能在最終的發布系統上運行不穩定。

臨時API級別標識僅僅在使用“早期預覽”版本的SDK下有效，並且只能運行應用程序於模擬器之中。實際的Android設備上是無法安裝使用臨時API級別標識的應用程序的。在最終版本平台發布後，你必須將程序清單文件中用到的臨時API級別標識替換成最終平台的實際API級別整數值。

 

 

通過API級別進行文檔內容過濾

(Filtering the Reference Documentation by API Level)

Android開發者站點上的參考文檔的每個頁面的右上方提供了“Filter by API Level”控件。你可以用這個控件來僅僅顯示你應用程序相關的那部分API文檔，可以通過應用程序清單文件中的android:minSdkVersion屬性值進行過濾。

要使用過濾功能，可以通過頁面搜索框下面的選擇框來啟用過濾功能。比如設定“Filter by API Level”控件內容與你應用程序申明的相同。注意：在選定級別之後引入的心API會以灰色顯示，並且內容被隱藏，因為你的應用程序是無法訪問這些新功能。

API級別過濾方法不會提供每個API級別中新添加的功能視圖，僅僅展現對應API級別的整個內容，其中去除了後續新版本中的內容。

如果你不想過濾API文檔了，只需要關閉該選擇框的特性。API級別過濾默認是關閉的，因此你可以看到整個框架API的全貌，而不管具體的API級別。

還要注意的是個別的API元素申明了該API參考文檔在哪一級引入的。這通過在每個文檔頁面正文部分的右上角的“Since <api level>”進行聲明該包和類的引入信息。類成員的API級別在其詳細描述文件頭部的右邊進行描述。

 

文章精選

         Android API Level