Ta strona została przetłumaczona przez Cloud Translation API.

Rozszerzenia SDK

Rozszerzenia pakietów SDK wykorzystują modułowe komponenty systemowe do dodawania interfejsów API do publicznego pakietu SDK na określonych wcześniej poziomach. Te interfejsy API są dostarczane do urządzeń, gdy użytkownicy otrzymują aktualizacje modułów w ramach aktualizacji systemu Google Play. Deweloperzy aplikacji mogą używać tych interfejsów API w swoich aplikacjach, aby udostępniać dodatkowe funkcje, które nie były pierwotnie dostępne w pakiecie SDK w poprzednich wersjach Androida.

Obsługa wersji interfejsu API

Począwszy od Androida 11 (poziom interfejsu API 30), urządzenia z Androidem zawierają zestaw rozszerzeń SDK. Dodane nowe interfejsy API są uwzględniane na poziomie interfejsu API, ale mogą być też uwzględnione w rozszerzeniu pakietu SDK w konkretnej wersji. Na przykład interfejs ACTION_PICK_IMAGES API dla selektora zdjęć został dodany do publicznego pakietu SDK w Androidzie 13 (poziom API 33), ale od wersji 2 rozszerzeń R jest też dostępny za pomocą rozszerzeń SDK. Nazwy rozszerzeń SDK odpowiadają stałej liczbie całkowitej – stałej z Build.VERSION_CODES lub określonej w klasie SdkExtensions (np. SdkExtensions.AD_SERVICES).

Określanie, których rozszerzeń SDK używać

Zanim użyjesz interfejsów API rozszerzeń pakietów SDK, musisz najpierw określić, które pakiety SDK zawierają interfejsy API obsługujące Twoją aplikację.

Na stronach z dokumentacją API dla interfejsów API rozszerzeń pakietu SDK określono najwcześniejszą wersję rozszerzenia pakietu SDK, za pomocą której aplikacja może uzyskiwać dostęp do interfejsu API. Jeśli w dokumentacji podana jest również wersja platformy Androida (do której odwołuje się poziom interfejsu API), oznacza to, że ten interfejs API jest też dostępny na wszystkich urządzeniach z tą wersją Androida lub nowszą.

Na przykład ACTION_PICK_IMAGES jest ogólnie dostępny w publicznym pakiecie SDK zaczynającym się od Androida 13 (poziom interfejsu API 33), ale można z niego też korzystać na urządzeniach starszych niż Android 11 (poziom interfejsu API 30), o ile urządzenie ma co najmniej rozszerzenia R w wersji 2:

Interfejsy API, które wchodzą w skład rozszerzeń SDK, pokazują wersję rozszerzenia w dokumentacji interfejsów API

Aby korzystać z tego interfejsu API, musisz skompilować go do pakietu SDK, który ma co najmniej poziom 33 interfejsu API lub co najmniej 2.

Aby skorzystać z pakietu SDK rozszerzeń:

Sprawdź minimalną wersję rozszerzeń, której potrzebujesz, sprawdzając dokumentację funkcji i dokumentację API interfejsów API, których chcesz użyć.
Gdy określisz wymaganą wersję rozszerzenia dla zbioru funkcji, otwórz SDK Manager w Android Studio.
Wybierz pozycję Android SDK Platform z odpowiednią wersją rozszerzenia (lub wyższą, ponieważ interfejsy API się sumują). np.: Android SDK Platform 33, rozszerzenie poziomu 4.

Zadeklaruj te wartości w pliku build.gradle.kts lub build.gradle aplikacji:

Odlotowy

android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

Kotlin

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

Sprawdzanie, czy są dostępne rozszerzenia pakietu SDK

Aplikacja może sprawdzać, jakie wersje rozszerzeń SDK są dostępne w czasie działania, a w trakcie jej tworzenia możesz sprawdzać ich wersje za pomocą poleceń Android Debug Bridge (adb) zgodnie z opisem w kolejnych sekcjach.

Sprawdź w czasie działania

Aplikacja może za pomocą metody getExtensionVersion() sprawdzić w czasie działania, czy rozszerzenia pakietu SDK są dostępne w przypadku danej wersji platformy. Na przykład ten kod sprawdzi, czy jest dostępne rozszerzenie w wersji 2 lub nowszej w przypadku rozszerzenia pakietu SDK na Androida 11 (poziom interfejsu API 30) i jego dostępności:

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

