Informacje o wersji wtyczki Androida do obsługi Gradle w wersji zapoznawczej

Ta strona zawiera informacje o wersjach próbnych wtyczki Androida do Gradle (AGP).

Wtyczka Androida do obsługi Gradle w wersji 9.0

Wtyczka Androida do obsługi Gradle w wersji 9.0 to nowa wersja główna AGP, która wprowadza zmiany w interfejsie API i zachowaniu.

Aby zaktualizować wtyczkę Androida do obsługi Gradle do wersji 9.0.0-alpha05, użyj Asystenta uaktualniania wtyczki Androida do obsługi Gradle w Android Studio Narwhal 4 Feature Drop | 2025.1.4.

Asystent uaktualniania AGP pomaga zachować dotychczasowe zachowania podczas uaktualniania projektu, gdy jest to odpowiednie. Umożliwia to uaktualnienie projektu do AGP 9.0, nawet jeśli nie chcesz jeszcze stosować wszystkich nowych ustawień domyślnych w AGP 9.0.

Zgodność

Maksymalny poziom interfejsu Android API obsługiwany przez wtyczkę Androida do obsługi Gradle w wersji 9.0.0-alpha05 to poziom 36.

Wtyczka Androida do obsługi Gradle w wersji 9.0.0-alpha05 wymaga Gradle w wersji 9.0.0.

Klasy android DSL implementują teraz tylko nowe interfejsy publiczne.

W ciągu ostatnich kilku lat wprowadziliśmy nowe interfejsy dla naszego języka DSL i interfejsu API, aby lepiej kontrolować, które interfejsy API są publiczne. Wersje AGP 7.x i 8.x nadal używały starych typów DSL (np. BaseExtension), które również implementowały nowe interfejsy publiczne, aby zachować zgodność w trakcie prac nad interfejsami.

AGP 9.0 korzysta wyłącznie z naszych nowych interfejsów DSL, a implementacje zostały zmienione na nowe typy, które są w pełni ukryte. Ta zmiana usuwa też dostęp do starego, wycofanego interfejsu API wariantów.

Aby zaktualizować AGP do wersji 9.0, może być konieczne wykonanie tych czynności:

• Przełącz na wbudowany język Kotlin: wtyczka org.jetbrains.kotlin.android nie jest zgodna z nowym DSL.

• Przełącz projekty KMP na wtyczkę Android Gradle Library Plugin for KMP: używanie wtyczki org.jetbrains.kotlin.multiplatform w tym samym podprojekcie Gradle co wtyczki com.android.library i com.android.application jest niezgodne z nowym DSL.

• Zaktualizuj pliki kompilacji: zmiana interfejsów ma na celu zachowanie jak największego podobieństwa do DSL, ale mogą wystąpić niewielkie zmiany.

• Zaktualizuj niestandardową logikę kompilacji, aby odwoływała się do nowego języka DSL i interfejsu API: zastąp wszystkie odwołania do wewnętrznego języka DSL interfejsami publicznego języka DSL. W większości przypadków będzie to zamiana 1:1. Zastąp wszystkie użycia interfejsu applicationVariants i podobnych interfejsów API nowym androidComponents. Może to być bardziej skomplikowane, ponieważ interfejs androidComponents API został zaprojektowany tak, aby był bardziej stabilny i zapewniał dłuższą zgodność wtyczek. Przykłady znajdziesz w przepisach Gradle.

• Zaktualizuj wtyczki innych firm: niektóre wtyczki innych firm mogą nadal korzystać z interfejsów lub interfejsów API, które nie są już udostępniane. Przejdź na wersje tych wtyczek, które są zgodne z AGP 9.0.

Jeśli po zaktualizowaniu do AGP 9.0 zobaczysz ten komunikat o błędzie, oznacza to, że Twój projekt nadal odwołuje się do niektórych starych typów:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

