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.
Esternalizza sempre le 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 speciali. In fase di runtime, Android utilizza la risorsa appropriata in base alla configurazione attuale. Ad esempio, puoi fornire un layout dell'interfaccia utente diverso a seconda delle dimensioni dello schermo o di 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 progetto Android. Spiega inoltre come fornire risorse alternative per configurazioni dispositivo specifiche e accedervi dal codice dell'app o da altri file XML.
Tipi di risorse di gruppo
Inserisci ogni tipo di risorsa in una sottodirectory specifica della directory res/
del tuo 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 app 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 Inserire le icone delle app nelle directory mipmap.
Directory | Tipo di risorsa |
---|---|
animator/ |
I file XML che definiscono le animazioni delle proprietà. |
anim/ |
File XML che definiscono Tween
animazioni. In questa directory è possibile salvare anche le animazioni delle proprietà, ma
per le animazioni delle proprietà è preferibile utilizzare la directory animator/ , in modo da distinguere i due
tipi. |
color/ |
File XML che definiscono un elenco di stati di colori. Per ulteriori informazioni, consulta la sezione Risorsa per l'elenco degli stati dei colori. |
drawable/ |
File bitmap (PNG,
Per saperne di più, vedi Risorse disegnabili. |
mipmap/ |
File disegnabili per diverse densità delle icone in Avvio applicazioni. Per maggiori informazioni sulla gestione
delle icone in Avvio applicazioni con le cartelle mipmap/ , consulta
Inserire le icone delle app nelle
directory mipmap. |
layout/ |
File XML che definiscono un layout dell'interfaccia utente. Per ulteriori informazioni, consulta la sezione Risorsa di layout. |
menu/ |
File XML che definiscono i menu delle app, ad esempio un menu opzioni, un menu contestuale o un sottomenu. Per ulteriori informazioni, vedi Risorsa del menu. |
raw/ |
i file arbitrari da salvare nel formato non elaborato. Per aprire queste risorse con un elemento 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 un proprio elemento XML, puoi assegnare al file il nome che preferisci e inserire diversi tipi di risorse in un unico file. Tuttavia, per maggiore 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 per le stringhe, Risorse per lo stile e Altri tipi di risorse. |
xml/ |
File XML arbitrari che possono essere letti in fase di runtime chiamando Resources.getXML() . Qui devono essere salvati 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 Aggiungere un carattere come risorsa XML.
|
Attenzione: non salvare mai i file delle risorse direttamente all'interno della directory res/
. Causa un errore del compilatore.
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 tue risorse predefinite. In altre parole, queste risorse definiscono il design e i contenuti predefiniti della tua app. Tuttavia, diversi tipi di dispositivi basati su Android potrebbero richiedere tipi di risorse differenti.
Ad esempio, puoi fornire risorse di layout diverse per i dispositivi che hanno 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 a quelle predefinite.
Fornire risorse alternative
La maggior parte delle app fornisce risorse alternative per supportare configurazioni di dispositivi specifiche. Ad esempio, puoi includere 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.
Per specificare alternative specifiche per la 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 (definite nella tabella 1).<qualifier>
è un nome che specifica una singola configurazione per cui devono essere utilizzate queste risorse (definita nella tabella 2).
Puoi aggiungere più di una
<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 non sono ordinati correttamente, le risorse vengono ignorate.
- Salva le risorse alternative appropriate in questa nuova directory. I file delle risorse devono avere 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 nella directory sono destinate ai dispositivi con uno schermo ad alta densità. Le immagini in queste directory disegnabili hanno dimensioni in base a densità di schermo specifiche, ma i nomi dei file sono esattamente gli stessi. In questo modo, l'ID risorsa che utilizzi 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 indicati 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 cambia 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 di sistema predefinita.
Nella tabella 2 sono elencati 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.
Configurazione | Valori qualificatori | Descrizione |
---|---|---|
Centro clienti e MNC | Esempi:mcc310
mcc208-mnc00
|
Il codice paese mobile (Centro clienti), seguito facoltativamente dal codice di rete mobile (MNC) della 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 solo il Centro clienti, ad esempio per includere risorse legali specifiche per paese nella tua app. Se devi specificare solo la 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. Consulta anche i campi di configurazione |
Lingua, script (facoltativo) e regione (facoltativo) | Esempi:en fr en-rUS fr-rFR fr-rCA b+en b+en+US b+es+419 b+zh+Hant b+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 le risorse specifiche per lingua e regione. Un tag di lingua è composto da una sequenza di uno o più sottotag, ognuno dei quali perfeziona o restringe l'intervallo di lingue identificate dal tag complessivo. Per ulteriori informazioni sui tag della 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 di app per altre lingue, consulta l'articolo Localizzare app. Vedi anche il metodo |
Direzione layout | ldrtl ldltr |
La direzione del layout della tua app. Questo vale per qualsiasi risorsa, ad esempio layout, disegnabili o valori. Ad esempio, se vuoi fornire un layout specifico per la lingua araba e uno generico per qualsiasi altra lingua da destra a sinistra, come il persiano o l'ebraico, devi utilizzare directory come la seguente:
Nota: per attivare le funzionalità di layout da destra a sinistra
nella tua app, devi impostare Aggiunta nel livello API 17. |
Larghezza minima | sw<N>dp Esempi: sw320dp sw600dp sw720dp ecc. |
La dimensione più corta dell'area dello schermo disponibile per un'app.
In particolare, il valore
Ad esempio, se il layout richiede che la dimensione minima dell'area dello schermo sia di almeno 600 dp in ogni momento, puoi utilizzare questo qualificatore per creare le risorse di layout in una directory È utile utilizzare una larghezza minima per determinare le dimensioni generali dello schermo, poiché la larghezza è spesso il fattore determinante nella progettazione di un layout. Spesso l'interfaccia utente scorre verticalmente, ma prevede vincoli abbastanza rigidi per quanto riguarda lo spazio minimo necessario in orizzontale. La larghezza disponibile è inoltre il fattore chiave per determinare se utilizzare un layout con un riquadro per i telefoni o uno con più riquadri per i tablet. Di conseguenza, probabilmente ti interessa di più la larghezza minima possibile su ciascun dispositivo. La larghezza minima di un dispositivo prende in considerazione le decorazioni dello schermo e l'interfaccia utente di sistema. Ad esempio, se sullo schermo del dispositivo sono presenti elementi UI permanenti che tengono conto dello spazio lungo l'asse di 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. Alcuni valori che potresti utilizzare qui per le dimensioni comuni degli schermi:
Quando la tua app fornisce più directory di risorse con valori diversi per il qualificatore Aggiunta nel livello API 13. Consulta anche l'attributo Per ulteriori informazioni sulla progettazione per diversi schermi utilizzando questo qualificatore, consulta la pagina Supporto di diverse dimensioni dello schermo. |
Larghezza e altezza disponibili | w<N>dp h<N>dp Esempi: w720dp w1024dp h720dp h1024dp ecc. |
Specifica la larghezza o l'altezza minima dello schermo (in unità 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 multiriquadro per l'orientamento verticale che per l'orientamento orizzontale. Pertanto, puoi utilizzarli per specificare la larghezza e/o l'altezza minime necessarie per il layout, anziché utilizzare insieme i qualificatori di orientamento e dimensioni dello schermo. Quando la tua app fornisce più directory di risorse con valori diversi per queste configurazioni, il sistema utilizza quella più vicina (senza superare) la larghezza dello schermo attuale del dispositivo. Il valore Più vicino a viene determinato sommando le differenze tra la larghezza effettiva dello schermo e la larghezza specificata alla differenza tra l'altezza effettiva dello schermo e quella specificata. Le altezze e le larghezze non specificate hanno un valore pari a 0. I valori escludono l'area occupata da inset di 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 dello schermo verticale che non sono fisse (ad esempio la barra di stato di un telefono che può essere nascosta a schermo intero) non vengono prese in considerazione qui, né le decorazioni delle finestre come la barra del titolo o la barra delle azioni, pertanto le app devono essere preparate a gestire uno spazio leggermente più piccolo di quello specificato. Nota: il sistema sceglie la risorsa corrispondente sia in larghezza che in altezza. Pertanto, una risorsa che specifica entrambi è vivamente preferita rispetto a una che specifica solo l'una o l'altra risorsa. Ad esempio, se lo schermo effettivo è largo 720 dp per 1280 dp alto e una risorsa è qualificata con w720dp e un'altra è w700dp-h1200dp, la seconda viene scelta anche se la prima è una corrispondenza esatta per ciò che specifica. Aggiunta nel livello API 13. Vedi anche i campi di configurazione Per ulteriori informazioni sulla progettazione per diversi schermi utilizzando questo qualificatore, consulta la pagina Supporto di diverse dimensioni dello schermo. |
Dimensioni schermo |
small normal large xlarge
|
Nota: l'utilizzo di un qualificatore 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 di 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 a tutte le risorse di layout viene assegnato il qualificatore Aggiunta nel livello API 4. Vedi anche il campo di configurazione Per maggiori informazioni, consulta la panoramica sulla compatibilità dello schermo. |
Aspetto dello schermo |
long notlong
|
Aggiunta nel livello API 4. Questo valore si basa esclusivamente sulle proporzioni dello schermo (uno schermo Vedi anche il campo di configurazione |
Schermo rotondo |
round notround
|
Aggiunta nel livello API 23. Vedi anche il metodo di configurazione |
Ampia gamma di colori |
widecg nowidecg
|
Aggiunta nel livello API 26. Vedi anche il metodo di configurazione |
Tecnologia HDR (High Dynamic Range) |
highdr lowdr
|
Aggiunta nel livello API 26. Vedi anche il metodo di configurazione |
Orientamento dello schermo |
port land
|
Questo può cambiare durante il ciclo di vita della tua app se l'utente ruota lo schermo. Per informazioni su come ciò influisce sulla tua app durante il runtime, consulta Gestire le modifiche alla configurazione. Vedi anche il campo di configurazione |
Modalità UI |
car desk television appliance watch vrheadset
|
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 in un dock o rimosso da un dock, consulta Determinare e monitorare lo stato e il tipo di dock. Questo può cambiare durante il ciclo di vita della tua app se l'utente posiziona il dispositivo in un dock. Puoi abilitare o disabilitare alcune di queste modalità utilizzando
|
Modalità notturna |
night notnight
|
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 abilitare
o disabilitare questa modalità utilizzando |
Densità pixel dello schermo (dpi) |
ldpi mdpi hdpi xhdpi xxhdpi xxxhdpi nodpi tvdpi anydpi nnndpi
|
Esiste un rapporto di ridimensionamento 3:4:6:8:12:16 tra le sei densità primarie (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'utilizzo di un qualificatore di densità non implica che le risorse siano solo per gli schermi con questa 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 ridimensionare le bitmap per adattarle alla densità attuale, consulta la Panoramica sulla compatibilità dello schermo. |
Tipo di touchscreen |
notouch finger
|
Vedi anche il campo di configurazione |
Disponibilità della tastiera |
keysexposed keyshidden keyssoft
|
Se fornisci risorse Questo può cambiare durante il ciclo di vita della tua app se l'utente apre una tastiera hardware. Per informazioni su come ciò influisce sulla tua app durante il runtime, consulta Gestire le modifiche alla configurazione. Consulta anche i campi di configurazione |
Metodo di immissione testo principale |
nokeys qwerty 12key
|
Vedi anche il campo di configurazione |
Disponibilità dei tasti di navigazione |
navexposed navhidden
|
Questo può cambiare durante il ciclo di vita della tua app se l'utente rivela i tasti di navigazione. Per informazioni su come ciò 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 |
nonav dpad trackball wheel
|
Vedi anche il campo di configurazione |
Versione piattaforma (livello API) | Esempi:v3 v4 v7 ecc. |
Il livello API supportato dal dispositivo. Ad esempio, |
Nota: non tutte le versioni di Android supportano tutti i qualificatori. L'utilizzo di un nuovo qualificatore aggiunge implicitamente quello
della versione della piattaforma in modo che i dispositivi meno recenti possano ignorarlo. Ad esempio, l'utilizzo di un qualificatore w600dp
include automaticamente il qualificatore v13
perché il qualificatore di larghezza disponibile era nuovo nel livello API 13. Per evitare problemi, includi sempre un insieme di risorse predefinite (un insieme di risorse senza qualificatori). Per ulteriori informazioni, consulta la sezione su come offrire 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-land
si 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 di risorse converte i nomi delle directory in lettere minuscole prima dell'elaborazione per evitare problemi nei file system che non fanno 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 Creare risorse alias.
Dopo aver salvato risorse alternative in directory denominate con questi qualificatori, Android applica automaticamente le risorse nella tua app in base all'attuale configurazione del dispositivo. Ogni volta che viene richiesta una risorsa, Android controlla le directory delle risorse alternative che contengono il file delle risorse richiesto, quindi trova la risorsa con corrispondenza migliore.
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 determinato tipo di risorsa che non include un qualificatore di configurazione.
Creazione di risorse alias
Se vuoi utilizzare una risorsa per più configurazioni di dispositivi, ma non vuoi specificarla come risorsa predefinita, non è necessario inserire la stessa risorsa in più directory di risorse alternative. Puoi invece creare una risorsa alternativa che funge da alias per una risorsa salvata nella tua directory delle risorse predefinita.
Nota: non tutte le risorse offrono un meccanismo mediante il quale è possibile creare un alias per un'altra risorsa. In particolare, animazione, menu, risorse non elaborate e altre risorse non specificate nella directory xml/
non offrono questa funzionalità.
Ad esempio, immagina di avere l'icona dell'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 l'inglese-canadese che per il francese-canadese.
Puoi invece salvare l'immagine utilizzata per entrambe le operazioni utilizzando un nome diverso da
icon.png
, ad esempio 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>
. In questo modo puoi archiviare una sola versione
del file PNG e due file XML di piccole dimensioni. Per maggiori dettagli, vedi gli esempi nelle sezioni seguenti.
Disegnabile
Per creare un alias a 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>
, racchiuso 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 a cui 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 per R.string.hello
.
Gli 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.
Una volta compilata l'applicazione, aapt
genera la classe R
, che contiene gli ID di tutte le risorse nella directory res/
. Per ogni tipo di risorsa, è presente 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.
Sebbene gli ID risorsa vengano specificati nella classe R
, non è necessario cercare lì per trovare un ID risorsa. Un ID risorsa è sempre composto da:
- Tipo di risorsa: ogni risorsa è raggruppata in un "tipo", ad esempio
string
,drawable
elayout
. Per saperne di più sui diversi tipi, vedi 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 classe
R
, ad esempio:R.string.hello
string
è il tipo di risorsa ehello
è il nome della risorsa. Esistono molte API Android che 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: utilizzi 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 che fornisci 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
Ecco 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 alle risorse del tuo pacchetto).<resource_type>
è la sottoclasseR
per il tipo di risorsa.<resource_name>
è il nome del file della risorsa senza l'estensione o il valore dell'attributoandroid:name
nell'elemento XML, per i valori semplici.
Per saperne di più su ciascun tipo di risorsa e su come fare riferimento, vedi Panoramica dei tipi di risorse.
Casi d'uso
Esistono molti metodi che accettano un parametro ID risorsa e puoi recuperare le risorse utilizzando 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
una volta compilato il progetto. 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 è necessaria 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 sottoclasseR
per il tipo di risorsa.<resource_name>
è il nome del file della risorsa senza l'estensione o il valore dell'attributoandroid:name
nell'elemento XML, per i valori semplici.
Per saperne di più su ciascun tipo di risorsa e su come fare 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 anche utilizzare una risorsa in XML in qualsiasi posizione che accetti un valore semplice. Ad esempio, se hai il 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 alla risorsa, perché 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: utilizza sempre risorse di tipo stringa, 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 di un'applicazione per altre lingue, consulta la sezione Localizzare l'app.
Puoi anche utilizzare risorse in XML per creare alias. Ad esempio, puoi creare una risorsa disegnabile che funge 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" />
Sembra ridondante, ma può essere molto utile quando si utilizzano risorse alternative. Per ulteriori informazioni, consulta la sezione sulla creazione di risorse alias.
Attributi dello stile 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 hardcoded. Il riferimento a un attributo di stile dice in sostanza: "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 al posto del simbolo "at" (@
) devi usare un punto interrogativo (?
). La parte del tipo di risorsa è facoltativa. Quindi 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 secondario del tema di 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 devi 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. Se lo fai, 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 che si trovano nella directory assets/
come su un normale file system e leggere i dati non elaborati utilizzando AssetManager
.
Tuttavia, se hai bisogno solo di poter 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 elemento 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 un ListView
. Puoi usare questo tipo di layout invece di creare
il tuo layout per gli elementi dell'elenco.
Fornisci 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 diverse lingue, includi sempre una directory values/
(in cui vengono salvate le stringhe) senza un qualificatore per 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 viene eseguita correttamente, anche se l'utente non comprende la lingua che presenta. È meglio che arrestarsi in modo anomalo.
Allo stesso modo, 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 orizzontale e layout-port/
per verticale, lasciane una come predefinita, ad esempio layout/
per orizzontale e layout-port/
per verticale.
Fornire risorse predefinite è importante non solo perché la tua app potrebbe essere eseguita su una configurazione non prevista, ma anche perché le nuove versioni di Android a volte aggiungono qualificatori di configurazione non supportati dalle versioni precedenti. Se utilizzi un nuovo qualificatore risorse, ma mantieni la compatibilità del codice con le versioni precedenti di Android, quando una versione precedente di Android esegue la tua app, l'app si arresta in modo anomalo se non fornisci risorse predefinite, perché non è possibile utilizzare le risorse denominate con il nuovo qualificatore.
Ad esempio, se il tuo minSdkVersion
è impostato su 4 e tutte le risorse disegnabili vengono idonee utilizzando la modalità notturna (night
o notnight
, che sono state aggiunte nel livello API 8), un dispositivo di livello API 4 non può accedere alle risorse disegnabili e agli arresti anomali. In questo caso, probabilmente vuoi che notnight
sia la tua risorsa predefinita, quindi escludi il qualificatore e inserisci le risorse disegnabili in drawable/
o drawable-night/
.
In breve, per offrire la migliore compatibilità dei dispositivi, fornisci sempre le risorse predefinite per le risorse necessarie all'app per funzionare correttamente. Poi crea risorse alternative per configurazioni dispositivo specifiche utilizzando i qualificatori di configurazione.
Esiste un'eccezione a questa regola: se il valore di minSdkVersion
dell'app è pari o superiore a 4, non hai bisogno di risorse disegnabili predefinite quando fornisci risorse disegnabili alternative con il qualificatore compattezza schermo. Anche senza risorse disegnabili predefinite, Android può trovare la migliore corrispondenza tra le densità di schermo alternative e ridimensionare le bitmap secondo necessità. 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 per cui fornisci alternative, Android seleziona la risorsa alternativa da utilizzare in fase di 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 ciascuna 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 dello schermo = port
Densità in pixel dello 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 stabilisce quali risorse utilizzare con la seguente logica:
- Elimina i file delle risorse che contraddicono la configurazione del dispositivo.
La directory
drawable-fr-rCA/
è stata eliminata perché contraddice le impostazioni internazionali dien-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 a causa di una contraddizione. Anche se la densità dello schermo del dispositivo è hdpi,
drawable-port-ldpi/
non viene eliminata perché ogni densità dello schermo viene considerata corrispondente in questo punto. Per informazioni, fai riferimento a Panoramica della compatibilità dello schermo. - Trova il qualificatore di precedenza più alto successivo nell'elenco (tabella 2). (Inizia con il Centro clienti.)
- Alcune directory delle risorse includono questo qualificatore?
- In caso contrario, torna al passaggio due e controlla il qualificatore successivo. In questo esempio, la risposta è "no" fino al raggiungimento del 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 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 più simile a quella del dispositivo. In generale, Android preferisce ridurre lo scale down di un'immagine originale più grande allo scale up di un'immagine originale più piccola. Per ulteriori informazioni, consulta Panoramica sulla compatibilità dello schermo.
- Ripeti i passaggi 2, 3 e 4 finché non rimane una sola directory. In questo esempio, l'orientamento dello schermo è il qualificatore successivo per cui esistono corrispondenze.
Pertanto, 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. Un'ottimizzazione di questo tipo è 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 viene mai inclusa nel pool di risorse verificate (sebbene sia ancora 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 più piccolo della schermata corrente se non sono presenti risorse che corrispondono meglio. Ad esempio, uno schermo di grandi dimensioni utilizza risorse dello 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 si verifica, ad esempio, se a tutte le risorse di layout viene assegnato 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 che corrisponde a (lingua). Tuttavia, il linguaggio ha una precedenza più alta rispetto a questi altri qualificatori, pertanto
drawable-port-notouch-12key
viene eliminato.