Dodaj zależności kompilacji

System kompilacji Gradle w Android Studio pozwala plików binarnych lub innych modułów biblioteki do kompilacji jako zależności. mogą znajdować się na maszynie lub w zdalnym repozytorium, deklarowane przez nich zależności pośrednie też są uwzględniane automatycznie. Na tej stronie dowiesz się, jak korzystać z zależności w projekcie Androida, w tym: szczegółowe informacje o zachowaniach i konfiguracjach, które są charakterystyczne dla wtyczki Androida do obsługi Gradle (AGP). Dokładny przewodnik po Gradle musisz też zobaczyć Przewodnik Gradle dotyczący zarządzania zależnościami – ale pamiętaj, że w projekcie na Androida musisz używać tylko konfiguracje zależności zdefiniowane na tej stronie.

Uwaga: podczas określania zależności nie używaj wersji dynamicznej. liczb, takich jak 'com.android.tools.build:gradle:3.+'. Korzystanie z tej funkcji może mogą powodować nieoczekiwane aktualizacje wersji, problemy z rozwiązywaniem różnic w wersjach. niską skuteczność.

Dodaj zależność biblioteki lub wtyczki

Najlepszym sposobem dodawania zależności kompilacji i zarządzania nimi jest korzystanie z katalogów wersji, metody domyślnie używanej w nowych projektach. W tej sekcji omawiamy najczęstsze typy konfiguracji używane w projektach na Androida; zapoznaj się z Dokumentacja Gradle , aby wyświetlić więcej opcji. Przykład aplikacji, która korzysta z katalogów wersji, znajdziesz tutaj Teraz na Androidzie. Jeśli masz już skonfigurowane zależności kompilacji bez katalogów wersji i mają projekt wielomodułowy, Migracja.

Wskazówki dotyczące dodawania zależności natywnych i zarządzania nimi (nietypowe) znajdziesz w artykule Zależności natywne.

W poniższym przykładzie dodamy zdalny plik binarny zależność (Jetpack Macrobenchmark biblioteka), moduł biblioteki lokalnej zależność (myLibrary) i wtyczka (wtyczka Androida do obsługi Gradle) do naszego projektu. Oto ogólne aby dodać te zależności do projektu:

Uwaga: w ustawieniach możesz zadeklarować katalogi wersji , ale zalecamy użycie osobnego pliku toml, aby uzyskać dodatkową pomoc dotyczącą kodu o sugestiach i wyróżnieniu dostępnych w Android Studio.

1. Dodaj alias wersji zależności, którą chcesz umieścić w Sekcja [versions] pliku katalogu wersji o nazwie libs.versions.toml (w katalogu gradle w Widok projektu lub Skrypty Gradle w widoku Android):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Aliasy mogą zawierać myślniki i podkreślenia. Te aliasy generują zagnieżdżone wartości które znajdziesz w skryptach kompilacji. Odwołania zaczynają się od nazwy katalog, część libs elementu libs.versions.toml. Kiedy w jednym katalogu wersji, zalecamy zachowanie domyślnej wartości „libs”.

2. Dodaj alias zależności w funkcji [libraries] (dla zdalnych plików binarnych lub modułów biblioteki lokalnej) lub [plugins] (dla wtyczek) w pliku libs.versions.toml.

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Niektóre biblioteki są dostępne w opublikowanym liście materiałów (BOM), grup rodzinnych bibliotek i ich wersji. Możesz umieścić BOM w katalogu wersji i plików kompilacji, a system będzie nimi zarządzać za Ciebie. Zobacz Więcej informacji znajdziesz na liście materiałów.

3. Dodaj odwołanie do aliasu zależności do skryptu kompilacji moduły, które wymagają tej zależności. Przekonwertuj alias” podkreślenia i myślniki na kropki, gdy odwołujesz się do niego w skrypcie kompilacji. Skrypt kompilacji na poziomie modułu będzie wyglądać tak:

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }
   

   Odlotowe

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }
   

   Odwołania do wtyczek zawierają plugins po nazwie katalogu i odwołania do wersji zawierają versions po nazwie katalogu (wersja referencje są rzadkie, zobacz Zależności z takimi samymi numerami wersji). Biblioteka odwołania nie zawierają kwalifikatora libraries, więc nie można użyć funkcji versions lub plugins na początku biblioteki alias.

