Tworzenie biblioteki na Androida

Biblioteka Androida ma taką samą strukturę jak moduł aplikacji na Androida. Zawiera wszystko, co jest potrzebne do stworzenia aplikacji, w tym kod źródłowy, plików zasobów i pliku manifestu Androida.

Jednak zamiast kompilować w pliku APK działającym na urządzeniu, biblioteka Androida skompiluje się w plik Android Archive (AAR), mogą służyć jako zależność w module aplikacji na Androida. W przeciwieństwie do plików JAR Pliki AAR oferują te funkcje w przypadku aplikacji na Androida:

  • Pliki AAR mogą zawierać zasoby Androida i plik manifestu, który umożliwia łączą wspólne zasoby, takie jak układy i elementy rysunkowe, do klas i metod Kotlin lub Javy.
  • Pliki AAR mogą zawierać ciąg C/C++ biblioteki do wykorzystania w kodzie C/C++ modułu aplikacji.

Moduł biblioteki przydaje się wtedy, gdy:

  • Gdy tworzysz wiele aplikacji, które korzystają z niektórych te same komponenty, takie jak czynności, usługi czy układy interfejsu;
  • Podczas tworzenia aplikacji, która istnieje w wielu odmianach pliku APK, na przykład bezpłatnej i płatnej wersji, które mają wspólne podstawowe komponenty.

W obu przypadkach przenieś pliki, których chcesz użyć ponownie, do modułu biblioteki, a następnie a potem dodaj bibliotekę jako zależność dla każdego modułu aplikacji.

Z tego artykułu dowiesz się, jak utworzyć bibliotekę Androida i jak z niej korzystać . Aby dowiedzieć się, jak opublikować bibliotekę, zobacz Publikowanie biblioteki

Tworzenie modułu biblioteki

Aby utworzyć w projekcie nowy moduł biblioteki, wykonaj te czynności:

  1. Kliknij Plik > Nowe > Nowy moduł.
  2. W wyświetlonym oknie Create New Module (Utwórz nowy moduł) Kliknij kolejno Biblioteka Androida i Dalej.

    Możesz też utworzyć bibliotekę Kotlin lub Java, który tworzy tradycyjny plik JAR. Plik JAR przydaje się wielu projektów – szczególnie jeśli chcesz udostępnić kod innym platform – nie pozwala na dodanie zasobów Androida ani pliku manifestu. co bardzo przydaje się do ponownego użycia kodu w projektach Androida. Ten przewodnik Skupia się na tworzeniu bibliotek Androida.

  3. Nazwij bibliotekę i wybierz minimalną wersję pakietu SDK dla kodu w bibliotece i kliknij Zakończ.

Po zakończeniu synchronizacji projektu Gradle moduł biblioteki pojawi się w w panelu Projekt. Jeśli nie widzisz nowego modułu sprawdź, czy w panelu wyświetla się widok Android.

Konwertowanie modułu aplikacji na moduł biblioteki

Jeśli masz już moduł aplikacji z kodem, którego chcesz użyć ponownie, możesz go przekształcić w moduł biblioteki w następujący sposób:

  1. Otwórz plik build.gradle na poziomie modułu, jeśli korzystasz Groovy lub build.gradle.kts, jeśli używasz Kotlin skrypt.
  2. Usuń wiersz: applicationId. Może to być zdefiniowane tylko w module aplikacji na Androida.
  3. U góry pliku znajdź blok „wtyczki”, który wygląda tak:

    Odlotowe

      plugins {
          id 'com.android.application'
      }
      

    Kotlin

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

    Zmień go na taki:

    Odlotowe

      plugins {
          id 'com.android.library'
      }
      

    Kotlin

      plugins {
          id("com.android.library")
      }
      
  4. Zapisz plik i kliknij Plik > Synchronizowanie projektu z plikami Gradle

Struktura modułu pozostaje taka sama, ale który działa jak biblioteka Androida. Kompilacja tworzy plik AAR. zamiast pliku APK.

Jeśli chcesz utworzyć plik AAR, wybierz moduł biblioteki Projekt i kliknij Kompilacja > Build APK

Dodawanie zależności w oknie Struktura projektu

W oknie Struktura projektu możesz dodać zależności w projektach AI. W poniższych sekcjach opisano, jak za pomocą okna dialogowego dodawania zależności.

