SDK 擴充功能可利用模組系統元件將 API 加到公用 SDK 中,以便用於部分先前發布的 API 級別。當使用者透過 Google Play 系統更新接收模組更新時,系統就會將這些 API 提供給裝置。應用程式開發人員可在自家應用程式中使用這些 API,為這類先前的 Android 版本提供 SDK 最初所沒有的額外功能。
API 版本管理
從 Android 11 (API 級別 30) 開始,Android 裝置便含有一組 SDK 擴充功能。新增 API 時,這些擴充功能會包含在 API 級別中,但也可能包含在特定版本的 SDK 擴充功能中。舉例來說,用於相片挑選工具的 ACTION_PICK_IMAGES
API 已新增至 Android 13 (API 級別 33) 的公用 SDK 內,但也可以透過 R Extensions 2 以上版本的 SDK 擴充功能取得。SDK 擴充功能名稱會對應一組整數常數,可以是 Build.VERSION_CODES
的常數,或 SdkExtensions
類別中定義的常數 (例如 SdkExtensions.AD_SERVICES
)。
決定要使用的 SDK 擴充功能
您必須先判斷哪些 SDK 包含可滿足應用程式用途的 API,才能使用 SDK Extension API。
SDK Extension API 的 API 參考資料頁面會指明應用程式存取 API 時可使用的最初 SDK 擴充功能版本。如果說明文件同時指出 Android 平台版本 (按 API 級別參照),那麼凡是搭載該 Android (或以上) 版本的裝置,也都能使用此 API。
舉例來說,ACTION_PICK_IMAGES
通常可在 Android 13 (API 級別 33) 以上版本的公用 SDK 中使用,但只要裝置版本至少為 R Extensions 2,那麼該 API 也能在搭載 Android 11 (API 級別 30) 的裝置上使用:
如要使用這個 API,您必須針對 API 級別至少 33 或擴充功能層級至少 2 的 SDK 進行編譯。
如要使用擴充功能 SDK,請按照下列步驟操作:
- 根據要使用的 API 查看相應的功能說明文件和 API 參考資料,找出所需的最低擴充功能版本。
- 決定功能集所需的擴充功能版本後,在 Android Studio 中開啟 SDK Manager。
- 選取符合對應擴充功能版本的 Android SDK Platform 項目,或更高版本的項目 (因為 API 是累加的)。例如:Android SDK Platform 33,擴充功能層級 4。
在應用程式的
build.gradle.kts
或build.gradle
檔案中宣告這些值:Groovy
android { compileSdk 33 compileSdkExtension 4 ... }
Kotlin
android { compileSdk = 33 compileSdkExtension = 4 ... }
檢查 SDK 擴充功能是否可用
您的應用程式可在執行階段檢查哪些 SDK 擴充功能版本可供使用,而在開發期間,您可以利用 Android Debug Bridge (ADB) 指令查詢擴充功能版本,如以下各節所述。
在執行階段檢查
您的應用程式可在執行階段運用 getExtensionVersion()
方法,檢查 SDK 擴充功能是否可用於特定平台版本。舉例來說,以下程式碼將檢查擴充功能 2 以上版本是否可在 Android 11 (API 級別 30) 的 SDK 擴充功能中使用:
Kotlin
fun isPhotoPickerAvailable(): Boolean { return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2 // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker. }
Java
public static final boolean isPhotoPickerAvailable() { return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2; }
這類似於根據 Build.VERSION.SDK_INT
執行檢查:
Kotlin
fun isPhotoPickerAvailable(): Boolean { return Build.VERSION.SDK_INT >= 33 }
Java
public static final boolean isPhotoPickerAvailable() { return Build.VERSION.SDK_INT >= 33; }
這項 SDK_INT
檢查仍然安全有效,但 isPhotoPickerAvailable
會在某些裝置上傳回 false,即使擴充功能 API 可用也是一樣。因此,SDK_INT
檢查並非最理想的做法,擴充功能版本檢查反倒更適合用來檢查 API 可用性。凡是 SDK_INT
為 33
以上 (Android 13 或以上版本) 的裝置,在公用 SDK 中都有 Photo Picker API,但如果是 SDK_INT
低於 33 (例如 Android 11、12 和 12L) 的裝置,只要其搭載 2
以上版本的 R 擴充功能,就也能存取上述 API。
在這種情況下,不妨採用擴充功能版本檢查,有助於應用程式為更多使用者提供額外功能。您可利用常數來檢查裝置上的特定 SDK 擴充功能,如需完整常數清單,請參閱「SDK 擴充功能名稱和常數」。
廣告服務擴充功能
與一般的 SDK 擴充功能組合類似,AdServices
API 參考資料有時會註明 API 屬於「廣告服務擴充功能」版本的一部分。但與一般 SDK 擴充功能不同,廣告服務擴充功能會利用 SdkExtensions.AD_SERVICES
常數確認裝置搭載的是哪一個版本:
Kotlin
fun isAdServicesAvailable(): Boolean { return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4 }
Java
public static final boolean isAdServicesAvailable() { return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4; }
如要進一步瞭解廣告服務擴充功能的特色,以及如何開始使用,請參閱廣告服務擴充功能說明文件。
公用程式方法
在某些情況下,您可以透過 SDK 擴充功能中的 Jetpack 公用程式方法,檢查 SDK Extension API 是否可用。舉例來說,您可以使用 Jetpack 程式庫函式檢查 PhotoPicker 的可用性,從而省去有條件的版本檢查。
工具支援
在 Android Studio Flamingo | 2022.2.1 以上版本中,Lint 工具可用於掃描 SDK 擴充功能版本的問題,將此措施做為 NewAPI 檢查的一環。此外,Android Studio 也可以為透過 SDK 擴充功能啟動的 API 自動產生正確的版本檢查操作。
SDK 擴充功能名稱和常數
下表標明 API 參考說明文件中列出的不同 SDK 擴充功能組合,以及應用程式在執行階段檢查 API 可用性時所用的常數,方便您瞭解兩者間的對應關係。每個公用 SDK 的一般 SDK 擴充功能組合都會對應至 Build.VERSION_CODES
的值。
SDK 擴充功能名稱 | 常數 | 適用的裝置 |
---|---|---|
R 擴充功能 | VERSION_CODES.R |
Android 11 (API 級別 30) 以上版本 |
S 擴充功能 | VERSION_CODES.S |
Android 12 (API 級別 31) 以上版本 |
T 擴充功能 | VERSION_CODES.TIRAMISU |
Android 13 (API 級別 33) 以上版本 |
廣告服務擴充功能 | SdkExtensions.AD_SERVICES |
Android 13 (API 級別 33) 以上版本 |
使用 ADB 檢查
如要使用 ADB 檢查裝置有哪些 SDK 擴充功能可用,請執行下列指令:
adb shell getprop | grep build.version.extensions
執行指令之後,您會看見類似下方的輸出內容:
[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher
每一行都會顯示裝置上的 SDK 擴充功能,以及對應的擴充功能版本 (在本例中為 3)。