SDK 扩展

SDK 扩展利用 模块化系统组件 向某些先前发布的 API 级别添加 API 到公共 SDK。当最终用户通过 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 扩展版本 2 开始也可通过 SDK 扩展获得。 SDK 扩展名称 对应于一个整数常量 - 来自 Build.VERSION_CODES 的常量，或在 SdkExtensions 类中定义的常量（例如 SdkExtensions.AD_SERVICES）。

确定要使用哪些 SDK 扩展

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

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

例如，ACTION_PICK_IMAGES 从 Android 13（API 级别 33）开始在公共 SDK 中普遍可用，但在 Android 11（API 级别 30）及更早版本上也可用，只要设备至少具有 R 扩展版本 2 即可。

APIs that are part of SDK Extensions show their extension version in the API reference docs

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

要使用扩展 SDK，请执行以下步骤

  1. 通过检查您要使用的 API 的功能文档和 API 参考，查找您需要的最低扩展版本。
  2. 确定功能集所需的扩展版本后，在 Android Studio 中打开 SDK 管理器。
  3. 选择具有相应扩展版本（或更高版本，因为 API 是累加的）的 Android SDK 平台条目。例如：Android SDK 平台 33，扩展级别 4。

  4. 在您的应用的 build.gradle.kts 或 build.gradle 文件中声明这些值

    Groovy

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

    android {
    compileSdk = 33
    compileSdkExtension = 4
    ...
}

检查 SDK 扩展是否可用

您的应用可以在运行时检查哪些 SDK 扩展版本可用，并且在开发过程中，您可以使用 Android 调试桥 (adb) 命令查找扩展版本，如下节所述。

在运行时检查

您的应用可以在运行时使用 getExtensionVersion() 方法检查给定平台版本是否可用 SDK 扩展。例如，以下代码将检查 Android 11（API 级别 30）SDK 扩展的扩展版本 2 或更高版本是否可用

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 即使扩展 API 可用，也可能在某些设备上返回 false。因此，SDK_INT 检查并非最佳选择，而扩展版本检查是检查 API 可用性的更好方法。所有 SDK_INT 大于或等于 33（Android 13 或更高版本）的设备在公共 SDK 中都具有照片选择器 API，但有些 SDK_INT 小于 33 的设备（例如 Android 11、12 和 12L）如果其 R 扩展版本至少为 2，也可以访问这些 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 扩展 API 的可用性。例如，您可以使用Jetpack 库函数来检查照片选择器的可用性，它可以抽象掉条件版本检查。

工具支持

在 Android Studio Flamingo | 2022.2.1 或更高版本中，lint 工具可以作为其 NewAPI 检查的一部分扫描 SDK 扩展版本的问题。此外，Android Studio 可以自动生成 API 使用 SDK 扩展启动的正确版本检查。

lint 工具会标记未满足调用 API 所需的最低 SDK 扩展版本的情况。

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）。