本頁面由 Cloud Translation API 翻譯而成。

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，請按照下列步驟操作：

根據要使用的 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) 以上版本
U 擴充功能	`VERSION_CODES.UPSIDE_DOWN_CAKE`	Android 14 (API 級別 34) 以上版本
V 擴充功能	`VERSION_CODES.VANILLA_ICE_CREAM`	Android 15 (API 級別 35) 以上版本
廣告服務擴充功能	`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)。