Skonfiguruj zależności

W bloku dependencies możesz zadeklarować zależność biblioteki, używając jednego z tych elementów: kilku różnych konfiguracji zależności (takich jak implementation wcześniej). Każda konfiguracja zależności zapewnia Gradle inny jak korzystać z zależności. Tabela poniżej zawiera konfiguracji, których możesz użyć w zależności w projekcie Androida.

Konfiguracja	Działanie
implementation	Gradle dodaje zależność do ścieżki klasy kompilacji i pakuje zależność do danych wyjściowych kompilacji. Gdy konfiguruje zależność implementation, jest to w celu poinformowania Gradle, że nie chcesz, aby moduł wyciekł zależności od innych modułów. Oznacza to, że zależność nie jest dostępna dla innych modułów zależnych od . Używam tej konfiguracji zależności zamiast api może znacząco skrócić czas kompilacji ponieważ zmniejsza liczbę modułów potrzebnych systemowi kompilacji do rekompilacji. Jeśli na przykład implementation zmienia swój interfejs API, Gradle ponownie kompiluje tylko tę zależność oraz zależne od niej moduły. Większość aplikacji i testów moduły powinny używać tej konfiguracji.
api	Gradle dodaje zależność do ścieżki kompilacji i kompilacji dane wyjściowe. Jeśli moduł zawiera zależność api, powiadamianie Gradle, że moduł chce eksportować dane który jest uzależniony od innych modułów, dzięki czemu jest dla nich dostępny w czasie działania i kompilacji. Używaj tej konfiguracji ostrożnie i tylko z zależnościami, które i dotychczasowego eksportowania do innych konsumentów. Jeśli Zależność api zmienia swój zewnętrzny interfejs API – Gradle ponownie kompiluje wszystkie moduły, które mają dostęp do tej zależności, podczas kompilacji obecnie się znajdujesz. Duża liczba zależności api może spowodować znacznie wydłużają czas kompilacji. O ile nie chcesz ujawniać API zależności do osobnego modułu, moduły biblioteki użyj zależności implementation.
compileOnly	Gradle dodaje zależność tylko do ścieżki klasy kompilacji (czyli nie jest dodawany do danych wyjściowych kompilacji). Jest to przydatne, gdy tworzysz moduł Androida i potrzebujesz zależności kompilację, ale opcjonalnie możesz umieścić ją w czasie działania. Dla: Jeśli korzystasz z biblioteki, która zawiera tylko adnotacje podczas kompilacji (zwykle jest ona używana do generowania kodu, ale często nie jest uwzględniana w danych wyjściowych kompilacji), możesz oznaczyć ją jako compileOnly. Jeśli używasz tej konfiguracji, moduł musi Uwzględnij warunek środowiska wykonawczego, aby sprawdzić, czy zależność a potem płynnie zmienić jego działanie, , jeśli nie jest podana. Pomaga to zmniejszyć nie dodając zależności tymczasowych, które nie są kluczowe. Uwaga: nie możesz użyć compileOnly z zależnościami Android Archive (AAR).
runtimeOnly	Gradle dodaje zależność tylko do danych wyjściowych kompilacji, gdzie jest używana w trakcie działania. Oznacza to, że nie jest on dodawany do ścieżki klasy kompilacji. Rzadko jest używana na Androidzie, ale jest często używana na serwerze które zapewniają implementacje logowania. Na przykład plik może użyć interfejsu API logowania, który nie zawiera atrybutu implementacji. Użytkownicy tej biblioteki mogą dodać ją jako implementation i uwzględnij komponent Zależność runtimeOnly rzeczywistego logowania implementacji.
ksp kapt annotationProcessor	Te konfiguracje udostępniają biblioteki przetwarzające adnotacje i innych symboli w kodzie. Zwykle sprawdzać poprawność kodu lub generować dodatkowy kod, ograniczając co trzeba napisać. Aby dodać taką zależność, musisz dodać ją do ścieżki klasy procesora adnotacji przy użyciu konfiguracji ksp, kapt lub annotationProcessor. Zastosowanie konfiguracje poprawia wydajność kompilacji przez rozdzielanie kompilacji classpath ze ścieżki klasy procesora adnotacji. Jeśli Gradle znajdzie procesora adnotacji w ścieżce klasy kompilacji, dezaktywuje unikanie kompilacji, które negatywnie wpływa na czas kompilacji (Gradle W wersji 5.0 lub nowszej ignorowane są procesory adnotacji znajdujące się w kompilacji classpath). Wtyczka Androida do obsługi Gradle zakłada, że zależność jest adnotacją procesora, jeśli plik JAR zawiera ten plik: META-INF/services/javax.annotation.processing.Processor Jeśli wtyczka wykryje procesor adnotacji znajdujący się w skompiluj ścieżkę klasy, zwraca błąd kompilacji. ksp to procesor symboli Kotlin, który jest uruchamiany przez Kompilator Kotlin. kapt i apt to osobne narzędzia, które przed uruchomieniem kompilatorów Kotlin lub Java. Wybierając konfigurację, weź pod uwagę : Jeśli procesor jest dostępny jako procesor symboli Kotlin, użyj go jako zależność ksp. Zobacz Migracja z kapt do ksp. . Jeśli procesor nie jest dostępny jako procesor symboli Kotlin: Jeśli Twój projekt zawiera źródło Kotlin (ale może też dodaj kod źródłowy Java), użyj kapt , aby go uwzględnić. Jeśli Twój projekt używa tylko źródła w Javie, użyj annotationProcessor, aby go uwzględnić. Więcej informacji o korzystaniu z procesorów adnotacji znajdziesz w artykule Dodaj procesory adnotacji.
lintChecks	Użyj tej konfiguracji, aby dołączyć bibliotekę zawierającą lint testy, które mają być wykonywane przez Gradle podczas tworzenia aplikacji na Androida w projektach AI. Pamiętaj, że AAR, które zawierają plik lint.jar, automatycznie uruchamiać testy zdefiniowane w tym pliku lint.jar; nie musisz dodawać wyraźnej zależności lintChecks. Dzięki temu możesz zdefiniować biblioteki i powiązane kontrole lint w jednym zależność, która zapewnia, że weryfikacja jest przeprowadzana, gdy konsumenci bibliotece.
lintPublish	Użyj tej konfiguracji w projektach biblioteki Androida, aby uwzględnić lint sprawdzanie, które Gradle ma skompilować w plik lint.jar i przesyłki w AAR. Oznacza to, że projekty zużywają AAR, aby przeprowadzić także kontrole lint. Jeśli wcześniej używasz konfiguracja zależności lintChecks uwzględniająca lint w opublikowanym AAR, musisz przenieść te zależności , aby zamiast tego użyć konfiguracji lintPublish. Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Odlotowe dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Konfigurowanie zależności dla określonego wariantu kompilacji

