Questa pagina è stata tradotta dall'API Cloud Translation.

Creare una raccolta Android

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

Tuttavia, invece di compilarla in un APK eseguito su un dispositivo, una libreria Android viene compilata in un file AAR (Android Archive) 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 classi e metodi Kotlin o Java.
I file AAR possono contenere librerie C/C++ da utilizzare con il codice C/C++ del modulo dell'app.

Un modulo della biblioteca è utile nelle seguenti situazioni:

Quando crei più app che usano alcuni degli stessi componenti, ad esempio attività, servizi o
Quando sviluppi un'app che esiste in più varianti dell'APK, ad esempio una versione senza costi e una a pagamento, che condividono componenti principali

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

In questa pagina viene spiegato come creare e utilizzare un modulo Libreria Android. Per indicazioni su come pubblicare una raccolta, consulta Pubblicare la raccolta.

Crea un modulo della libreria

Per creare un nuovo modulo della libreria nel tuo progetto, procedi come segue:

Fai clic su File > Nuovo > Nuovo modulo.
Nella finestra di dialogo Crea nuovo modulo visualizzata, fai clic su Libreria Android, quindi fai clic su Avanti.
C'è anche un'opzione per creare una libreria Kotlin o Java, che crea un file JAR tradizionale. Sebbene un file JAR sia utile per molti progetti, soprattutto quando vuoi condividere codice con altre piattaforme, non consente di includere risorse Android o file manifest, che sono molto utili per il riutilizzo del codice nei progetti Android. Questa guida è incentrata sulla creazione di librerie Android.
Assegna un nome alla libreria e seleziona una versione minima dell'SDK per il codice nella libreria, quindi fai clic su Fine.
Importante: i nomi dei pacchetti di moduli devono essere univoci a livello globale. Non possono esistere due moduli con lo stesso nome di pacchetto nello stesso progetto.

Una volta completata la sincronizzazione del progetto Gradle, il modulo della libreria viene visualizzato nel riquadro Progetto. Se non vedi la cartella del nuovo 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 convertirlo in un modulo della libreria nel seguente modo:

Apri il file build.gradle a livello di modulo, se utilizzi Groovy, oppure il file build.gradle.kts, se utilizzi lo script Kotlin.
Elimina la riga per applicationId. Solo un modulo dell'app per Android può definire questa impostazione.

Individua il blocco "plugins" all'inizio del file con un aspetto simile al seguente:

Alla moda

  plugins {
      id 'com.android.application'
  }

Kotlin

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

Modificalo come segue:

Alla moda

  plugins {
      id 'com.android.library'
  }

Kotlin

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

Salva il file e fai clic su File > Sync Project with Gradle Files.

La struttura del modulo è la stessa, ma ora funziona come una libreria Android. La build crea un file AAR invece di un APK.

Quando vuoi creare il file AAR, seleziona il modulo libreria nella finestra Progetto e fai clic su Crea > Crea APK.

Aggiungi dipendenze con la finestra di dialogo Struttura del progetto

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

Utilizzare la raccolta dall'interno dello stesso progetto

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

Vai a File > Struttura del progetto > Dipendenze.
Seleziona il modulo che vuoi aggiungere la libreria.
Nella scheda Dipendenze dichiarate, fai clic su e seleziona Dipendenza modulo dal menu.
Nella finestra di dialogo Aggiungi dipendenza modulo, seleziona il modulo della libreria.
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:

Alla moda

  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 remoti.

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

Per utilizzare il codice della tua libreria Android in un altro modulo dell'app in un altro progetto, procedi come segue:

Vai a File > Struttura del progetto > Dipendenze.
Nella scheda Dipendenze dichiarate, fai clic su e seleziona Dipendenza libreria nel menu.
Nella finestra di dialogo Aggiungi dipendenza libreria, utilizza la casella di ricerca per trovare la libreria da aggiungere. Questo modulo cerca nei repository specificati nel blocco dependencyResolutionManagement { repositories {...}} nel file settings.gradle o settings.gradle.kts.
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 della build selezionata):

Alla moda

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

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

Aggiungi l'AAR o JAR come dipendenza

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

Vai a File > Struttura del progetto > Dipendenze.
Nella scheda Dipendenze dichiarate, fai clic su e seleziona Dipendenza da Jar nel menu.
Nella finestra di dialogo Aggiungi dipendenza jar/Aar, inserisci il percorso del file AAR o JAR, poi seleziona la configurazione a cui si applica la dipendenza. Se la libreria deve essere disponibile per tutte le configurazioni, seleziona la configurazione di implementazione.

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):
Alla moda
```
  implementation files('my_path/my_lib.aar')
```
Kotlin
```
  implementation(files("my_path/my_lib.aar"))
```

Per importare una dipendenza sulla build Gradle in esecuzione al di fuori di Android Studio, aggiungi un percorso alla dipendenza nel file build.gradle o build.gradle.kts della tua app. Ecco alcuni esempi:

Alla moda

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 build.

Dichiara una risorsa pubblica