Korzystaj z biblioteki w tym samym projekcie

Aby użyć kodu nowej biblioteki na Androida w innym module aplikacji lub biblioteki w w tym samym projekcie, dodaj zależność na poziomie projektu:

  1. Przejdź do Plik > Projekt Struktura > Zależności.
  2. Wybierz moduł, do którego chcesz dodać bibliotekę.
  3. Na karcie Deklarowane zależności kliknij i wybierz Module Dependency (Zależność modułu).

  4. W oknie Dodaj zależność modułu wybierz moduł biblioteki.

    Dodaj zależność modułów w strukturze projektu
Okno

  5. Wybierz konfigurację, która wymaga tej zależności, lub wybierz implementacji, jeśli dotyczy ona wszystkich konfiguracji, i kliknij OK.

Android Studio edytuje plik build.gradle lub build.gradle.kts modułu na dodaj zależność w takim formacie:

Odlotowe

  implementation project(path: ":example-library")

Kotlin

  implementation(project(":example-library"))

Używaj swojej biblioteki w innych projektach

Zalecanym sposobem udostępniania zależności (plików JAR i AAR) jest użycie narzędzia Maven repozytorium hostowane w usłudze, takiej jak Maven Central lub ze strukturą katalogów na dysku lokalnym. Więcej informacji o korzystaniu z Repozytoria Maven – patrz Zdalna z repozytoriów.

Po opublikowaniu biblioteki Androida w repozytorium Maven metadane są aby zależności z biblioteki były uwzględnione w parametrze zużywających kompilację. Dzięki temu biblioteka może automatycznie usuwać duplikaty, jeśli jest używany w wielu miejscach.

Aby użyć kodu z biblioteki Androida w innym module aplikacji w innym projekcie, wykonaj następujące czynności:

  1. Nawiguj do Plik > Struktura projektu > Zależności.
  2. Na karcie Deklarowane zależności kliknij i wybierz Zależność bibliotek.

  3. W oknie Dodaj zależność biblioteki użyj pola wyszukiwania, aby znaleźć do biblioteki. Ten formularz przeszukuje repozytoria określone w w bloku dependencyResolutionManagement { repositories {...}} w settings.gradle lub settings.gradle.kts.

    Dodaj zależność biblioteki w strukturze projektu
Okno

  4. Wybierz konfigurację, która wymaga tej zależności, lub wybierz implementacji, jeśli dotyczy ona wszystkich konfiguracji, i kliknij OK.

Sprawdź plik build.gradle lub build.gradle.kts aplikacji, aby upewnić się, że deklaracja podobna do tej (w zależności od konfiguracji kompilacji wybranego dokumentu):

Odlotowe

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

  implementation("com.example:examplelibrary:1.0.0")

Dodaj AAR lub JAR jako zależność

Aby użyć kodu z biblioteki na Androida w innym module aplikacji, wykonaj te czynności:

  1. Kliknij Plik >. Struktura projektu > Zależności.
  2. Na karcie Deklarowane zależności kliknij i wybierz Jar Zależność w menu.

  3. W oknie Dodaj zależność Jar/Aar wpisz ścieżkę do pliku AAR. lub JAR, a potem wybierz konfigurację, do której zależność ma zastosowanie. Jeśli biblioteka ma być dostępna dla wszystkich konfiguracji, wybierz implementacji.

    Dodaj zależność AAR w strukturze projektu
Okno

    Sprawdź plik build.gradle lub build.gradle.kts aplikacji, aby upewnić się, że deklaracja podobna do tej (w zależności od konfiguracji kompilacji wybranego dokumentu):

    Odlotowe

      implementation files('my_path/my_lib.aar')
    

    Kotlin

      implementation(files("my_path/my_lib.aar"))
    

Aby zaimportować zależność od kompilacji Gradle uruchomionej poza Android Studio: dodaj ścieżkę do zależności w plik build.gradle lub build.gradle.kts aplikacji. Na przykład:

Odlotowe

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

Kotlin

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

Więcej informacji o dodawaniu zależności Gradle znajdziesz w artykule Dodaj zależności kompilacji.

Deklarowanie zasobu publicznego