Przypomina to sprawdzanie na podstawie 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;
}

Ten test SDK_INT jest nadal bezpieczny i prawidłowy, ale isPhotoPickerAvailable zwróci na niektórych urządzeniach wartość „false”, mimo że interfejs API rozszerzenia jest dostępny. W efekcie sprawdzanie SDK_INT nie jest optymalne, a sprawdzanie wersji rozszerzenia stanowi lepszy sposób sprawdzania dostępności interfejsu API. Wszystkie urządzenia z SDK_INT w wersji 33 lub wyższej (Android 13 lub nowszy) mają interfejsy API selektora zdjęć w publicznym pakiecie SDK, ale istnieją urządzenia z SDK_INT w wersji starszej niż 33 (np. Android 11, 12 i 12L), które również mają dostęp do interfejsów API w wersji R co najmniej 2.

W takim przypadku sprawdzenie wersji rozszerzenia może pomóc w udostępnieniu dodatkowych funkcji większej liczbie użytkowników. Listę wszystkich stałych, których możesz używać do sprawdzania określonych rozszerzeń SDK na urządzeniu, znajdziesz w sekcji Nazwy i stałe rozszerzenia pakietu SDK.

Rozszerzenia usług reklamowych

Podobnie jak w przypadku ogólnego zestawu rozszerzeń SDK, informacje o interfejsie API AdServices czasami wskazują, że interfejs API jest częścią wersji „Rozszerzenia usług reklamowych”. W przeciwieństwie do ogólnych rozszerzeń w pakiecie SDK rozszerzenia usług reklamowych używają stałej SdkExtensions.AD_SERVICES do określenia, która wersja znajduje się na urządzeniu:

Kotlin

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

Java

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

Więcej informacji o funkcjach rozszerzeń usług reklamowych i o tym, jak zacząć z nich korzystać, znajdziesz w dokumentacji rozszerzeń usług reklamowych.

Metody użyteczności

W niektórych przypadkach rozszerzenia pakietów SDK mają narzędzia Jetpack służące do sprawdzania dostępności interfejsów API rozszerzeń pakietu SDK. Możesz na przykład użyć funkcji biblioteki Jetpack, aby sprawdzić dostępność PhotoPicker, co pozwoli uniknąć sprawdzania wersji warunkowej.

Pomoc dotycząca narzędzi

W Android Studio Flamingo | 2022.2.1 lub nowszym narzędzie Lint może w ramach kontroli NewAPI skanować pod kątem problemów z wersjami rozszerzenia pakietu SDK. Dodatkowo Android Studio może automatycznie generować poprawne testy wersji interfejsów API uruchamianych za pomocą rozszerzeń w pakiecie SDK.

Narzędzie do lintowania flagami, w przypadku których nie została osiągnięta minimalna wersja rozszerzeń SDK wymagana do wywołania interfejsu API.

Nazwy i stałe rozszerzenia pakietu SDK

W tabeli poniżej opisujemy, jak różne zestawy rozszerzeń SDK wymienione w dokumentacji referencyjnej interfejsu API są mapowane na stałe, których aplikacja może używać do sprawdzania dostępności interfejsu API w czasie działania. Ogólny zestaw rozszerzeń SDK dla każdego publicznego pakietu SDK jest mapowany na wartości Build.VERSION_CODES.

Nazwa rozszerzenia pakietu SDK	Stała	Kwalifikujące się urządzenia
Rozszerzenia R	`VERSION_CODES.R`	Android 11 (poziom API 30) i nowsze
Rozszerzenia S	`VERSION_CODES.S`	Android 12 (poziom API 31) i nowsze
Rozszerzenia T	`VERSION_CODES.TIRAMISU`	Android 13 (poziom interfejsu API 33) i nowszy
Rozszerzenia usług reklamowych	`SdkExtensions.AD_SERVICES`	Android 13 (poziom interfejsu API 33) i nowszy

Sprawdź za pomocą narzędzia adb

Aby sprawdzić, które rozszerzenia pakietu SDK są dostępne na urządzeniu za pomocą adb, uruchom to polecenie:

adb shell getprop | grep build.version.extensions

Po uruchomieniu polecenia wyświetlą się dane wyjściowe podobne do tych:

[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

Każdy wiersz zawiera rozszerzenie SDK obecne na urządzeniu wraz z odpowiadającą im wersją rozszerzenia (w tym przypadku 3).