Jeśli blokują Cię niekompatybilne wtyczki innych firm, możesz zrezygnować z nich i przywrócić stare implementacje DSL oraz stary interfejs API wariantów. W tym czasie dostępne są też nowe interfejsy, a Ty nadal możesz zaktualizować własną logikę kompilacji do nowego interfejsu API. Aby zrezygnować, umieść ten wiersz w pliku gradle.properties:

android.newDsl=false

Możesz też rozpocząć uaktualnianie do nowych interfejsów API przed uaktualnieniem do AGP 9.0. Nowe interfejsy są dostępne w wielu wersjach AGP, więc możesz mieć połączenie nowych i starych. W dokumentacji referencyjnej interfejsu AGP API znajdziesz informacje o interfejsie API dla każdej wersji AGP oraz daty dodania poszczególnych klas, metod i pól.

W fazie alfa wersji 9.0 będziemy kontaktować się z autorami wtyczek, aby pomóc im dostosować i opublikować wtyczki w pełni zgodne z nowymi trybami. Ulepszymy też Asystenta uaktualniania AGP w Android Studio, aby przeprowadzić Cię przez proces migracji.

Jeśli zauważysz, że w nowym interfejsie DSL lub Variant API brakuje funkcji, jak najszybciej zgłoś problem.

Wbudowany Kotlin

Wtyczka Androida do obsługi Gradle w wersji 9.0 ma wbudowaną obsługę kompilacji w języku Kotlin, która zastępuje oddzielnie stosowaną wtyczkę Kotlin. Upraszcza to integrację z AGP, pozwala uniknąć korzystania z wycofanych interfejsów API i w niektórych przypadkach zwiększa wydajność.

Wtyczka Androida do obsługi Gradle w wersji 9.0 ma zależność środowiska wykonawczego od wtyczki Kotlin Gradle w wersji 2.2.10, która jest minimalną wersją wymaganą do obsługi wbudowanego języka Kotlin.

Możesz zrezygnować z wbudowanego języka Kotlin, ustawiając android.builtInKotlin=false.

Jeśli zrezygnowano z wbudowanego języka Kotlin i trzeba używać starszej wersji wtyczki Kotlin Gradle, można wymusić przejście na starszą wersję:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

Zmiany w działaniu

Wtyczka Androida do obsługi Gradle w wersji 9.0 ma te nowe funkcje:

AGP 9.0 zawiera aktualizacje domyślnych wartości tych właściwości Gradle. Dzięki temu podczas uaktualniania możesz zachować działanie AGP 8.13:

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Usunięte funkcje

Wtyczka Androida do obsługi Gradle w wersji 9.0 usuwa te funkcje:

• Obsługa umieszczonych aplikacji na Wear OS
  AGP 9.0 usuwa obsługę umieszczania aplikacji na Wear OS, która nie jest już obsługiwana w Google Play. Obejmuje to usunięcie konfiguracji wearApp i AndroidSourceSet.wearAppConfigurationName DSL. Więcej informacji o publikowaniu aplikacji na Wear OS znajdziesz w artykule Dystrybucja aplikacji na Wear OS.
• androidDependencies i sourceSets zgłosić zadanie

Zmieniony DSL

Wtyczka Androida do obsługi Gradle w wersji 9.0 zawiera te zmiany powodujące niezgodność w języku DSL:

• Parametryzacja funkcji CommonExtension została usunięta.

  Sama w sobie jest to tylko zmiana powodująca niezgodność na poziomie źródła, która ma pomóc uniknąć takich zmian w przyszłości. Oznacza to jednak również, że metody blokowania muszą zostać przeniesione z CommonExtension do ApplicationExtension, LibraryExension, DynamicFeatureExtension i TestExtension.

  Podczas uaktualniania projektu do AGP 9.0 zmień kod wtyczki Gradle, który korzysta z tych parametrów lub metod blokowych. Na przykład ten wtyczka została zaktualizowana, aby usunąć parametr typu i nie korzystać z usuniętych metod blokowania:

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  W przypadku wtyczek, które są przeznaczone dla zakresu wersji AGP, bezpośrednie użycie funkcji pobierającej jest binarne zgodne z wersjami AGP starszymi niż 9.0.