Zasoby obejmują wszystkie pliki znajdujące się w katalogu res/ projektu, takich jak obrazy. Wszystkie zasoby w bibliotece domyślnie są publiczne. Aby wszystkie zasobów niejawnie prywatnych, należy zdefiniować co najmniej jeden konkretny atrybut jako publiczne.

Aby zadeklarować zasób publiczny, dodaj deklarację <public> do pliku public.xml z Twojej biblioteki. Jeśli nie dodano publicznego albumu , musisz utworzyć plik public.xml w Katalog res/values/ Twojej biblioteki.

Poniższy przykładowy kod tworzy 2 publiczne zasoby ciągu znaków z atrybutem nazwy mylib_app_name i mylib_public_string:

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

Aby uniemożliwić użytkownikom biblioteki dostęp do zamierzonych zasobów tylko do użytku wewnętrznego, użyj tego automatycznego oznaczenia prywatnego przez zadeklarowanie co najmniej jednego zasobu publicznego. Możesz też wszystkie zasoby są prywatne, dodając pusty tag <public />. Ten nie oznacza nic jako publicznego i sprawia, że wszystkie zasoby są prywatne.

Wszystkie zasoby, które mają pozostać widoczne dla użytkowników używający Twojej biblioteki, ustaw jako publiczne.

Pośrednie ustawienie atrybutów jako prywatnych uniemożliwia użytkownikom korzystanie z Twojej biblioteki z otrzymywania sugestii uzupełnienia kodu z wewnętrznych zasobów biblioteki i pozwala użytkownikom zmieniać nazwy lub usuwać zasoby prywatne bez uszkodzenia klientów Twojej biblioteki. zasoby prywatne są odfiltrowywane z uzupełniania kodu, a narzędzie Lint ostrzega, gdy spróbujesz , aby odwołać się do zasobu prywatnego.

Podczas tworzenia biblioteki wtyczka Androida do obsługi Gradle pobiera zasób publiczny i wyodrębnia je do pliku public.txt, który jest i spakuj je do pliku AAR.

Uwagi na temat programowania modułów biblioteki

