Creare una raccolta Android

Una libreria Android è strutturalmente la stessa di un modulo dell'app Android. Include tutto il necessario per creare un'app, tra cui codice sorgente, file di risorse e un file manifest Android.

Tuttavia, anziché compilarsi in un APK che viene eseguito su un dispositivo, una libreria Android viene compilata in un file Android Archive (AAR) che puoi utilizzare come dipendenza per un modulo dell'app Android. A differenza dei file JAR, i file AAR offrono le seguenti funzionalità per le app per Android:

  • I file AAR possono contenere risorse Android e un file manifest, che consente di raggruppare risorse condivise come layout e drawable, oltre a metodi e classi Kotlin o Java.
  • I file AAR possono contenere librerie C/C++ da utilizzare dal codice C/C++ del modulo dell'app.

Un modulo della libreria è utile nelle seguenti situazioni:

  • Quando crei più app che utilizzano alcuni degli stessi componenti, ad esempio attività, servizi o layout dell'interfaccia utente
  • Quando crei un'app disponibile in più varianti APK, ad esempio una versione senza costi e una a pagamento, che condividono componenti di base

In entrambi i casi, sposta i file che vuoi riutilizzare in un modulo della libreria e poi aggiungi la libreria come dipendenza per ogni modulo dell'app.

Questa pagina spiega come creare e utilizzare un modulo della libreria Android. Per indicazioni su come pubblicare una raccolta, consulta Pubblicare una raccolta

Creare un modulo della raccolta

Per creare un nuovo modulo della libreria nel progetto:

  1. Fai clic su File > Nuovo > Nuovo modulo.
  2. Nella finestra di dialogo Crea nuovo modulo visualizzata, fai clic su Libreria Android e poi su Avanti.

    È inoltre possibile creare una libreria Kotlin o Java, che genera un file JAR tradizionale. Sebbene un file JAR sia utile per molti progetti, in particolare quando vuoi condividere il codice con altre piattaforme, non ti consente di includere risorse Android o file manifest, il che è molto utile per il riutilizzo del codice nei progetti Android. Questa guida si concentra sulla creazione di librerie Android.

  3. Assegna un nome alla libreria e seleziona una versione minima dell'SDK per il codice al suo interno, quindi fai clic su Fine.

Al termine della sincronizzazione del progetto Gradle, il modulo della libreria viene visualizzato nel riquadro Progetto. Se non vedi la nuova cartella del modulo, assicurati che nel riquadro sia visualizzata la visualizzazione Android.

Convertire un modulo dell'app in un modulo della libreria

Se hai già un modulo dell'app con codice che vuoi riutilizzare, puoi trasformarlo in un modulo della libreria come segue:

  1. Apri il file build.gradle a livello di modulo se utilizzi Groovy o il file build.gradle.kts se utilizzi lo script Kotlin.
  2. Elimina la riga per applicationId. Solo un modulo dell'app per Android può definirlo.
  3. Individua il blocco "plugins" nella parte superiore del file, che ha il seguente aspetto:

    Groovy

      plugins {
      id 'com.android.application'
  }

    Kotlin

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

    Modificala come segue:

    Groovy

      plugins {
      id 'com.android.library'
  }

    Kotlin

      plugins {
      id("com.android.library")
  }
  4. Salva il file e fai clic su File > Sincronizza progetto con i file Gradle.

La struttura del modulo rimane invariata, ma ora opera come libreria Android. La build crea un file AAR instead of an APK.

Quando vuoi compilare il file AAR, seleziona il modulo della libreria nella finestra Progetto e fai clic su Compila > Compila APK.

Aggiungere dipendenze con la finestra di dialogo Struttura del progetto

Puoi utilizzare la finestra di dialogo Struttura del progetto per aggiungere dipendenze al progetto. Le sezioni seguenti descrivono come utilizzare la finestra di dialogo per aggiungere le dipendenze.

Utilizzare la raccolta all'interno dello stesso progetto

Per utilizzare il codice della nuova libreria Android in un altro modulo di app o libreria all'interno dello stesso progetto, aggiungi una dipendenza a livello di progetto:

  1. Vai a File > Struttura progetto > Dipendenze.
  2. Seleziona il modulo a cui vuoi aggiungere la libreria.
  3. Nella scheda Dipendenze dichiarate, fai clic su e seleziona Dipendenza dal modulo dal menu.

  4. Nella finestra di dialogo Aggiungi dipendenza dal modulo, seleziona il modulo della raccolta.

    Aggiungere la dipendenza dal modulo nella dialogoschitudi Struttura del progetto

  5. Seleziona la configurazione che richiede questa dipendenza o seleziona implementazione se si applica a tutte le configurazioni, quindi fai clic su OK.

Android Studio modifica il file build.gradle o build.gradle.kts del modulo per aggiungere la dipendenza nel seguente formato:

Groovy

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

Kotlin

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

Utilizzare la raccolta in altri progetti

Il modo consigliato per condividere le dipendenze (JAR e AAR) è con un repository Maven, ospitato su un servizio come Maven Central o con una struttura di directory sul disco locale. Per ulteriori informazioni sull'utilizzo dei repository Maven, consulta Repository remote.

Quando una libreria Android viene pubblicata in un repository Maven, i metadati vengono inclusi in modo che le dipendenze della libreria siano incluse nella compilazione che le utilizza. In questo modo, la libreria viene deduplicata automaticamente se viene utilizzata in più posizioni.

Per utilizzare il codice della libreria Android in un altro modulo dell'app in un progetto diverso, proceddi nel seguente modo:

  1. Vai a File > Struttura del progetto > Dipendenze.
  2. Nella scheda Dipendenze dichiarate, fai clic su e seleziona Dipendenza dalla libreria nel menu.

  3. Nella finestra di dialogo Aggiungi dipendenza dalla libreria, utilizza la casella di ricerca per trovare la libreria da aggiungere. Questo modulo esegue ricerche nei repository specificati nel blocco dependencyResolutionManagement { repositories {...}} del file settings.gradle o settings.gradle.kts.

    Aggiungere una dipendenza della libreria nella finestra di dialogo Struttura progetto

  4. Seleziona la configurazione che richiede questa dipendenza o seleziona implementazione se si applica a tutte le configurazioni, quindi fai clic su OK.

Controlla il file build.gradle o build.gradle.kts dell'app per verificare che venga visualizzata una dichiarazione simile alla seguente (a seconda della configurazione di compilazione selezionata):

Groovy

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

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

Aggiungi l'AAR o il JAR come dipendenza

Per utilizzare il codice della libreria Android in un altro modulo dell'app, procedi nel seguente modo:

  1. Vai a File > Struttura del progetto > Dipendenze.
  2. Nella scheda Dipendenze dichiarate, fai clic su e seleziona Dipendenza da jar nel menu.

  3. Nella finestra di dialogo Aggiungi dipendenza Jar/Aar, inserisci il percorso del file AAR o JAR, quindi seleziona la configurazione a cui si applica la dipendenza. Se la libreria deve essere disponibile per tutte le configurazioni, seleziona la configurazione di implementazione.

    Aggiungere la dipendenza AAR nella dialogoschitudistruttura del progetto

    Controlla il file build.gradle o build.gradle.kts dell'app per verificare che venga visualizzata una dichiarazione simile alla seguente (a seconda della configurazione della build selezionata):

    Groovy

      implementation files('my_path/my_lib.aar')

    Kotlin

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

Per importare una dipendenza nella compilazione Gradle eseguita al di fuori di Android Studio, aggiungi un percorso alla dipendenza nel file build.gradle o build.gradle.kts della tua app. Ad esempio:

Groovy

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

Kotlin

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