Le risorse includono tutti i file nella directory res/ del progetto, ad esempio le immagini. Tutte le risorse di una biblioteca sono pubbliche per impostazione predefinita. 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 libreria. Se non hai mai aggiunto risorse pubbliche, devi creare il file public.xml nella directory res/values/ della tua libreria.

Il codice di esempio seguente 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 libreria di accedere a risorse destinate solo a uso interno, utilizza questo meccanismo automatico di designazione privata dichiarando una o più risorse pubbliche. In alternativa, puoi rendere private tutte le risorse aggiungendo un tag <public /> vuoto. In questo modo nulla viene contrassegnato come pubblico e tutte le risorse diventano private.

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

Impostare implicitamente gli attributi impedisce agli utenti della tua libreria di ricevere suggerimenti per il completamento del codice dalle risorse della libreria interna e consente agli utenti di rinominare o rimuovere le risorse private senza interrompere i client della libreria. Le risorse private vengono escluse dal completamento del codice e lo strumento Lint ti avvisa quando provi a fare riferimento a una risorsa privata.

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

Considerazioni sullo sviluppo per i moduli delle biblioteche

Durante lo sviluppo dei moduli della libreria e delle 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 Android, puoi impostare la loro priorità relativa. Al momento della creazione, le librerie vengono unite alle app una alla volta, a partire dalla priorità più bassa fino a quella più alta.
Evita conflitti di unione delle risorse.

Gli strumenti di creazione 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 libreria elencata per prima nell'elenco delle dipendenze (più vicina alla parte superiore del blocco dependencies).

Per evitare conflitti tra le risorse, utilizza le classi R non transitive. Se questo non è possibile, valuta la possibilità di utilizzare un prefisso o un altro schema di denominazione coerente univoco del modulo (o univoco in tutti i moduli del progetto).
Nelle build multimodulo, le dipendenze JAR vengono trattate come dipendenze transitive.

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

Tuttavia, se il progetto include un modulo di libreria utilizzato da un modulo dell'app, quest'ultimo considera la dipendenza JAR locale della libreria come una dipendenza transitiva. In questo caso, il JAR locale viene elaborato dal modulo dell'app che lo utilizza e non dal modulo della libreria. Questo accelera le build incrementali causate da modifiche al codice di una libreria.

Eventuali conflitti delle risorse Java causati da dipendenze JAR locali devono essere risolti nel modulo dell'app che utilizza la libreria.
Un modulo della libreria può dipendere da una libreria JAR esterna.

Puoi sviluppare un modulo della libreria che dipende da una libreria esterna. In questo caso il modulo dipendente deve essere creato in base a una destinazione che include la libreria esterna.

Tieni presente che sia il modulo libreria sia l'app dipendente devono dichiarare la libreria esterna nei file manifest in un elemento <uses-library>.
Il valore minSdkVersion del modulo dell'app deve essere uguale o superiore alla versione definita dalla libreria.

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, questi vengono compilati in un file AAR e poi aggiunti al modulo dell'app. Di conseguenza, ogni libreria ha la propria classe R, denominata in base al nome del pacchetto della libreria.

La classe R generata dal modulo principale e il 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 creare e pubblicare un AAR, puoi aggiungere un file di configurazione ProGuard alla configurazione di compilazione della libreria. In questo caso, il plug-in Android Gradle applica le regole ProGuard che hai specificato. Gli strumenti di creazione incorporano questo file all'interno del file AAR generato per il modulo 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.

Incorporando un file ProGuard nel modulo della libreria, avrai la certezza che i moduli dell'app che dipendono dalla libreria non debbano aggiornare manualmente i file ProGuard per utilizzare la libreria. Quando il sistema di build di Android Studio crea la tua app, utilizza le istruzioni sia del modulo dell'app sia della libreria. Pertanto, non è necessario eseguire uno shrinker di codice sulla libreria in un passaggio separato.

Per aggiungere regole ProGuard al tuo progetto 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, il seguente snippet imposta lib-proguard-rules.txt come file di configurazione ProGuard della libreria:
Alla moda
```
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 build multimodulo che si compila in un APK e non genera un AAR, esegui la riduzione del codice solo sul modulo dell'app che utilizza la libreria. Per scoprire di più sulle regole ProGuard e sul loro utilizzo, leggi Ridurre, offuscare e ottimizzare l'app.
Testare un modulo della libreria è quasi come testare 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'AR della libreria e tutte le sue dipendenze. Poiché non esiste un'app separata da testare, l'attività androidTest installa (e disinstalla) solo l'APK di test.

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

Struttura di un file AAR

L'estensione del file per un file AAR è .aar, così come il tipo di artefatto Maven è aar. Il file stesso è un file ZIP. L'unica voce obbligatoria è /AndroidManifest.xml.

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

/classes.jar
/res/
/R.txt
/public.txt
/assets/
/libs/name.jar
/jni/abi_name/name.so (dove abi_name è una delle ABI supportate da Android)
/proguard.txt
/lint.jar
/api.jar
/prefab/ per l'esportazione di librerie native