Pracując nad modułami w bibliotece i aplikacjami zależnych, pamiętaj o następujących kwestiach: w przypadku tych zachowań i ograniczeń.

  • Biblioteki są scalane w kolejności według priorytetu.

    Gdy dodasz odwołania do modułów biblioteki do modułu aplikacji na Androida, możesz ustawić ich względny priorytet. W momencie kompilacji biblioteki są scalane z aplikacją pojedynczo, począwszy od najmniejszej z najwyższym priorytetem.

  • Unikaj konfliktów podczas scalania zasobów.

    Narzędzia do kompilacji łączą zasoby z modułu biblioteki z zasobami z modułu zależnego aplikacji. Jeśli dany identyfikator zasobu jest zdefiniowany w obu modułach, parametr zasobu z aplikacji.

    Jeśli występują konflikty między wieloma bibliotekami AAR, zasób z biblioteka jest wymieniona jako pierwsza na liście zależności (blisko początku listy zależności dependencies).

    Aby uniknąć konfliktów zasobów, używaj nieprzechodnich klas R. Jeśli to niemożliwe, spróbuj użyć tagu prefiksu lub innego spójnego nazewnictwa, który jest unikalny dla modułu (lub unikalne dla wszystkich modułów projektu).

  • W kompilacjach złożonych z wielu modułów zależności JAR są traktowane jako zależności pośrednie.

    Gdy dodasz zależność JAR do projektu biblioteki, który generuje odpowiedź AAR, plik JAR jest przetwarzany przez moduł biblioteki i dołączony do pakietu AAR.

    Jeśli jednak projekt zawiera moduł biblioteki, który jest wykorzystywany przez aplikację traktuje lokalną zależność JAR biblioteki jako zależność przejściowa. W tym przypadku lokalny plik JAR jest przetwarzany przez aplikację. za jej pomocą, a nie przez moduł biblioteki. To przyspiesza przyrostowe kompilacje powodowane przez zmiany w kodzie biblioteki.

    Wszystkie konflikty zasobów Java spowodowane przez lokalne zależności JAR muszą być rozwiązane w module, który korzysta z biblioteki.

  • Moduł biblioteki może korzystać z zewnętrznej biblioteki JAR.

    Możesz opracować moduł biblioteki zależny od biblioteki zewnętrznej. W tym przypadku moduł zależny musi kompilować z celem, który obejmuje bibliotekę zewnętrzną.

    Pamiętaj, że zarówno moduł biblioteki, jak i aplikacja zależna muszą zadeklarować bibliotekę zewnętrzną w plikach manifestu w <uses-library>.

  • Wartość minSdkVersion modułu aplikacji musi być równa lub jest większa niż wersja zdefiniowana przez bibliotekę.

    Biblioteka jest skompilowana jako część modułu zależnej aplikacji, więc używane przez nią interfejsy API w module biblioteki musi być zgodny z wersją platformy, którą aplikacja obsługiwanych modułów.

  • Każdy moduł biblioteki tworzy własną klasę R.

    Podczas tworzenia zależnych modułów aplikacji moduły biblioteczne są łączone w plik AAR dodany do modułu aplikacji. Dlatego każda biblioteka ma swoje własne R – nadana zgodnie z nazwą pakietu biblioteki.

    Klasa R wygenerowana z modułu głównego i modułu biblioteki to utworzone we wszystkich potrzebnych pakietach, łącznie z pakietem modułu głównego i biblioteki przesyłek.

  • Moduł biblioteki może zawierać własną konfigurację ProGuard .

    Jeśli masz projekt biblioteczny używany do tworzenia i publikowania aplikacji AAR, możesz dodać plik konfiguracji ProGuard do konfiguracji kompilacji Twojej biblioteki. Jeśli tak, wtyczka Androida do obsługi Gradle stosuje określone przez Ciebie reguły ProGuard. Narzędzia do kompilacji umieszczają ten plik w wygenerowanym pliku AAR na potrzeby biblioteki . Po dodaniu biblioteki do modułu aplikacji plik ProGuard biblioteki jest dołączany do pliku konfiguracji ProGuard (proguard.txt) do modułu aplikacji.

    Umieszczając plik ProGuard w module biblioteki, masz pewność, że moduły aplikacji, które są zależne od biblioteki, nie muszą aktualizować swoich pliki ProGuard, aby korzystać z biblioteki. Kiedy kompiluje się system kompilacji Android Studio Twojej aplikacji, używa ona dyrektyw z modułu aplikacji i biblioteki. No więc nie musisz w oddzielnym kroku uruchamiać w bibliotece narzędzia do skracania kodu.

    Aby dodać reguły ProGuard do projektu biblioteki, podaj z właściwością consumerProguardFiles w parametrze defaultConfig blok build.gradle lub build.gradle.kts.

    Na przykład ten zestaw fragmentów kodu lib-proguard-rules.txt jako konfigurację ProGuard biblioteki plik:

    Odlotowe

    android {
        defaultConfig {
            consumerProguardFiles 'lib-proguard-rules.txt'
        }
        ...
    }

    Kotlin

    android {
        defaultConfig {
            consumerProguardFiles("lib-proguard-rules.txt")
        }
        ...
    }

    Jeśli jednak moduł biblioteki jest częścią kompilacji składającej się z wielu modułów, kompiluje się w pakiet APK i nie generuje AAR, uruchamia kod ale będzie ograniczać się tylko do modułu aplikacji, który zużywa bibliotekę. Aby dowiedzieć się więcej, o regułach ProGuard i ich wykorzystaniu, przeczytaj Zmniejszaj, zaciemniaj i optymalizuj

  • Testowanie modułu biblioteki przebiega prawie tak samo testowanie aplikacji.

    Główna różnica polega na tym, że biblioteka i jej zależności są automatycznie uwzględnione jako zależności testowego pakietu APK. Oznacza to, że testowy plik APK zawiera nie tylko własny kod, ale też plik AAR biblioteki i wszystkich zależnościach tego typu. Nie ma osobnej aplikacji w trakcie testowania, Zadanie androidTest instaluje (i odinstalowuje) tylko test plik APK.

    Podczas scalania wielu plików manifestu, Gradle ma domyślną kolejność, scala plik manifestu biblioteki z głównym plikiem manifestu testowego pakietu APK.

Składnia pliku AAR

Plik AAR ma rozszerzenie .aar, a typ artefaktu Maven to aar. Sam plik jest plikiem ZIP. Jedyny wymagany wpis to /AndroidManifest.xml

Plik AAR może też zawierać co najmniej jeden z tych opcjonalnych elementów: wpisy: