SDK 扩展

SDK 扩展利用 模块化系统组件 将 API 添加到某些先前发布的 API 级别上的公共 SDK。这些 API 在最终用户通过 Google Play 系统更新 接收模块更新时交付给设备。应用程序开发者可以在其应用程序中使用这些 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 参考页面指定了您的应用程序可以使用以访问 API 的最早 SDK 扩展版本。如果文档还指定了 Android 平台版本（通过 API 级别引用），则该 API 也适用于运行该版本或更高版本的 Android 的所有设备。

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

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 Debug Bridge (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 检查仍然安全有效，但即使扩展 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 扩展名称和常量。

广告服务扩展

与一般 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 库函数检查 PhotoPicker 的可用性，它可以抽象出条件版本检查。

工具支持

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

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 检查

要检查设备上可用的 SDK 扩展，请使用 adb 运行以下命令

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