Wszystkie poprzednie konfiguracje stosują zależności do wszystkich wariantów kompilacji. Jeśli lepiej zadeklarować zależność tylko dla konkretnej kompilacji wariantzbioru źródeł lub dla źródła testowego , musisz napisać wielkimi literami nazwę konfiguracji. nazwę i poprzedź ją nazwą wariantu kompilacji lub testowego zbioru źródłowego.

Aby np. dodać zdalną zależność binarną tylko do tagu „bezpłatne” produkt rodzaj za pomocą konfiguracji implementation, użyj tego:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Odlotowe

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Jeśli jednak chcesz dodać zależność dla wersji, która łączy produkt i typ kompilacji, musisz zainicjować nazwę konfiguracji:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Odlotowe

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Aby dodać zależności (implementation) na potrzeby testów lokalnych i testów instrumentowanych , wygląda to tak:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
}

Odlotowe

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
}

Jednak w takiej sytuacji niektóre konfiguracje nie mają sensu. Przykład: ponieważ inne moduły nie mogą zależeć od funkcji androidTest, otrzymasz następujący ostrzeżenie, jeśli używasz konfiguracji androidTestApi:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Kolejność zależności

Kolejność wyświetlania zależności wskazuje ich priorytet: pierwsza biblioteka ma wyższy priorytet niż druga, a druga – niż trzeci itd. Kolejność ta jest ważna, jeśli zasoby zostały scalone lub elementy manifestu są scalane do aplikacji z bibliotek.

