Libreria di supporto

Nota: con il rilascio di Android 9.0 (livello API 28), è disponibile una nuova versione della libreria di supporto chiamata AndroidX, che fa parte di Jetpack. La libreria AndroidX contiene la libreria di supporto esistente e include anche i componenti Jetpack più recenti.

Puoi continuare a utilizzare la libreria di assistenza. Gli artefatti storici (quelli con versione 27 e precedenti e pacchettizzati come android.support.*) rimarranno disponibili in Google Maven. Tuttavia, lo sviluppo di tutte le nuove librerie avverrà nella libreria AndroidX.

Ti consigliamo di utilizzare le librerie AndroidX in tutti i nuovi progetti. Dovresti anche prendere in considerazione la migrazione dei progetti esistenti ad AndroidX.

Durante lo sviluppo di app che supportano più versioni dell'API, ti consigliamo di utilizzare un metodo standard per fornire funzionalità più recenti sulle versioni precedenti di Android oppure di ripristinare le funzionalità equivalenti. Anziché creare codice per gestire le versioni precedenti della piattaforma, puoi utilizzare queste librerie per fornire il livello di compatibilità. Inoltre, le librerie di assistenza offrono ulteriori classi di comodità e funzionalità non disponibili nell'API Framework standard per semplificare lo sviluppo e il supporto su più dispositivi.

In origine un'unica libreria binaria per le app, Android Support Library si è evoluta in una suite di librerie per lo sviluppo di app. Molte di queste librerie sono ora fortemente consigliate, se non essenziali, per lo sviluppo di app.

Questo documento fornisce una panoramica della libreria di assistenza per aiutarti a comprendere i suoi componenti e come utilizzarla in modo efficace nella tua app.

Attenzione: a partire dalla release 26.0.0 di Support Library (luglio 2017), il livello API minimo supportato nella maggior parte delle librerie di supporto è aumentato ad Android 4.0 (livello API 14) per la maggior parte dei pacchetti di librerie. Per ulteriori informazioni, vedi Supporto versione e nomi pacchetti in questa pagina.

Utilizzi delle librerie di assistenza

Esistono diversi utilizzi delle librerie di supporto. Le classi di compatibilità con le versioni precedenti della piattaforma sono solo una di queste. Ecco un elenco più completo dei modi in cui puoi utilizzare le librerie di supporto nella tua app:

  • Compatibilità con le versioni precedenti delle API più recenti: una grande quantità di librerie di supporto garantisce la compatibilità con le versioni precedenti di classi e metodi di framework più recenti. Ad esempio, la classe di supporto Fragment fornisce supporto per i frammenti sui dispositivi che eseguono versioni precedenti ad Android 3.0 (livello API 11).
  • Classi di comodità e helper: le librerie di supporto forniscono una serie di classi helper, in particolare per lo sviluppo dell'interfaccia utente. Ad esempio, la classe RecyclerView fornisce un widget dell'interfaccia utente per visualizzare e gestire elenchi molto lunghi, utilizzabile sulle versioni di Android a partire dal livello API 7 e successivi.
  • Debug e utilità: sono disponibili numerose funzionalità oltre al codice che incorpori nella tua app, tra cui la libreria support-annotations per controlli migliorati del lint del codice sugli input dei metodi e il supporto Multidex per la configurazione e la distribuzione delle app con oltre 65.536 metodi.

Utilizzo dell'assistenza e delle API Framework

Le librerie di assistenza forniscono classi e metodi molto simili alle API nel framework Android. Dopo averlo scoperto, potresti chiederti se dovresti usare la versione framework dell'API o l'equivalente della libreria di supporto. Di seguito sono riportate le linee guida su quando utilizzare le classi della libreria di supporto al posto delle API Framework:

  • Compatibilità per una funzionalità specifica: se vuoi supportare una funzionalità recente della piattaforma su dispositivi che eseguono versioni precedenti della piattaforma, utilizza le classi e i metodi equivalenti della libreria di assistenza.
  • Compatibilità per le funzionalità delle librerie correlate: le classi delle librerie di supporto più sofisticate possono dipendere da una o più classi delle librerie di supporto aggiuntive, perciò è consigliabile utilizzare classi delle librerie di supporto per queste dipendenze. Ad esempio, la classe di assistenza ViewPager deve essere utilizzata con le classi di assistenza FragmentPagerAdapter o FragmentStatePagerAdapter.
  • Compatibilità generale dei dispositivi. Se non disponi di una funzionalità specifica della piattaforma che intendi utilizzare con la tua app in modo compatibile con le versioni precedenti, è comunque consigliabile utilizzare le classi di librerie di supporto nell'app. Ad esempio, potresti utilizzare ActivityCompat al posto della classe Activity del framework, per poter sfruttare le funzionalità più recenti in un secondo momento, come incorporare il nuovo modello di autorizzazioni introdotto in Android 230 (livello API 2.0).

