Le risorse sono i file aggiuntivi e i contenuti statici utilizzati dal codice, come bitmap, definizioni di layout, stringhe dell'interfaccia utente, istruzioni di animazione e altro ancora.
Esterna sempre risorse dell'app come immagini e stringhe dal tuo codice, in modo da poterle gestire in modo indipendente. Inoltre, fornisci risorse alternative per configurazioni di dispositivi specifiche raggruppandole in directory delle risorse con nomi specifici. In fase di runtime, Android utilizza la risorsa appropriata in base alla configurazione attuale. Ad esempio, puoi fornire un layout UI diverso a seconda delle dimensioni dello schermo o stringhe diverse a seconda dell'impostazione della lingua.
Dopo aver esternalizzato le risorse dell'app, puoi accedervi utilizzando gli ID risorsa generati nella classe R del tuo progetto.
Questo documento mostra come raggruppare le risorse nel tuo progetto Android. Mostra inoltre come
fornire risorse alternative per configurazioni di dispositivi specifiche e quindi accedervi dal
codice dell'app o da altri file XML.
Tipi di risorse del gruppo
Inserisci ogni tipo di risorsa in una sottodirectory specifica della directory res/ del progetto. Ad esempio, questa è la gerarchia dei file per un progetto semplice:
MyProject/
src/
MyActivity.java
res/
drawable/
graphic.png
layout/
main.xml
info.xml
mipmap/
icon.png
values/
strings.xml
La directory res/ contiene tutte le risorse nelle relative sottodirectory: una risorsa immagine, due risorse di layout, una directory mipmap/ per le icone di Avvio applicazioni e un file di risorse di tipo stringa. I nomi delle directory delle risorse sono importanti e sono descritti nella tabella 1.
Nota: per ulteriori informazioni sull'uso delle cartelle mipmap, consulta Inserimento delle icone delle app nelle directory mipmap.
Tabella 1. Directory delle risorse supportate all'interno della directory del progetto res/.
| Directory | Tipo di risorsa |
|---|---|
animator/ |
File XML che definiscono le animazioni delle proprietà. |
anim/ |
File XML che definiscono le animazioni
Tween. In questa directory è possibile salvare anche le animazioni delle proprietà, ma
per distinguere i due tipi è preferibile usare la directory animator/. |
color/ |
File XML che definiscono un elenco di stati di colori. Per ulteriori informazioni, consulta la risorsa per l'elenco di stati dei colori. |
drawable/ |
File bitmap (PNG,
Per ulteriori informazioni, consulta Risorse disegnabili. |
mipmap/ |
File disegnabili con diverse densità delle icone in Avvio applicazioni. Per ulteriori informazioni sulla gestione delle icone in Avvio applicazioni con le cartelle mipmap/, consulta la sezione Inserimento delle icone delle app nelle directory mipmap. |
layout/ |
File XML che definiscono un layout dell'interfaccia utente. Per ulteriori informazioni, consulta Risorsa di layout. |
menu/ |
File XML che definiscono i menu delle app, ad esempio un menu di opzioni, un menu contestuale o un sottomenu. Per ulteriori informazioni, vedi Risorsa del menu. |
raw/ |
File arbitrari da salvare nel formato non elaborato. Per aprire queste risorse con un Tuttavia, se hai bisogno di accedere ai nomi e alla gerarchia dei file originali, valuta la possibilità di salvare le risorse nella directory |
values/ |
File XML che contengono valori semplici, come stringhe, numeri interi e colori. Mentre i file di risorse XML in altre sottodirectory Poiché ogni risorsa è definita con il proprio elemento XML, puoi assegnare al file il nome che preferisci e inserire tipi di risorse diversi in un unico file. Tuttavia, per chiarezza, potresti voler inserire tipi di risorse univoci in file diversi. Ad esempio, ecco alcune convenzioni relative ai nomi file per le risorse che puoi creare in questa directory:
Per maggiori informazioni, consulta Risorse stringa, Risorsa stile e Altri tipi di risorse. |
xml/ |
File XML arbitrari che possono essere letti in fase di runtime chiamando Resources.getXML(). È necessario salvare qui vari file di configurazione XML, ad esempio una configurazione di ricerca.
|
font/ |
File dei caratteri con estensioni come TTF, OTF o TTC oppure file XML che includono un elemento <font-family>. Per maggiori informazioni sui caratteri come risorse, consulta la pagina relativa all'aggiunta di un carattere come risorsa XML.
|
Attenzione: non salvare mai i file delle risorse direttamente all'interno della directory res/. Causa un errore di compilazione.
Per saperne di più sui singoli tipi di risorse, consulta la panoramica dei tipi di risorse.
Le risorse salvate nelle sottodirectory definite nella tabella 1 sono le risorse predefinite. In altre parole, queste risorse definiscono il design e i contenuti predefiniti della tua app. Tuttavia, diversi tipi di dispositivi Android potrebbero richiedere tipi diversi di risorse.
Ad esempio, puoi fornire risorse di layout diverse per i dispositivi con schermi più grandi del normale, in modo da sfruttare lo spazio aggiuntivo sullo schermo. Puoi anche fornire risorse per le stringhe che traducono il testo nell'interfaccia utente in base all'impostazione della lingua del dispositivo. Per fornire queste diverse risorse per le diverse configurazioni dei dispositivi, devi fornire risorse alternative oltre alle risorse predefinite.
Fornisci risorse alternative
La maggior parte delle app fornisce risorse alternative per supportare configurazioni dispositivo specifiche. Ad esempio, includi risorse disegnabili alternative per densità di schermo diverse e risorse stringa alternative per lingue diverse. In fase di runtime, Android rileva la configurazione attuale del dispositivo e carica le risorse appropriate per la tua app.
Figura 1. Due dispositivi che utilizzano risorse di layout diverse in base alle dimensioni dello schermo.
Per specificare alternative specifiche della configurazione per un insieme di risorse:
- Crea una nuova directory in
res/denominata nel modulo<resources_name>-<qualifier>.<resources_name>è il nome della directory delle risorse predefinite corrispondenti (definiti nella tabella 1).<qualifier>è un nome che specifica una singola configurazione per la quale devono essere utilizzate queste risorse (definita nella tabella 2).
Puoi aggiungere più di un elemento
<qualifier>. Separale con un trattino.Attenzione: quando aggiungi più qualificatori, devi posizionarli nello stesso ordine in cui sono elencati nella tabella 2. Se i qualificatori sono ordinati in modo errato, le risorse vengono ignorate.
- Salva le risorse alternative appropriate in questa nuova directory. I file delle risorse devono avere esattamente lo stesso nome dei file delle risorse predefiniti.
Ad esempio, ecco alcune risorse predefinite e alternative:
res/
drawable/
icon.png
background.png
drawable-hdpi/
icon.png
background.png
Il qualificatore hdpi indica che le risorse in quella directory sono destinate ai dispositivi con uno schermo ad alta densità. Le immagini in queste directory disegnabili sono dimensionate in base a densità di schermo specifiche, ma i nomi dei file sono esattamente gli stessi. In questo modo, l'ID risorsa utilizzato per fare riferimento all'immagine icon.png o
background.png è sempre lo stesso. Android seleziona la versione di ogni risorsa che meglio corrisponde al dispositivo attuale confrontando le informazioni di configurazione del dispositivo con i qualificatori riportati nel nome della directory delle risorse.
Attenzione: quando definisci una risorsa alternativa, assicurati di
definirla anche in una configurazione predefinita. In caso contrario, l'app potrebbe riscontrare eccezioni di runtime
quando il dispositivo modifica una configurazione. Ad esempio, se aggiungi una stringa solo a
values-en e non a values, la tua app potrebbe riscontrare un'eccezione
Resource Not Found quando l'utente cambia la lingua predefinita di sistema.
La tabella 2 elenca i qualificatori di configurazione validi in ordine di precedenza. Puoi aggiungere più qualificatori a un nome di directory separando ogni qualificatore con un trattino. Se utilizzi più qualificatori per una directory di risorse, devi aggiungerli al nome della directory nell'ordine in cui sono elencati nella tabella.
Tabella 2. Nomi dei qualificatori di configurazione.
| Configurazione | Valori qualificatore | Descrizione |
|---|---|---|
| Centro clienti e MNC | Esempi:mcc310mcc208-mnc00
|
Il codice paese del dispositivo mobile (Centro clienti), facoltativamente seguito dal codice della rete mobile (MNC)
riportato nella scheda SIM del dispositivo. Ad esempio, Se il dispositivo utilizza una connessione radio (ovvero un telefono GSM), i valori MCC e MNC provengono dalla scheda SIM. Puoi anche utilizzare da solo il Centro clienti, ad esempio per includere risorse legali specifiche per paese nella tua app. Se devi specificare solo in base alla lingua, utilizza invece il qualificatore lingua, script (facoltativo) e regione (facoltativo). Se utilizzi il Centro clienti e il qualificatore MNC, fallo con cura e verifica che funzioni come previsto. Vedi anche i campi di configurazione |
| Lingua, script (facoltativo) e regione (facoltativo) | Esempi:enfren-rUSfr-rFRfr-rCAb+enb+en+USb+es+419b+zh+Hantb+sr+Latn+RS |
La lingua è definita da un codice lingua ISO 639-1 di due lettere, facoltativamente seguito
da un codice regione ISO 3166-1-alpha-2 di due lettere (preceduto dal
carattere I codici non sono sensibili alle maiuscole. Il prefisso Android 7.0 (livello API 24) ha introdotto il supporto per i tag della lingua BCP 47, che puoi utilizzare per qualificare risorse specifiche per lingua e regione. Un tag lingua è composto da una sequenza di uno o più sottotag, ciascuno dei quali perfeziona o restringe l'intervallo di lingue identificate dal tag complessivo. Per ulteriori informazioni sui tag lingua, consulta la sezione Tag per l'identificazione delle lingue. Per utilizzare un tag lingua BCP 47, concatena
Il tag della lingua può cambiare durante il ciclo di vita della tua app se gli utenti cambiano la lingua nelle impostazioni di sistema. Per informazioni su come questo può influire sulla tua app durante il runtime, consulta Gestire le modifiche alla configurazione. Per una guida completa alla localizzazione della tua app per altre lingue, consulta Localizzare app. Vedi anche il metodo |
| Direzione layout | ldrtlldltr |
La direzione del layout della tua app. Questo vale per qualsiasi risorsa, ad esempio layout, disegni o valori. Ad esempio, se vuoi fornire un layout specifico per la lingua araba e un layout generico per qualsiasi altra lingua da destra a sinistra, come il persiano o l'ebraico, utilizza directory come le seguenti:
Nota: per attivare le funzionalità di layout da destra a sinistra
per la tua app, devi impostare Aggiunta nel livello API 17. |
| Larghezza minima | sw<N>dpEsempi: sw320dpsw600dpsw720dpecc. |
La dimensione più breve dell'area dello schermo disponibile per un'app.
In particolare, il valore
Ad esempio, se il layout richiede che la dimensione più piccola dell'area dello schermo sia sempre almeno pari a 600 dp, puoi utilizzare questo qualificatore per creare le risorse di layout in una directory L'utilizzo della larghezza più piccola per determinare le dimensioni generali dello schermo è utile perché spesso è il fattore determinante nella progettazione di un layout. Una UI spesso scorre verticalmente, ma ha vincoli abbastanza duri sullo spazio minimo necessario in orizzontale. La larghezza disponibile è anche il fattore chiave per determinare se utilizzare un layout a un riquadro per gli smartphone o uno multiriquadro per i tablet. Di conseguenza, probabilmente ti interessa di più la larghezza minima possibile su ciascun dispositivo. La larghezza minima di un dispositivo tiene conto delle decorazioni dello schermo e dell'interfaccia utente di sistema. Ad esempio, se sullo schermo del dispositivo sono presenti elementi UI permanenti che tengono conto dello spazio lungo l'asse della larghezza minima, il sistema dichiara che la larghezza minima è inferiore alle dimensioni effettive dello schermo, poiché si tratta di pixel dello schermo non disponibili per la tua UI. Ecco alcuni valori che potresti usare per le dimensioni degli schermi più comuni:
Quando la tua app fornisce più directory delle risorse con valori diversi per il qualificatore Aggiunta nel livello API 13. Consulta anche l'attributo Per ulteriori informazioni sulla progettazione per schermi diversi utilizzando questo qualificatore, consulta la pagina relativa al supporto di schermi di dimensioni diverse. |
| Larghezza e altezza disponibili | w<N>dph<N>dpEsempi: w720dpw1024dph720dph1024dpecc. |
Specifica l'altezza o la larghezza minima dello schermo disponibile (in La larghezza e l'altezza disponibili sono spesso utili per determinare se utilizzare un layout multiriquadro, in quanto anche su un tablet spesso non desideri lo stesso layout multipannello per l'orientamento verticale che per quello orizzontale. Puoi quindi utilizzarli per specificare la larghezza e/o l'altezza minima necessarie per il layout, anziché utilizzare insieme i qualificatori di dimensioni e orientamento. Se la tua app fornisce più directory delle risorse con valori diversi per queste configurazioni, il sistema utilizza quella più vicina (senza superare) l'attuale larghezza dello schermo del dispositivo. Il valore più vicino a viene determinato aggiungendo le differenze tra la larghezza effettiva dello schermo e quella specificata alla differenza tra l'altezza effettiva dello schermo e l'altezza specificata, con altezze e larghezze non specificate che hanno un valore pari a 0. I valori escludono l'area occupata dagli
inserzioni delle finestre; pertanto, se il dispositivo ha
elementi UI permanenti sui bordi del display, i valori per larghezza e altezza
sono inferiori alle dimensioni reali dello schermo, anche quando l'app viene visualizzata da bordo a bordo
utilizzando
Alcune decorazioni verticali non fisse (ad esempio la barra di stato di un telefono che può essere nascosta a schermo intero) non sono prese in considerazione qui, così come le decorazioni delle finestre come la barra del titolo o la barra delle azioni, quindi le app devono essere preparate a gestire uno spazio leggermente più piccolo di quello specificato. Nota: il sistema sceglie la risorsa che corrisponde sia in larghezza che in altezza. Pertanto, una risorsa che specifica entrambi è fortemente preferita rispetto a una che specifica solo una o l'altra risorsa. Ad esempio, se lo schermo effettivo ha una larghezza di 720 dp per 1280 dp di altezza e una risorsa è qualificata con w720dp e un'altra come w700dp-h1200dp, la seconda viene scelta anche se la prima corrisponde esattamente a quanto specificato. Aggiunta nel livello API 13. Vedi anche i campi di configurazione Per ulteriori informazioni sulla progettazione per schermi diversi utilizzando questo qualificatore, consulta la pagina relativa al supporto di schermi di dimensioni diverse. |
| Dimensioni schermo |
smallnormallargexlarge
|
Nota: l'utilizzo di un qualificatore di dimensione non implica che le risorse siano solo per gli schermi di quelle dimensioni. Se non fornisci risorse alternative con qualificatori che corrispondono meglio alla configurazione attuale del dispositivo, il sistema può utilizzare le risorse che corrispondono maggiormente alla corrispondenza migliore. Attenzione: se tutte le risorse utilizzano un qualificatore
dimensione più grande della schermata corrente, il sistema
non le utilizza e l'app si arresta in modo anomalo in fase di runtime. Questo accade, ad esempio, se tutte le risorse di layout sono contrassegnate con il qualificatore Aggiunta nel livello API 4. Vedi anche il campo di configurazione Per maggiori informazioni, consulta la Panoramica della compatibilità dello schermo. |
| Aspetto schermo |
longnotlong
|
Aggiunta nel livello API 4. Si basa unicamente sulle proporzioni dello schermo (uno schermo Vedi anche il campo di configurazione |
| Schermo rotondo |
roundnotround
|
Aggiunta nel livello API 23. Vedi anche il metodo di configurazione |
| Ampia gamma di colori |
widecgnowidecg
|
Aggiunta nel livello API 26. Vedi anche il metodo di configurazione |
| Tecnologia HDR (High Dynamic Range) |
highdrlowdr
|
Aggiunta nel livello API 26. Vedi anche il metodo di configurazione |
| Orientamento dello schermo |
portland
|
Questo può cambiare durante il ciclo di vita dell'app se l'utente ruota lo schermo. Per informazioni su come questo influisce sulla tua app durante il runtime, consulta Gestire le modifiche alla configurazione. Vedi anche il campo di configurazione |
| Modalità UI |
cardesktelevisionappliancewatchvrheadset
|
Aggiunta nel livello API 8; televisione aggiunta nell'API 13; smartwatch aggiunto nell'API 20. Per informazioni su come l'app può rispondere quando il dispositivo viene inserito o rimosso da un dock, leggi l'articolo Determinare e monitorare lo stato e il tipo di dock. Questo può cambiare durante il ciclo di vita dell'app se l'utente posiziona il dispositivo in un dock. Puoi abilitare o disabilitare alcune di queste modalità utilizzando
|
| Modalità notturna |
nightnotnight
|
Aggiunta nel livello API 8. Questo può cambiare durante il ciclo di vita dell'app se la modalità notturna viene lasciata in modalità automatica (impostazione predefinita), nel qual caso cambia in base all'ora del giorno. Puoi attivare o disattivare questa modalità utilizzando |
| Densità pixel dello schermo (dpi) |
ldpimdpihdpixhdpixxhdpixxxhdpinodpitvdpianydpinnndpi
|
Il rapporto di scalabilità tra le sei densità primarie è 3:4:6:8:12:16 (ignorando la densità di tvdpi). Quindi, una bitmap 9 x 9 in ldpi è 12 x 12 in mdpi, 18 x 18 in hdpi, 24 x 24 in xhdpi e così via. Nota: l'uso di un qualificatore di densità non implica che le risorse siano solo per gli schermi con quella densità. Se non fornisci risorse alternative con qualificatori che corrispondono meglio alla configurazione attuale del dispositivo, il sistema utilizza le risorse che corrispondono maggiormente alla corrispondenza migliore. Per ulteriori informazioni su come gestire le diverse densità dello schermo e su come Android potrebbe scalare le bitmap per adattarle alla densità attuale, consulta la Panoramica della compatibilità dello schermo. |
| Tipo di touchscreen |
notouchfinger
|
Vedi anche il campo di configurazione |
| Disponibilità della tastiera |
keysexposedkeyshiddenkeyssoft
|
Se fornisci le risorse Questo può cambiare durante il ciclo di vita dell'app se l'utente apre una tastiera hardware. Per informazioni su come questo influisce sulla tua app durante il runtime, consulta Gestire le modifiche alla configurazione. Vedi anche i campi di configurazione |
| Metodo di immissione testo principale |
nokeysqwerty12key
|
Vedi anche il campo di configurazione |
| Disponibilità dei tasti di navigazione |
navexposednavhidden
|
Questo può cambiare durante il ciclo di vita dell'app se l'utente rivela i tasti di navigazione. Per informazioni su come questo influisce sulla tua app durante il runtime, consulta Gestire le modifiche alla configurazione. Vedi anche il campo di configurazione |
| Metodo principale di navigazione non touch |
nonavdpadtrackballwheel
|
Vedi anche il campo di configurazione |
| Versione piattaforma (livello API) | Esempi:v3v4v7ecc. |
Il livello API supportato dal dispositivo. Ad esempio, |
Nota: non tutte le versioni di Android supportano tutti i qualificatori. Se utilizzi un nuovo qualificatore, questo viene aggiunto
implicitamente alla versione della piattaforma, in modo che i dispositivi meno recenti possano ignorarlo. Ad esempio, l'uso di un qualificatore w600dp include automaticamente il qualificatore v13 perché il qualificatore della larghezza disponibile era nuovo nel livello API 13. Per evitare problemi, includi sempre un set di risorse predefinite (un insieme di risorse senza qualificatori). Per ulteriori informazioni, consulta la sezione Fornire la migliore compatibilità dei dispositivi con le risorse.
Regole per i nomi dei qualificatori
Di seguito sono riportate alcune regole sull'utilizzo dei nomi dei qualificatori di configurazione:
- Puoi specificare più qualificatori per un singolo insieme di risorse, separati da trattini. Ad
esempio,
drawable-en-rUS-landsi applica ai dispositivi in inglese americano con orientamento orizzontale. - I qualificatori devono essere nell'ordine indicato nella tabella 2.
- Sbagliato:
drawable-hdpi-port/ - Risposta corretta:
drawable-port-hdpi/
- Sbagliato:
- Le directory delle risorse alternative non possono essere nidificate. Ad esempio, non puoi avere
res/drawable/drawable-en/. - I valori non fanno distinzione tra maiuscole e minuscole. Il compilatore delle risorse converte i nomi delle directory in minuscoli prima dell'elaborazione per evitare problemi con i file system senza distinzione tra maiuscole e minuscole. L'uso delle lettere maiuscole nei nomi contribuisce solo a migliorare la leggibilità.
- È supportato un solo valore per ogni tipo di qualificatore. Ad esempio, se vuoi utilizzare gli stessi file disegnabili per Spagna e Francia, non puoi avere una directory denominata
drawable-es-fr/. Sono invece necessarie due directory delle risorse, comedrawable-es/edrawable-fr/, che contengono i file appropriati. Tuttavia, non è necessario duplicare effettivamente i file in entrambe le posizioni. Puoi invece creare un alias per una risorsa, come descritto nella sezione Crea risorse alias.
Dopo aver salvato le risorse alternative in directory denominate con questi qualificatori, Android le applica automaticamente nella tua app in base alla configurazione attuale del dispositivo. Ogni volta che viene richiesta una risorsa, Android controlla le directory delle risorse alternative contenenti il file della risorsa richiesto, quindi trova la risorsa con la migliore corrispondenza.
Se non esistono risorse alternative che corrispondono a una determinata configurazione del dispositivo, Android utilizza le risorse predefinite corrispondenti, ovvero l'insieme di risorse per un particolare tipo di risorsa che non include un qualificatore di configurazione.
crea risorse alias
Se hai una risorsa che vuoi utilizzare per più configurazioni dei dispositivi, ma non vuoi specificarla come predefinita, non è necessario inserire la stessa risorsa in più directory di risorse alternative. Puoi invece creare una risorsa alternativa che funga da alias per una risorsa salvata nella directory delle risorse predefinita.
Nota: non tutte le risorse offrono un meccanismo mediante il quale
puoi creare un alias per un'altra risorsa. In particolare, animazioni, menu, risorse non elaborate e altre risorse non specificate nella directory xml/ non offrono questa funzionalità.
Ad esempio, immagina di avere l'icona di un'app, icon.png, e di aver bisogno di una versione univoca per
le diverse impostazioni internazionali. Tuttavia, due lingue, inglese-canadese e franco-canadese, devono
utilizzare la stessa versione. Non è necessario copiare la stessa immagine nella
directory delle risorse sia per inglese-canadese che franco-canadese.
Puoi invece salvare l'immagine utilizzata per entrambi utilizzando un nome diverso da
icon.png, come icon_ca.png, e inserirla
nella directory res/drawable/ predefinita. Quindi crea un file icon.xml in res/drawable-en-rCA/ e res/drawable-fr-rCA/ che faccia riferimento alla risorsa icon_ca.png
utilizzando l'elemento <bitmap>. che permette di archiviare una sola versione
del file PNG e due piccoli file XML. Per maggiori dettagli, consulta gli esempi nelle sezioni seguenti.
Disegnabile
Per creare un alias per un disegno esistente, utilizza l'elemento <drawable>:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<drawable name="icon">@drawable/icon_ca</drawable>
</resources>
Se salvi questo file come icon.xml in una directory di risorse alternativa, come res/values-en-rCA/, questo file viene compilato in una risorsa a cui puoi fare riferimento come R.drawable.icon, ma in realtà è un alias per la risorsa R.drawable.icon_ca, che viene salvata in res/drawable/.
Layout
Per creare un alias a un layout esistente, utilizza l'elemento <include>, aggregato in un <merge>:
<?xml version="1.0" encoding="utf-8"?>
<merge>
<include layout="@layout/main_ltr"/>
</merge>
Se salvi questo file come main.xml, verrà compilato in una risorsa che puoi fare riferimento come R.layout.main, ma in realtà è un alias per la risorsa R.layout.main_ltr.
Stringhe e altri valori semplici
Per creare un alias a una stringa esistente, utilizza l'ID risorsa della stringa desiderata come valore per la nuova stringa:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="hello">Hello</string>
<string name="hi">@string/hello</string>
</resources>
La risorsa R.string.hi è ora un alias di R.string.hello.
Altri valori semplici funzionano allo stesso modo, ad esempio i colori:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<color name="red">#f00</color>
<color name="highlight">@color/red</color>
</resources>
Accedi alle risorse dell'app
Dopo aver fornito una risorsa nell'applicazione, puoi applicarla facendo riferimento al suo ID risorsa. Tutti gli ID risorsa sono definiti nella classe R del progetto, che
lo strumento aapt genera automaticamente.
Quando l'applicazione è compilata, aapt genera la classe R, che contiene gli ID risorsa per tutte le risorse nella tua directory res/. Per ogni tipo di risorsa, esiste una sottoclasse R, ad esempio R.drawable per tutte le risorse disegnabili. Per ogni risorsa di quel tipo è presente un
numero intero statico, ad esempio R.drawable.icon. Questo numero intero è l'ID risorsa che puoi
utilizzare per recuperare la risorsa.
Anche se gli ID risorsa sono specificati nella classe R, non è necessario cercare in questa classe per trovare un ID risorsa. Un ID risorsa è sempre composto da:
- Il tipo di risorsa: ogni risorsa è raggruppata in un "tipo", ad esempio
string,drawableelayout. Per saperne di più sui diversi tipi, consulta Panoramica dei tipi di risorse. - Il nome della risorsa, ovvero il nome del file che esclude l'estensione o il valore nell'attributo XML
android:name, se la risorsa è un valore semplice, ad esempio una stringa.
Puoi accedere a una risorsa in due modi:
- Nel codice: utilizzando un numero intero statico di una sottoclasse della tua
classe
R, ad esempio:R.string.hello
stringè il tipo di risorsa ehelloè il nome della risorsa. Molte API Android possono accedere alle tue risorse se fornisci un ID risorsa in questo formato. Per ulteriori informazioni, consulta la sezione Accedere alle risorse nel codice. - In XML: utilizza una sintassi XML speciale che corrisponde
all'ID risorsa definito nella classe
R, ad esempio:@string/hello
stringè il tipo di risorsa ehelloè il nome della risorsa. Puoi utilizzare questa sintassi in una risorsa XML in qualsiasi punto in cui è previsto un valore in una risorsa. Per ulteriori informazioni, consulta la sezione Accedere alle risorse da XML.
Accedi alle risorse nel codice
Puoi utilizzare una risorsa nel codice passando l'ID risorsa come parametro del metodo. Ad
esempio, puoi impostare un ImageView per utilizzare la
risorsa res/drawable/myimage.png utilizzando setImageResource():
Kotlin
val imageView = findViewById(R.id.myimageview) as ImageView imageView.setImageResource(R.drawable.myimage)
Java
ImageView imageView = (ImageView) findViewById(R.id.myimageview); imageView.setImageResource(R.drawable.myimage);
Puoi anche recuperare le singole risorse utilizzando i metodi in Resources, di cui puoi ottenere un'istanza
con getResources().
Sintassi
Questa è la sintassi per fare riferimento a una risorsa nel codice:
[<package_name>.]R.<resource_type>.<resource_name>
<package_name>è il nome del pacchetto in cui si trova la risorsa (non obbligatorio quando si fa riferimento a risorse del proprio pacchetto).<resource_type>è la sottoclasseRper il tipo di risorsa.<resource_name>è il nome del file della risorsa senza l'estensione o il valore dell'attributoandroid:namenell'elemento XML, per i valori semplici.
Per saperne di più su ogni tipo di risorsa e su come farvi riferimento, vedi Panoramica dei tipi di risorse.
casi d'uso
Esistono molti metodi che accettano un parametro ID risorsa e puoi recuperare le risorse usando i metodi in Resources. Puoi
ottenere un'istanza di Resources utilizzando Context.getResources().
Ecco alcuni esempi di accesso alle risorse nel codice:
Kotlin
// Load a background for the current screen from a drawable resource. window.setBackgroundDrawableResource(R.drawable.my_background_image) // Set the Activity title by getting a string from the Resources object, because // this method requires a CharSequence rather than a resource ID. window.setTitle(resources.getText(R.string.main_title)) // Load a custom layout for the current screen. setContentView(R.layout.main_screen) // Set a slide in animation by getting an Animation from the Resources object. flipper.setInAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_in)) // Set the text on a TextView object using a resource ID. val msgTextView = findViewById(R.id.msg) as TextView msgTextView.setText(R.string.hello_message)
Java
// Load a background for the current screen from a drawable resource. getWindow().setBackgroundDrawableResource(R.drawable.my_background_image) ; // Set the Activity title by getting a string from the Resources object, because // this method requires a CharSequence rather than a resource ID. getWindow().setTitle(getResources().getText(R.string.main_title)); // Load a custom layout for the current screen. setContentView(R.layout.main_screen); // Set a slide in animation by getting an Animation from the Resources object. flipper.setInAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_in)); // Set the text on a TextView object using a resource ID. TextView msgTextView = (TextView) findViewById(R.id.msg); msgTextView.setText(R.string.hello_message);
Attenzione:non modificare manualmente il file R.java. Viene generato dallo strumento aapt quando il progetto è compilato. Le eventuali modifiche verranno sostituite alla successiva compilazione.
Accedi alle risorse da XML
Puoi definire i valori per alcuni attributi ed elementi XML utilizzando un riferimento a una risorsa esistente. Spesso questa operazione è effettuata durante la creazione di file di layout, per fornire stringhe e immagini per i widget.
Ad esempio, se aggiungi un elemento Button al layout, utilizza
una risorsa stringa per il testo del pulsante:
<Button
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text="@string/submit" />
Sintassi
Ecco la sintassi per fare riferimento a una risorsa in una risorsa XML:
@[<package_name>:]<resource_type>/<resource_name>
<package_name>è il nome del pacchetto in cui si trova la risorsa (non obbligatorio quando si fa riferimento a risorse dello stesso pacchetto).<resource_type>è la sottoclasseRper il tipo di risorsa.<resource_name>è il nome del file della risorsa senza l'estensione o il valore dell'attributoandroid:namenell'elemento XML, per i valori semplici.
Per saperne di più su ogni tipo di risorsa e su come farvi riferimento, vedi Panoramica dei tipi di risorse.
casi d'uso
In alcuni casi devi utilizzare una risorsa per un valore in XML, ad esempio per applicare un'immagine disegnabile a un widget, ma puoi utilizzare una risorsa anche in XML in qualsiasi punto che accetti un valore semplice. Ad esempio, se disponi del seguente file di risorse che include una risorsa di colore e una risorsa stringa:
<?xml version="1.0" encoding="utf-8"?> <resources> <color name="opaque_red">#f00</color> <string name="hello">Hello!</string> </resources>
Puoi utilizzare queste risorse nel seguente file di layout per impostare il colore del testo e la stringa di testo:
<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:textColor="@color/opaque_red"
android:text="@string/hello" />
In questo caso, non è necessario specificare il nome del pacchetto nel riferimento della risorsa, poiché le risorse provengono dal tuo pacchetto. Per fare riferimento a una risorsa di sistema, devi includere il nome del pacchetto, come mostrato nell'esempio seguente:
<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:textColor="@android:color/secondary_text_dark"
android:text="@string/hello" />
Nota: usa sempre risorse per le stringhe, in modo che l'applicazione possa essere localizzata in altre lingue. Per informazioni sulla creazione di risorse alternative (ad esempio stringhe localizzate), consulta Fornire risorse alternative. Per una guida completa alla localizzazione della tua applicazione per altre lingue, consulta Localizzare l'app.
Puoi anche utilizzare le risorse nel file XML per creare alias. Ad esempio, puoi creare una risorsa disegnabile che funga da alias per un'altra risorsa disegnabile:
<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android"
android:src="@drawable/other_drawable" />
Questo sembra ridondante, ma può essere molto utile quando si utilizza una risorsa alternativa. Per ulteriori informazioni, consulta la sezione sulla creazione di risorse alias.
Attributi degli stili di riferimento
Una risorsa attributo di stile consente di fare riferimento al valore di un attributo nel tema applicato. Il riferimento a un attributo di stile ti consente di personalizzare l'aspetto degli elementi dell'interfaccia utente definendoli in modo che corrispondano alle varianti standard fornite dal tema corrente, anziché fornire un valore impostato come hardcoded. Il riferimento a un attributo di stile indica in pratica: "Utilizza lo stile definito da questo attributo nel tema corrente".
Per fare riferimento a un attributo di stile, la sintassi del nome è quasi identica al normale formato delle risorse, ma invece del simbolo "at" (@), utilizza un punto interrogativo (?). La parte del tipo di risorsa è facoltativa. La sintassi di riferimento è la seguente:
?[<package_name>:][<resource_type>/]<resource_name>
Ad esempio, ecco come puoi fare riferimento a un attributo per impostare il colore del testo in modo che corrisponda al colore del testo secondario del tema del sistema:
<EditText id="text"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:textColor="?android:textColorSecondary"
android:text="@string/hello_world" />
In questo caso, l'attributo android:textColor specifica il nome di un attributo di stile nel tema corrente. Android ora utilizza il valore applicato all'attributo stile android:textColorSecondary come valore per android:textColor in questo widget. Poiché lo strumento delle risorse di sistema sa che in questo contesto è prevista una risorsa attributo, non è necessario indicare esplicitamente il tipo, ovvero ?android:attr/textColorSecondary. Puoi escludere il tipo attr.
Accedi ai file originali
Sebbene non sia comune, potrebbe essere necessario accedere ai file e alle directory originali. In questo caso, il salvataggio dei file in res/ non funzionerà, perché l'unico modo per leggere una risorsa da res/ è tramite l'ID risorsa. Puoi invece salvare le risorse nella directory assets/.
Ai file salvati nella directory assets/ non viene assegnato un ID risorsa, quindi non puoi farvi riferimento tramite la classe R o dalle risorse XML. Puoi invece eseguire query sui file nella directory assets/ come un normale file system e leggere i dati non elaborati utilizzando AssetManager.
Tuttavia, se tutto ciò di cui hai bisogno è la capacità di leggere i dati non elaborati (ad esempio un file video o audio), salva il file nella directory res/raw/ e leggi un flusso di byte utilizzando openRawResource().
Accedi alle risorse della piattaforma
Android contiene una serie di risorse standard, come stili, temi e layout. Per accedere a queste risorse, qualifica il riferimento delle risorse con il nome del pacchetto android. Ad esempio, Android fornisce una risorsa di layout che puoi utilizzare per
gli elementi dell'elenco in un ListAdapter:
Kotlin
listAdapter = ArrayAdapter(this, android.R.layout.simple_list_item_1, myarray)
Java
setListAdapter(new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, myarray));
In questo esempio, simple_list_item_1 è una risorsa di layout definita dalla piattaforma per gli elementi in ListView. Puoi usarla anziché creare un layout
personalizzato per gli elementi dell'elenco.
Offri la migliore compatibilità dei dispositivi con le risorse
Affinché la tua app supporti più configurazioni di dispositivi, è molto importante fornire sempre risorse predefinite per ogni tipo di risorsa utilizzata dall'app.
Ad esempio, se la tua app supporta più lingue, includi sempre una directory values/ (in cui vengono salvate le stringhe) senza un qualificatore di lingua e regione. Se invece inserisci tutti i file delle stringhe in directory che hanno un qualificatore di lingua e regione, l'app si arresta in modo anomalo quando viene eseguita su un dispositivo impostato su una lingua non supportata dalle stringhe.
Se fornisci risorse values/ predefinite, la tua app funziona correttamente, anche se l'utente non comprende la lingua utilizzata. È meglio che arrestarsi in modo anomalo.
Analogamente, se fornisci risorse di layout diverse in base all'orientamento dello schermo, scegli un orientamento come predefinito. Ad esempio, invece di fornire risorse di layout in layout-land/ per l'orientamento orizzontale e in layout-port/ per l'orientamento verticale, lasciane una come impostazione predefinita, ad esempio layout/ per l'orientamento orizzontale e layout-port/ per l'orientamento verticale.
Fornire risorse predefinite è importante non solo perché la tua app potrebbe essere eseguita su una configurazione che non avevi previsto, ma anche perché a volte le nuove versioni di Android aggiungono qualificatori di configurazione non supportati dalle versioni precedenti. Se utilizzi un nuovo qualificatore delle risorse, ma mantieni la compatibilità del codice con le versioni precedenti di Android, quando una versione precedente di Android esegue la tua app, si arresta in modo anomalo se non fornisci risorse predefinite, perché non è possibile usare le risorse denominate con il nuovo qualificatore.
Ad esempio, se minSdkVersion è impostato su 4 e tutte le risorse disegnabili vengono considerate idonee utilizzando la modalità notturna (night o notnight, che sono state aggiunte nel livello API 8), un dispositivo di livello API 4 non potrà accedere alle risorse disegnabili e agli arresti anomali. In questo caso, probabilmente vuoi notnight come risorse predefinite, quindi escludi il qualificatore e inserisci le risorse disegnabili in drawable/ o drawable-night/.
In breve, per offrire la migliore compatibilità tra dispositivi, fornisci sempre le risorse predefinite per le risorse necessarie all'applicazione per funzionare correttamente. Poi crea risorse alternative per configurazioni di dispositivi specifiche utilizzando i qualificatori di configurazione.
Esiste un'eccezione a questa regola: se il valore minSdkVersion dell'app è pari o superiore a 4, non hai bisogno di risorse disegnabili predefinite quando fornisci risorse di cui può essere utilizzato alternativa con il qualificatore di complessità dello schermo. Anche in assenza di risorse disegnabili predefinite, Android può trovare la migliore corrispondenza tra le densità dello schermo alternative e scalare le bitmap in base alle esigenze. Tuttavia, per un'esperienza ottimale su tutti i tipi di dispositivi,
fornisci elementi disegnabili alternativi per tutti e tre i tipi di densità.
In che modo Android trova la risorsa migliore
Quando richiedi una risorsa che fornisci alternative, Android seleziona la risorsa alternativa da utilizzare per il runtime, in base alla configurazione attuale del dispositivo. Per dimostrare in che modo Android seleziona una risorsa alternativa, supponiamo che le seguenti directory disegnabili contengano versioni diverse delle stesse immagini:
drawable/ drawable-en/ drawable-fr-rCA/ drawable-en-port/ drawable-en-notouch-12key/ drawable-port-ldpi/ drawable-port-notouch-12key/
Supponiamo che la configurazione del dispositivo sia la seguente:
Impostazioni internazionali = en-GB
Orientamento schermo = port
Densità pixel schermo = hdpi
Tipo di touchscreen = notouch
Metodo di immissione testo principale = 12key
Confrontando la configurazione del dispositivo con le risorse alternative disponibili, Android seleziona i file disegnati da drawable-en-port.
Il sistema decide quali risorse utilizzare con la seguente logica:
Figura 2. Diagramma di flusso che mostra come Android trova la risorsa migliore.
- Elimina i file delle risorse che contraddicono la configurazione del dispositivo.
La directory
drawable-fr-rCA/viene eliminata perché contraddice le impostazioni internazionalien-GB.drawable/ drawable-en/
drawable-fr-rCA/drawable-en-port/ drawable-en-notouch-12key/ drawable-port-ldpi/ drawable-port-notouch-12key/Eccezione: la densità dei pixel dello schermo è l'unico qualificatore che non viene eliminato per una contraddizione. Anche se la densità dello schermo del dispositivo è hdpi,
drawable-port-ldpi/non viene eliminato perché ogni densità dello schermo viene considerata corrispondente in questo momento. Per informazioni, vedi Panoramica della compatibilità dello schermo. - Trova il qualificatore successivo con la priorità più alta nell'elenco (tabella 2). (Inizia con il Centro clienti.)
- Alcune delle directory delle risorse includono questo qualificatore?
- In caso contrario, torna al secondo passaggio e controlla il qualificatore successivo. In questo esempio, la risposta è "no" finché non viene raggiunto il qualificatore lingua.
- In caso affermativo, vai al passaggio quattro.
- Elimina le directory delle risorse che non includono questo qualificatore. In questo esempio, il sistema elimina tutte le directory che non includono un qualificatore di lingua:
drawable/drawable-en/ drawable-en-port/ drawable-en-notouch-12key/drawable-port-ldpi/drawable-port-notouch-12key/Eccezione: se il qualificatore in questione è la densità dei pixel dello schermo, Android seleziona l'opzione che corrisponde maggiormente alla densità dello schermo del dispositivo. In generale, Android preferisce ridurre un'immagine originale più grande per aumentare lo scale up di un'immagine originale più piccola. Per ulteriori informazioni, consulta la panoramica sulla compatibilità dello schermo.
- Ripeti i passaggi due, tre e quattro finché non rimane una sola directory. In questo esempio, l'orientamento dello schermo è il qualificatore successivo per il quale esistono corrispondenze.
Di conseguenza, le risorse che non specificano un orientamento dello schermo vengono eliminate:
drawable-en/drawable-en-port/drawable-en-notouch-12key/La directory rimanente è
drawable-en-port.
Anche se questa procedura viene eseguita per ogni risorsa richiesta, il sistema ne ottimizza alcuni aspetti. Una di queste ottimizzazioni è che, una volta nota la configurazione del dispositivo, potrebbe eliminare risorse alternative che non possono mai corrispondere. Ad esempio, se la lingua di configurazione è l'inglese, qualsiasi directory delle risorse con un qualificatore di lingua impostato su qualcosa di diverso dall'inglese non verrà mai inclusa nel pool di risorse controllate (anche se viene comunque inclusa una directory delle risorse senza il qualificatore lingua).
Quando seleziona le risorse in base ai qualificatori delle dimensioni dello schermo, il sistema utilizza risorse progettate per uno schermo di dimensioni inferiori a quella corrente se non esistono risorse più corrispondenti. Ad esempio, uno schermo di grandi dimensioni utilizza risorse di schermo di dimensioni normali, se necessario.
Tuttavia, se
le uniche risorse disponibili sono più grandi della schermata corrente, il sistema
non le utilizza e la tua app si arresta in modo anomalo se non ci sono altre risorse corrispondenti alla configurazione
del dispositivo. Questo accade, ad esempio, se tutte le risorse di layout sono contrassegnate con il qualificatore xlarge,
ma il dispositivo ha uno schermo di dimensioni normali.
Nota: la precedenza del qualificatore (nella tabella 2) è più importante del numero di qualificatori che corrispondono esattamente al dispositivo. Nell'esempio precedente, al quarto passaggio
l'ultima scelta nell'elenco include tre qualificatori che corrispondono esattamente al dispositivo (orientamento,
tipo di touchscreen e metodo di immissione), mentre drawable-en ha un solo parametro corrispondente
(lingua). Tuttavia, la lingua ha una precedenza maggiore rispetto a questi altri qualificatori, pertanto il criterio drawable-port-notouch-12key viene eliminato.