SDK 擴充功能

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) 的裝置上使用:

SDK 擴充功能中的 API 在 API 參考資料文件顯示其擴充功能版本

如要使用這個 API,您必須針對 API 級別至少 33 或擴充功能層級至少 2 的 SDK 進行編譯。

如要使用擴充功能 SDK,請按照下列步驟操作:

  1. 根據要使用的 API 查看相應的功能說明文件和 API 參考資料,找出所需的最低擴充功能版本。
  2. 決定功能集所需的擴充功能版本後,在 Android Studio 中開啟 SDK Manager。
  3. 選取符合對應擴充功能版本的 Android SDK Platform 項目,或更高版本的項目 (因為 API 是累加的)。例如:Android SDK Platform 33,擴充功能層級 4。
  4. 在應用程式的 build.gradle.ktsbuild.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_INT33 以上 (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 自動產生正確的版本檢查操作。

Lint 工具會標記哪個例項不符合呼叫 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)。