Jeśli na przykład projekt deklaruje te elementy:

• Zależność od LIB_A i LIB_B (w tej kolejności)
• LIB_A zależy od tych danych: LIB_C i LIB_D (w tej kolejności)
• LIB_B zależy również od: LIB_C

W takiej sytuacji kolejność zależności stałych będzie wyglądać tak:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Dzięki temu zarówno LIB_A, jak i LIB_B mogą zastąpić LIB_C; a LIB_D ma nadal wyższy priorytet niż LIB_B, ponieważ LIB_A (w zależności od tego) ma wyższy priorytet niż LIB_B.

Aby uzyskać więcej informacji o plikach manifestu z różnych projektów źródła/zależności zostały scalone, patrz Scalanie wielu plików manifestu.

Informacje o zależności w Konsoli Play

podczas tworzenia aplikacji, AGP uwzględnia metadane opisujące bibliotekę. zawarte w niej zależności. Podczas przesyłania aplikacji link Google Play Konsola sprawdza te metadane, aby wygenerować alerty o znanych problemach z pakietami SDK oraz i w razie potrzeby przekazywać praktyczne opinie, ich rozwiązania.

Dane są kompresowane, szyfrowane kluczem podpisywania Google Play i przechowywane do bloku podpisywania aplikacji w wersji. Zalecamy zachowanie tych zależności aby zadbać o bezpieczeństwo i pozytywne wrażenia użytkowników. Aby zrezygnować, dodaj obserwujesz dependenciesInfo w pliku build.gradle.kts modułu.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Więcej informacji o naszych zasadach i potencjalnych problemach z zależnościami znajdziesz tutaj: naszej strony pomocy używasz w aplikacji pakietów SDK innych firm.

Statystyki dotyczące pakietu SDK

Android Studio wyświetla ostrzeżenia lint w pliku katalogu wersji oraz projekcie Okno struktury publicznych pakietów SDK w Platforma Google Play SDK Index, jeśli występują te problemy:

• Pakiety SDK zostały oznaczone przez autorów jako nieaktualne.
• Naruszają zasady Google Play.

Ostrzeżenia sygnalizują, że trzeba zaktualizować te zależności, ponieważ że używanie nieaktualnych wersji może uniemożliwić publikowanie w Google Play konsoli w przyszłości.

Dodaj zależności kompilacji bez katalogów wersji

Zalecamy korzystanie z katalogów wersji do dodawania zależności i zarządzania nimi, ale jest to proste projekty mogą nie być potrzebne. Oto przykład pliku kompilacji, który nie korzysta katalogi wersji:

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Odlotowe

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

Ten plik kompilacji deklaruje zależność od wersji 12.3 metody „app-magic” w bibliotece „com.example.android”, grupy przestrzeni nazw. Zdalny plik binarny deklaracja zależności to skrócony skrót dla:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Odlotowe

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

W pliku kompilacji deklarujesz też zależność od modułu biblioteki Androida o nazwie "mylibrary"; ta nazwa musi być zgodna z nazwą biblioteki zdefiniowaną w tagu include: w Twój plik settings.gradle.kts. Podczas tworzenia aplikacji system kompilacji skompiluje moduł biblioteki i pakuje otrzymaną zawartość w pliku .

Plik kompilacji deklaruje również zależność od wtyczki Androida do obsługi Gradle. (com.application.android). Jeśli masz kilka modułów korzystających z tego samego wtyczki, w ścieżce klasy kompilacji możesz mieć tylko jedną wersję wtyczki we wszystkich modułach. Zamiast określać wersję w każdym module skrypt kompilacji, umieść zależność wtyczki w głównym skrypcie kompilacji z wersją i wskazać, by jej nie stosować. Dodaję opowiadania (apply false) Gradle, aby zanotować wersję wtyczki, ale nie używać jej w kompilacji głównej. Zwykle główny skrypt kompilacji jest pusty z wyjątkiem tego bloku plugins.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Odlotowe

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Jeśli masz projekt z jednym modułem, możesz jawnie podać wersję skrypt kompilacji na poziomie modułu i pozostaw skrypt kompilacji na poziomie projektu pusty:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Odlotowe

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}