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

如要使用這個 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.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 擴充功能中使用：

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.
}

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

這類似於根據 Build.VERSION.SDK_INT 執行檢查：

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

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 常數確認裝置搭載的是哪一個版本：

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

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 的值。

使用 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)。