Le classi di supporto della libreria che forniscono un'implementazione compatibile delle classi API della piattaforma potrebbero non essere in grado di fornire l'insieme completo delle funzionalità disponibili nella release più recente, a causa delle limitazioni della versione della piattaforma del dispositivo host. In questi casi, le classi della libreria di supporto sono progettate per eseguire la riduzione in modo controllato e potrebbero non fornire tutte le funzionalità o i dati dell'API attuale della piattaforma. Per questo motivo, devi esaminare la documentazione di riferimento per le classi e i metodi della libreria che utilizzi ed eseguire test approfonditi sui dispositivi che eseguono la versione meno recente della piattaforma supportata dalla tua app.

Nota: le librerie di supporto non forniscono classi e metodi equivalenti per ogni API framework. In alcuni casi, potresti dover eseguire il wrapping di una chiamata al metodo framework con un controllo esplicito della versione dell'SDK e fornire un codice alternativo per gestire i metodi non disponibili su un dispositivo. Per ulteriori informazioni sull'utilizzo dei controlli della versione nel codice, consulta la pagina relativa al supporto di diverse versioni della piattaforma.

Supporto delle versioni e nomi dei pacchetti

Alcuni pacchetti della libreria di supporto hanno nomi di pacchetto che indicano il livello minimo dell'API supportato in origine, utilizzando una notazione v#, come il pacchetto support-v4. A partire dalla versione 26.0.0 della libreria di supporto (rilasciata a luglio 2017), il livello API minimo supportato è stato modificato in Android 4.0 (livello API 14) per tutti i pacchetti della libreria di supporto. Per questo motivo, quando lavori con una release recente della libreria di supporto, non devi dare per scontato che la notazione del pacchetto v# indichi un livello minimo di supporto API. Questa modifica nelle release recenti significa anche che i pacchetti di librerie con le versioni v4 e v7 sono essenzialmente equivalenti nel livello minimo di API supportato. Ad esempio, il pacchetto support-v4 e support-v7 supportano entrambi un livello API minimo di 14 per le release della Support Library 26.0.0 e successive.

Versioni release della libreria di supporto

La versione di release della Support Library, ad esempio 24.2.0 o 25.0.1, è diversa dal livello API minimo supportato da qualsiasi libreria in quella release.Il numero di versione della release indica la versione dell'API della piattaforma su cui è stata creata e, di conseguenza, le API più recenti che potrebbero essere incluse in questa versione delle librerie.

In particolare, la prima sezione del numero di versione della release, ad esempio la 24 nella versione 24.2.0, corrisponde in genere alla versione dell'API della piattaforma disponibile al momento del rilascio. Il livello della versione di release della libreria di supporto indica che incorpora alcune funzionalità di tale livello API, ma non devi dare per scontato che fornisca compatibilità con tutte le funzionalità rilasciate nella nuova versione dell'API della piattaforma.

Dipendenze libreria

La maggior parte delle librerie della suite Android Support Library ha alcune dipendenze da una o più librerie. Ad esempio, quasi tutte le librerie di supporto hanno una dipendenza dal pacchetto support-compat. In generale, non devi preoccuparti del supporto delle dipendenze delle librerie, poiché lo strumento di creazione Gradle gestisce per te le dipendenze delle librerie includendo automaticamente le librerie dipendenti.

Se vuoi vedere quali librerie e dipendenze di libreria sono incluse nella tua app, esegui questo comando nella radice di build del progetto di sviluppo di app per ricevere un report sulle dipendenze del progetto, incluse le librerie di assistenza Android e altre librerie:

gradle -q dependencies your-app-project:dependencies

Per ulteriori informazioni sull'aggiunta di librerie di supporto al tuo progetto di sviluppo utilizzando Gradle, consulta Configurazione della libreria di supporto. Per saperne di più sull'utilizzo di Gradle, consulta Configurare la build.

Tieni presente che tutte le librerie di supporto Android dipendono anche da un livello base della piattaforma, per le release recenti, ovvero Android 4.0 (livello API 14) o versioni successive.