Usunięto DSL

Wtyczka Androida do obsługi Gradle w wersji 9.0 usuwa:

• AndroidComponentsExtension.finalizeDSl. Zastępuje ją finalizeDsl

• AndroidSourceSet.jni, ponieważ nie działał.

• AndroidSourceSet.wearAppConfigurationName, ponieważ dotyczy to usuniętej obsługi wbudowanej aplikacji na Wear OS.

• BuildType.isRenderscriptDebuggable, ponieważ nie działał.

• Component.transformClassesWith. Zastępuje ją Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. Zastępuje ją Instrumentation.setAsmFramesComputationMode

• DependenciesInfoBuilder.includedInApk. Zastąpienie:includeInApk

• DependenciesInfoBuilder.includedInBundle. Zastąpienie:includeInBundle

• ComponentBuilder.enabled. Zastępuje ją ComponentBuilder.enable.

• DependencyVariantSelection. Zastępuje ją DependencySelection, która jest udostępniana jako kotlin.android.

• GeneratesApk.targetSdkVersion. Zastąpiono ją wartością targetSdk

• Installation.installOptions(String). Zastępuje ją modyfikowalna właściwość Installation.installOptions.

• Variant.minSdkVersion. Zastąpiono ją wartością minSdk

• Variant.maxSdkVersion. Zastąpiono ją wartością maxSdk

• Variant.targetSdkVersion. Zastąpiono ją wartością targetSdk

• VariantBuilder.targetSdk i targetSdkPreview, ponieważ nie miały one znaczenia w bibliotekach. Zamiast tego użyj GeneratesApkBuilder.targetSdk lub GeneratesApkBuilder.targetSdkPreview.

• VariantOutput.enable. Zastąpiono ją wartością enabled

• Blok PostProcessing, który jest eksperymentalny i nigdy nie został ustabilizowany.

• ProductFlavor.setDimension, która jest zastępowana przez właściwość dimension

• LanguageSplitOptions, która była przydatna tylko w przypadku aplikacji błyskawicznych w Google Play, które zostały wycofane.

• Variant.unitTest, ponieważ nie dotyczyło to wtyczki com.android.test. unitTest jest dostępna w przypadku podtypów VariantBuilder rozszerzających HasUnitTest.

• VariantBuilder.enableUnitTest, ponieważ nie dotyczyło to wtyczki com.android.test. enableUnitTest jest dostępna w przypadku podtypów VariantBuilder rozszerzających HasUnitTestBuilder.

• Typ VariantBuilder.unitTestEnabled został usunięty na rzecz bardziej spójnie nazwanego typu enableUnitTest w przypadku podtypów VariantBuilder rozszerzających typ HasUnitTestBuilder.

Usunięte właściwości Gradle

Poniższe właściwości Gradle zostały początkowo dodane jako sposoby globalnego wyłączania funkcji, które były domyślnie włączone.

Te funkcje są domyślnie wyłączone od wersji AGP 8.0 lub starszej. Włącz te funkcje tylko w podprojektach, które z nich korzystają, aby usprawnić kompilację.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Usunięte interfejsy API

Wtyczka Androida do obsługi Gradle w wersji 9.0 usuwa:

• Wycofane i wyłączone interfejsy APIBaseExtension.registerTransform, które były dostępne tylko po to, aby umożliwić kompilowanie pod kątem najnowszej wersji AGP przy jednoczesnym kierowaniu na AGP 4.2 lub starszą.

• Wycofane i wyłączone funkcje FeaturePlugin i FeatureExtension.

Wymuszane właściwości Gradle

AGP 9.0 zgłasza błąd, jeśli ustawisz te właściwości Gradle.

Asystent uaktualniania wtyczki Androida do obsługi Gradle nie uaktualni projektów do AGP 9.0, które korzystają z tych właściwości.