Per saperne di più sull'aggiunta delle dipendenze Gradle, consulta Aggiungere dipendenze di compilazione.

Dichiarare una risorsa pubblica

Le risorse includono tutti i file nella directory res/ del progetto, come le immagini. Per impostazione predefinita, tutte le risorse di una raccolta sono pubbliche. Per rendere implicitamente private tutte le risorse, devi definire almeno un attributo specifico come pubblico.

Per dichiarare una risorsa pubblica, aggiungi una dichiarazione <public> al file public.xml della tua raccolta. Se non hai mai aggiunto risorse pubbliche, devi creare il file public.xml nella directory res/values/ della tua libreria.

Il seguente codice di esempio crea due risorse stringa pubbliche con i nomi mylib_app_name e mylib_public_string:

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

Per impedire agli utenti della tua raccolta di accedere alle risorse destinate solo all'uso interno, utilizza questo meccanismo di designazione automatica come privato dichiarando una o più risorse pubbliche. In alternativa, puoi impostare come private tutte le risorse aggiungendo un tag <public /> vuoto. In questo modo, non viene contrassegnato nulla come pubblico e tutte le risorse diventano private.

Tutte le risorse che vuoi che rimangano visibili agli sviluppatori che utilizzano la tua libreria devono essere rese pubbliche.

La definizione implicita degli attributi come privati impedisce agli utenti della tua libreria di ricevere suggerimenti di completamento del codice dalle risorse interne della libreria e consente loro di rinominare o rimuovere le risorse private senza interrompere i client della tua libreria. Le risorse private vengono filtrate dalla compilazione automatica del codice e lo strumento di lint ti avvisa quando provi a fare riferimento a una risorsa privata.

Quando viene compilata una libreria, il plug-in Android per Gradle recupera le definizioni delle risorse pubbliche e le estrae nel file public.txt, che viene poi pacchettizzato all'interno del file AAR.

Considerazioni sullo sviluppo per i moduli della libreria

