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 Version 2 开始，也可通过 SDK 扩展使用。 SDK 扩展名称对应于一个整数常量，可以是 Build.VERSION_CODES 中的常量，也可以是 SdkExtensions 类中定义的常量（例如 SdkExtensions.AD_SERVICES）。

确定要使用的 SDK 扩展

在使用 SDK 扩展 API 之前，您首先需要确定哪些 SDK 包含支持您的应用用例的 API。

SDK 扩展 API 的 API 参考页面指定了您的应用可以用来访问 API 的最低 SDK 扩展版本。如果文档还指定了 Android 平台版本（由 API 级别引用），则该 API 也适用于运行该版本或更高版本 Android 的所有设备。

例如，ACTION_PICK_IMAGES 通常从 Android 13（API 级别 33）开始在公共 SDK 中可用，但也适用于低至 Android 11（API 级别 30）的设备，前提是设备至少具有 R Extensions Version 2

要使用此 API，您需要针对至少 API 级别 33 或扩展级别至少 2 的 SDK 进行编译。

使用扩展 SDK 的步骤

1. 通过查看您想使用的 API 的功能文档和 API 参考来查找您需要的最低扩展版本。
2. 确定您的功能集所需的扩展版本后，在 Android Studio 中打开 SDK 管理器。
3. 选择具有相应扩展版本（或更高版本，因为 API 是累加的）的 Android SDK Platform 条目。例如：Android SDK Platform 33，Extension Level 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 扩展。例如，以下代码会检查 Android 11（API 级别 30）SDK 扩展的版本是否为 2 或更高版本

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 检查仍然安全有效，但在某些设备上，即使扩展 API 可用，isPhotoPickerAvailable 也会返回 false。因此，SDK_INT 检查不是最佳方法，扩展版本检查是检查 API 可用性的更好方法。所有 SDK_INT 大于或等于 33（Android 13 或更高版本）的设备都在公共 SDK 中包含照片选择器 API，但有些设备 SDK_INT 小于 33（例如 Android 11、12 和 12L），如果其 R 扩展版本至少为 2，则也可以访问这些 API。

在这种情况下，使用扩展版本检查可以帮助您的应用为更多用户提供额外功能。有关可用于在设备上检查某些 SDK 扩展的所有常量列表，请参阅SDK 扩展名称和常量。

Ad Services 扩展

与一般的 SDK 扩展类似，AdServices API 参考有时会表明某个 API 是“Ad Services 扩展”版本的一部分。与一般的 SDK 扩展不同，Ad Services 扩展使用 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;
}

要详细了解 Ad Services 扩展中的功能以及如何开始使用，请参阅Ad Services 扩展文档。

实用方法

在某些情况下，SDK 扩展提供了 Jetpack 实用方法，用于检查其 SDK 扩展 API 的可用性。例如，您可以使用Jetpack 库函数来检查 PhotoPicker 是否可用，这抽象了条件版本检查。

工具支持

在 Android Studio Flamingo | 2022.2.1 或更高版本中，lint 工具可以作为其 NewAPI 检查的一部分扫描 SDK 扩展版本的问题。此外，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）。