Quando sviluppi i moduli della libreria e le app dipendenti, tieni presente i seguenti comportamenti e limitazioni.

  • Le librerie vengono unite in ordine di priorità.

    Dopo aver aggiunto i riferimenti ai moduli della libreria al modulo dell'app per Android, puoi impostarne la priorità relativa. In fase di compilazione, le librerie vengono unite all'app una alla volta, dalla priorità più bassa a quella più alta.

  • Evita i conflitti di unione delle risorse.

    Gli strumenti di compilazione uniscono le risorse di un modulo della libreria con quelle di un modulo dell'app dipendente. Se un determinato ID risorsa è definito in entrambi i moduli, viene utilizzata la risorsa dell'app.

    Se si verificano conflitti tra più librerie AAR, viene utilizzata la risorsa della biblioteca elencata per prima nell'elenco delle dipendenze (più vicina alla parte superiore del blocco dependencies).

    Per evitare conflitti di risorse, utilizza classi R non transitive. Se non è possibile, valuta la possibilità di utilizzare un prefisso o un altro schema di denominazione coerente univoco per il modulo (o per tutti i moduli del progetto).

  • Nelle build multi-modulo, le dipendenze JAR vengono trattate come dipendenze transitive.

    Quando aggiungi una dipendenza JAR a un progetto della libreria che genera un file AAR, il JAR viene elaborato dal modulo della libreria e pacchettizzato con il relativo file AAR.

    Tuttavia, se il progetto include un modulo della libreria utilizzato da un modulo dell'app, il modulo dell'app tratta la dipendenza JAR locale della libreria come una dipendenza transitiva. In questo caso, il file JAR locale viene elaborato dal modulo dell'app che lo utilizza e non dal modulo della libreria. In questo modo vengono accelerate le compilazioni incrementali causate da modifiche al codice di una libreria.

    Eventuali conflitti di risorse Java causati da dipendenze JAR locali devono essere risolti nel modulo dell'app che utilizza la libreria.

  • Un modulo della raccolta può dipendere da una raccolta JAR esterna.

    Puoi sviluppare un modulo della libreria che dipende da una libreria esterna. In questo caso, il modulo dipendente deve essere compilato in base a un target che includa la libreria esterna.

    Tieni presente che sia il modulo della libreria sia l'app dipendente devono dichiarare la libreria esterna nei propri file manifest in un elemento <uses-library>.

  • Il valore minSdkVersion del modulo dell'app deve essere uguale o superiore alla versione definita dalla raccolta.

    Una libreria viene compilata come parte del modulo dell'app dipendente, pertanto le API utilizzate nel modulo della libreria devono essere compatibili con la versione della piattaforma supportata dal modulo dell'app.

  • Ogni modulo della libreria crea la propria classe R.

    Quando crei i moduli dell'app dipendenti, i moduli della libreria vengono compilati in un file AAR e poi aggiunti al modulo dell'app. Pertanto, ogni libreria ha il proprio R, denominato in base al nome del pacchetto della libreria.

    La classe R generata dal modulo principale e dal modulo della libreria viene creata in tutti i pacchetti necessari, inclusi il pacchetto del modulo principale e i pacchetti delle librerie.

  • Un modulo della libreria potrebbe includere il proprio file di configurazione ProGuard.

    Se hai un progetto di libreria che utilizzi per compilare e pubblicare un file AAR, puoi aggiungere un file di configurazione di ProGuard alla configurazione di compilazione della libreria. In questo caso, il plug-in Gradle per Android applica le regole di ProGuard che hai specificato. Gli strumenti di compilazione incorporano questo file nel file AAR generato per il modulo della libreria. Quando aggiungi la libreria a un modulo dell'app, il file ProGuard della libreria viene aggiunto al file di configurazione ProGuard (proguard.txt) del modulo dell'app.

    Se incorpori un file ProGuard nel modulo della libreria, contribuisci ad assicurarti che i moduli dell'app che dipendono dalla tua libreria non debbano aggiornare manualmente i propri file ProGuard per utilizzarla. Quando il sistema di compilazione di Android Studio compila la tua app, utilizza le direttive sia del modulo dell'app sia della libreria. Pertanto, non è necessario eseguire un compressore di codice sulla libreria in un passaggio separato.

    Per aggiungere le regole ProGuard al progetto della libreria, specifica il nome del file con la proprietà consumerProguardFiles all'interno del blocco defaultConfig del file build.gradle o build.gradle.kts della libreria.

    Ad esempio, lo snippet seguente impostalib-proguard-rules.txt come file di configurazione ProGuard della libreria:

    Groovy

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

    Kotlin

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

    Tuttavia, se il modulo della libreria fa parte di una compilazione multi-modulo che viene compilata in un APK e non genera un file AAR, esegui la riduzione del codice solo sul modulo dell'app che utilizza la libreria. Per scoprire di più sulle regole di ProGuard e sul loro utilizzo, consulta Riduci, offusca e ottimizza la tua app.

  • Il test di un modulo della libreria è quasi uguale al test di un'app.

    La differenza principale è che la libreria e le sue dipendenze vengono incluse automaticamente come dipendenze dell'APK di test. Ciò significa che l'APK di test include non solo il proprio codice, ma anche l'AAR della libreria e tutte le sue dipendenze. Poiché non è presente un'app separata in fase di test, il compito androidTest installa (e disinstalla) solo l'APK di test.

    Quando unisci più file manifest, Gradle segue l'ordine di priorità predefinito e unisce il manifest della libreria al manifest principale dell'APK di test.

Anatomia di un file AAR

L'estensione di un file AAR è .aar e anche il tipo di elemento Maven è aar. Il file stesso è un file ZIP. L'unica voce obbligatoria è /AndroidManifest.xml.

Un file AAR può includere anche una o più delle seguenti voci facoltative: