Il linguaggio delle espressioni ti consente di scrivere espressioni che gestiscono gli eventi inviati dalle visualizzazioni. La libreria di associazione di dati genera automaticamente le classi necessarie per associare le visualizzazioni nel layout agli oggetti di dati.
I file di layout di associazione di dati sono leggermente diversi e iniziano con un tag root layout, seguito da un elemento data e da un elemento root view. Questo elemento di visualizzazione è la radice in un file di layout non di associazione. Il seguente codice mostra un file di layout di esempio:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android">
<data>
<variable name="user" type="com.example.User"/>
</data>
<LinearLayout
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.firstName}"/>
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.lastName}"/>
</LinearLayout>
</layout>
La variabile user all'interno di data descrive una proprietà che può essere utilizzata all'interno di questo layout:
<variable name="user" type="com.example.User" />
Le espressioni all'interno del layout vengono scritte nelle proprietà degli attributi utilizzando la sintassi @{}. Nell'esempio seguente, il testo TextView è impostato sulla proprietà firstName della variabile user:
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.firstName}" />
Oggetti dati
Supponiamo che tu abbia un oggetto semplice per descrivere l'entità User:
Kotlin
data class User(val firstName: String, val lastName: String)
Java
public class User { public final String firstName; public final String lastName; public User(String firstName, String lastName) { this.firstName = firstName; this.lastName = lastName; } }
Questo tipo di oggetto contiene dati che non cambiano mai. Nelle app è comune avere dati che vengono letti una volta e non cambiano mai. È anche possibile utilizzare un oggetto che segue un insieme di convenzioni, ad esempio l'utilizzo di metodi della funzione di accesso nel linguaggio di programmazione Java, come mostrato nell'esempio seguente:
Kotlin
// Not applicable in Kotlin. data class User(val firstName: String, val lastName: String)
Java
public class User { private final String firstName; private final String lastName; public User(String firstName, String lastName) { this.firstName = firstName; this.lastName = lastName; } public String getFirstName() { return this.firstName; } public String getLastName() { return this.lastName; } }
Dal punto di vista dell'associazione di dati, queste due classi sono equivalenti. L'espressione @{user.firstName} utilizzata per l'attributo android:text accede al campo firstName nella prima classe e al metodo getFirstName() nella seconda classe. Viene inoltre risolto in firstName(), se questo metodo esiste.
Dati di associazione
Viene generata una classe di associazione per ogni file di layout. Per impostazione predefinita, il nome della classe si basa sul nome del file di layout, convertito in PascalCase, con l'aggiunta del suffisso Binding. Ad esempio, il nome file del layout precedente è
activity_main.xml, quindi la classe di associazione generata corrispondente è
ActivityMainBinding.
Questa classe contiene tutte le associazioni dalle proprietà del layout, ad esempio la variabile user, alle visualizzazioni del layout e sa come assegnare i valori per le espressioni di associazione. Ti consigliamo di creare le associazioni durante l'inflating del layout, come mostrato nell'esempio seguente:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val binding: ActivityMainBinding = DataBindingUtil.setContentView( this, R.layout.activity_main) binding.user = User("Test", "User") }
Java
@Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); ActivityMainBinding binding = DataBindingUtil.setContentView(this, R.layout.activity_main); User user = new User("Test", "User"); binding.setUser(user); }
In fase di runtime, l'app mostra l'utente Test nella UI. In alternativa, puoi ottenere la visualizzazione utilizzando un LayoutInflater, come mostrato nell'esempio seguente:
Kotlin
val binding: ActivityMainBinding = ActivityMainBinding.inflate(getLayoutInflater())
Java
ActivityMainBinding binding = ActivityMainBinding.inflate(getLayoutInflater());
Se utilizzi elementi di associazione di dati all'interno di un adattatore
Fragment,
ListView o
RecyclerView,
potresti preferire utilizzare i metodi
inflate()
delle classi di associazioni o della classe
DataBindingUtil, come
mostrato nell'esempio di codice seguente:
Kotlin
val listItemBinding = ListItemBinding.inflate(layoutInflater, viewGroup, false) // or val listItemBinding = DataBindingUtil.inflate(layoutInflater, R.layout.list_item, viewGroup, false)
Java
ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, false); // or ListItemBinding binding = DataBindingUtil.inflate(layoutInflater, R.layout.list_item, viewGroup, false);
Linguaggio delle espressioni
Funzionalità comuni
Il linguaggio delle espressioni è molto simile alle espressioni presenti nel codice gestito. Puoi utilizzare i seguenti operatori e parole chiave nel linguaggio delle espressioni:
- Matematica:
+ - / * % - Concatenazione di stringhe:
+ - Logico:
&& || - Binario:
& | ^ - Unaria:
+ - ! ~ - Turno:
>> >>> << - Confronto:
== > < >= <=(il carattere<deve essere preceduto dal carattere di escape<) instanceof- Raggruppamento:
() - Valori letterali, come caratteri, stringhe, numeri,
null - Trasmetti
- Chiamate ai metodi
- Accesso ai campi
- Accesso all'array:
[] - Operatore ternario:
?:
Ecco alcuni esempi:
android:text="@{String.valueOf(index + 1)}"
android:visibility="@{age > 13 ? View.GONE : View.VISIBLE}"
android:transitionName='@{"image_" + id}'
Operazioni mancanti
Le seguenti operazioni non sono presenti nella sintassi delle espressioni che puoi utilizzare nel codice gestito:
thissupernew- Chiamata generica esplicita
Operatore di coalescenza null
L'operatore di coalescenza null (??) sceglie l'operando sinistro se non è null
o quello destro se il primo è null:
android:text="@{user.displayName ?? user.lastName}"
Questo è funzionalmente equivalente a quanto segue:
android:text="@{user.displayName != null ? user.displayName : user.lastName}"
Riferimenti alle proprietà
Un'espressione può fare riferimento a una proprietà in una classe utilizzando il seguente formato, che è lo stesso per campi, getter e oggetti ObservableField:
android:text="@{user.lastName}"
Evita le eccezioni di puntatore nullo
Il codice di associazione di dati generato controlla automaticamente la presenza di valori null ed evita eccezioni di puntatore nullo. Ad esempio, nell'espressione @{user.name}, se user è null, a user.name viene assegnato il valore predefinito null. Se fai riferimento a user.age, dove l'età è di tipo int, l'associazione di dati utilizza il valore predefinito di 0.
Visualizza i riferimenti
Un'espressione può fare riferimento ad altre visualizzazioni nel layout in base all'ID, utilizzando la seguente sintassi:
android:text="@{exampleText.text}"
Nell'esempio seguente, la visualizzazione TextView fa riferimento a una visualizzazione EditText nello stesso layout:
<EditText
android:id="@+id/example_text"
android:layout_height="wrap_content"
android:layout_width="match_parent"/>
<TextView
android:id="@+id/example_output"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{exampleText.text}"/>
Raccolte
Puoi accedere a raccolte comuni, come array, elenchi, elenchi sparsi e mappe, utilizzando l'operatore [] per praticità.
<data>
<import type="android.util.SparseArray"/>
<import type="java.util.Map"/>
<import type="java.util.List"/>
<variable name="list" type="List<String>"/>
<variable name="sparse" type="SparseArray<String>"/>
<variable name="map" type="Map<String, String>"/>
<variable name="index" type="int"/>
<variable name="key" type="String"/>
</data>
...
android:text="@{list[index]}"
...
android:text="@{sparse[index]}"
...
android:text="@{map[key]}"
Puoi anche fare riferimento a un valore nella mappa utilizzando la notazione object.key. Ad esempio, puoi sostituire @{map[key]} nell'esempio precedente con @{map.key}.
Valori letterali stringa
Puoi utilizzare le virgolette singole per racchiudere il valore dell'attributo, il che ti consente di utilizzare le virgolette doppie nell'espressione, come mostrato nell'esempio seguente:
android:text='@{map["firstName"]}'
Puoi anche utilizzare le virgolette doppie per racchiudere il valore dell'attributo. In questo caso, i valori letterali stringa devono essere racchiusi tra apici inversi `, come mostrato qui:
android:text="@{map[`firstName`]}"
Risorse
Un'espressione può fare riferimento alle risorse dell'app con la seguente sintassi:
android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}"
Puoi valutare le stringhe di formato e i plurali fornendo i parametri:
android:text="@{@string/nameFormat(firstName, lastName)}"
android:text="@{@plurals/banana(bananaCount)}"
Puoi passare riferimenti alle proprietà e riferimenti alle viste come parametri delle risorse:
android:text="@{@string/example_resource(user.lastName, exampleText.text)}"
Quando un plurale accetta più parametri, passali tutti:
Have an orange
Have %d oranges
android:text="@{@plurals/orange(orangeCount, orangeCount)}"
Alcune risorse richiedono una valutazione esplicita del tipo, come mostrato nella tabella seguente:
| Tipo | Riferimento normale | Riferimento per le espressioni |
|---|---|---|
String[] |
@array |
@stringArray |
int[] |
@array |
@intArray |
TypedArray |
@array |
@typedArray |
Animator |
@animator |
@animator |
StateListAnimator |
@animator |
@stateListAnimator |
color int |
@color |
@color |
ColorStateList |
@color |
@colorStateList |
Gestione degli eventi
L'associazione di dati ti consente di scrivere espressioni che gestiscono gli eventi inviati dalle visualizzazioni, ad esempio il metodo onClick(). I nomi degli attributi degli eventi sono determinati dal nome del metodo del listener, con alcune eccezioni. Ad esempio,
View.OnClickListener ha
un metodo onClick(), quindi l'attributo per questo evento è android:onClick.
Esistono alcuni gestori di eventi specializzati per l'evento di clic che richiedono un attributo diverso da android:onClick per evitare un conflitto. Puoi utilizzare i seguenti attributi per evitare questo tipo di conflitti:
| Classe | Listener setter | Attributo |
|---|---|---|
SearchView |
setOnSearchClickListener(View.OnClickListener) |
android:onSearchClick |
ZoomControls |
setOnZoomInClickListener(View.OnClickListener) |
android:onZoomIn |
ZoomControls |
setOnZoomOutClickListener(View.OnClickListener) |
android:onZoomOut |
Per gestire un evento, puoi utilizzare questi due meccanismi, descritti in dettaglio nelle sezioni seguenti:
- Riferimenti ai metodi: nelle espressioni, puoi fare riferimento ai metodi conformi alla firma del metodo listener. Quando un'espressione restituisce un riferimento a un metodo, l'associazione di dati inserisce il riferimento al metodo e l'oggetto proprietario in un listener e imposta quest'ultimo nella visualizzazione di destinazione. Se l'espressione restituisce
null, l'associazione di dati non crea un listener e imposta invece un listenernull. - Associazioni di listener: si tratta di espressioni lambda che vengono valutate quando si verifica l'evento. L'associazione di dati crea sempre un listener, che imposta sulla visualizzazione. Quando l'evento viene inviato, il listener valuta l'espressione lambda.
Riferimenti ai metodi
Puoi associare gli eventi ai metodi del gestore direttamente, in modo simile a come puoi assegnare android:onClick a un metodo in un'attività. Un vantaggio rispetto all'attributo View onClick è che l'espressione viene elaborata in tempo di compilazione. Quindi, se il metodo non esiste o la sua firma non è corretta, ricevi un errore di tempo di compilazione.
La differenza principale tra i riferimenti ai metodi e le associazioni dei listener è che l'implementazione effettiva del listener viene creata quando i dati vengono associati, non quando viene attivato l'evento. Se preferisci valutare l'espressione quando si verifica l'evento, utilizza i binding dei listener.
Per assegnare un evento al relativo gestore, utilizza una normale espressione di associazione, con il valore che corrisponde al nome del metodo da chiamare. Ad esempio, considera il seguente oggetto dati di layout di esempio:
Kotlin
class MyHandlers { fun onClickFriend(view: View) { ... } }
Java
public class MyHandlers { public void onClickFriend(View view) { ... } }
L'espressione di associazione può assegnare il click listener per una visualizzazione al metodo onClickFriend(), come segue:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android">
<data>
<variable name="handlers" type="com.example.MyHandlers"/>
<variable name="user" type="com.example.User"/>
</data>
<LinearLayout
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<TextView android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@{user.firstName}"
android:onClick="@{handlers::onClickFriend}"/>
</LinearLayout>
</layout>
Associazioni dei listener
Le associazioni di listener sono espressioni di associazione che vengono eseguite quando si verifica un evento. Sono simili ai riferimenti ai metodi, ma consentono di eseguire espressioni di associazione di dati arbitrarie. Questa funzionalità è disponibile con il plug-in Android per Gradle per Gradle versione 2.0 e successive.
Nei riferimenti ai metodi, i parametri del metodo devono corrispondere ai parametri del listener di eventi. Nelle associazioni di listener, solo il valore restituito deve corrispondere al valore restituito previsto del listener, a meno che non sia previsto void. Ad esempio, considera la seguente classe presenter con un metodo onSaveClick():
Kotlin
class Presenter { fun onSaveClick(task: Task){} }
Java
public class Presenter { public void onSaveClick(Task task){} }
Puoi associare l'evento di clic al metodo onSaveClick() come segue:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android">
<data>
<variable name="task" type="com.android.example.Task" />
<variable name="presenter" type="com.android.example.Presenter" />
</data>
<LinearLayout android:layout_width="match_parent" android:layout_height="match_parent">
<Button android:layout_width="wrap_content" android:layout_height="wrap_content"
android:onClick="@{() -> presenter.onSaveClick(task)}" />
</LinearLayout>
</layout>
Quando un callback viene utilizzato in un'espressione, l'associazione di dati crea automaticamente il listener necessario e lo registra per l'evento. Quando la visualizzazione attiva l'evento, l'associazione di dati valuta l'espressione specificata. Come per le normali espressioni di associazione, ottieni la thread safety e la sicurezza dei valori null dell'associazione di dati durante la valutazione di queste espressioni di listener.
Nell'esempio precedente, il parametro view passato a onClick(View) non è definito. Le associazioni di listener offrono due opzioni per i parametri del listener:
puoi ignorare tutti i parametri del metodo o assegnare un nome a tutti. Se preferisci assegnare un nome ai parametri, puoi utilizzarli nell'espressione. Ad esempio, puoi scrivere l'espressione precedente nel seguente modo:
android:onClick="@{(view) -> presenter.onSaveClick(task)}"
Se vuoi utilizzare il parametro nell'espressione, puoi farlo nel seguente modo:
Kotlin
class Presenter { fun onSaveClick(view: View, task: Task){} }
Java
public class Presenter { public void onSaveClick(View view, Task task){} }
android:onClick="@{(theView) -> presenter.onSaveClick(theView, task)}"
Inoltre, puoi utilizzare un'espressione lambda con più di un parametro:
Kotlin
class Presenter { fun onCompletedChanged(task: Task, completed: Boolean){} }
Java
public class Presenter { public void onCompletedChanged(Task task, boolean completed){} }
<CheckBox android:layout_width="wrap_content" android:layout_height="wrap_content"
android:onCheckedChanged="@{(cb, isChecked) -> presenter.completeChanged(task, isChecked)}" />
Se l'evento che stai ascoltando restituisce un valore il cui tipo non è void, anche le tue espressioni devono restituire lo stesso tipo di valore. Ad esempio, se vuoi ascoltare l'evento di tocco e pressione (clic lungo), l'espressione deve restituire un valore booleano.
Kotlin
class Presenter { fun onLongClick(view: View, task: Task): Boolean { } }
Java
public class Presenter { public boolean onLongClick(View view, Task task) { } }
android:onLongClick="@{(theView) -> presenter.onLongClick(theView, task)}"
Se l'espressione non può essere valutata a causa di oggetti null, l'associazione di dati restituisce il valore predefinito per quel tipo, ad esempio null per i tipi di riferimento, 0 per int o false per boolean.
Se devi utilizzare un'espressione con un predicato, ad esempio un operatore ternario, puoi utilizzare void come simbolo:
android:onClick="@{(v) -> v.isVisible() ? doSomething() : void}"
Evita listener complessi
Le espressioni di listener sono potenti e possono semplificare la lettura del codice. D'altra parte, i listener contenenti espressioni complesse rendono i layout più difficili da leggere e gestire. Mantieni le espressioni semplici, ad esempio passando i dati disponibili dalla UI al metodo di callback. Implementa la logica di business all'interno del metodo di callback che richiami dall'espressione del listener.
Importazioni, variabili e inclusioni
La libreria di associazione di dati fornisce funzionalità come importazioni, variabili e inclusioni. Le importazioni creano classi facili da consultare all'interno dei file di layout. Le variabili ti consentono di descrivere una proprietà che può essere utilizzata nelle espressioni di associazione. Gli elementi include ti consentono di riutilizzare layout complessi nell'app.
Importazioni
Le importazioni ti consentono di fare riferimento alle classi all'interno del file di layout, come nel codice gestito.
Puoi utilizzare zero o più elementi import all'interno dell'elemento data. Il seguente esempio di codice importa la classe View nel file di layout:
<data>
<import type="android.view.View"/>
</data>
L'importazione della classe View ti consente di farvi riferimento dalle espressioni di associazione.
L'esempio seguente mostra come fare riferimento alle costanti VISIBLE e GONE della classe View:
<TextView
android:text="@{user.lastName}"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"/>
Alias del tipo
In caso di conflitti tra i nomi delle classi, puoi rinominare una delle classi con un alias. L'esempio seguente rinomina la classe View nel pacchetto com.example.real.estate in Vista:
<import type="android.view.View"/>
<import type="com.example.real.estate.View"
alias="Vista"/>
Puoi quindi utilizzare Vista per fare riferimento a com.example.real.estate.View e View per fare riferimento a android.view.View all'interno del file di layout.
Importa altri corsi
Puoi utilizzare i tipi importati come riferimenti ai tipi in variabili ed espressioni. L'esempio seguente mostra User e List utilizzati come tipo di variabile:
<data>
<import type="com.example.User"/>
<import type="java.util.List"/>
<variable name="user" type="User"/>
<variable name="userList" type="List<User>"/>
</data>
Puoi utilizzare i tipi importati per eseguire il cast di parte di un'espressione. L'esempio seguente esegue il cast della proprietà connection a un tipo di User:
<TextView
android:text="@{((User)(user.connection)).lastName}"
android:layout_width="wrap_content"
android:layout_height="wrap_content"/>
Puoi anche utilizzare i tipi importati quando fai riferimento a campi e metodi statici nelle espressioni. Il seguente codice importa la classe MyStringUtils e fa riferimento al relativo metodo capitalize:
<data>
<import type="com.example.MyStringUtils"/>
<variable name="user" type="com.example.User"/>
</data>
…
<TextView
android:text="@{MyStringUtils.capitalize(user.lastName)}"
android:layout_width="wrap_content"
android:layout_height="wrap_content"/>
Come nel codice gestito, java.lang.* viene importato automaticamente.
Variabili
Puoi utilizzare più elementi variable all'interno dell'elemento data. Ogni elemento variable descrive una proprietà che può essere impostata sul layout da utilizzare nelle espressioni di associazione all'interno del file di layout. L'esempio seguente dichiara
le variabili user, image e note:
<data>
<import type="android.graphics.drawable.Drawable"/>
<variable name="user" type="com.example.User"/>
<variable name="image" type="Drawable"/>
<variable name="note" type="String"/>
</data>
I tipi di variabili vengono controllati in fase di compilazione, quindi se una variabile implementa
Observable o è una
raccolta osservabile,
questo deve essere riflesso nel tipo. Se la variabile è una classe base o un'interfaccia che non implementa l'interfaccia Observable, le variabili non vengono osservate.
Quando sono presenti file di layout diversi per varie configurazioni (ad esempio, orizzontale o verticale), le variabili vengono combinate. Non devono esserci definizioni di variabili in conflitto tra questi file di layout.
La classe di associazione generata ha un setter e un getter per ciascuna delle variabili descritte. Le variabili assumono i valori predefiniti del codice gestito finché non viene chiamato il setter: null per i tipi di riferimento, 0 per int, false per boolean e così via.
Viene generata una variabile speciale denominata context da utilizzare nelle espressioni di associazione, se necessario. Il valore di context è l'oggetto Context del metodo getContext() della visualizzazione principale. La variabile context viene sostituita da una dichiarazione di variabile esplicita con quel nome.
Include
Puoi passare le variabili all'associazione di un layout incluso dal layout contenitore utilizzando lo spazio dei nomi dell'app e il nome della variabile in un attributo. L'esempio seguente mostra le variabili user incluse dai file di layout name.xml e contact.xml:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:bind="http://schemas.android.com/apk/res-auto">
<data>
<variable name="user" type="com.example.User"/>
</data>
<LinearLayout
android:orientation="vertical"
android:layout_width="match_parent"
android:layout_height="match_parent">
<include layout="@layout/name"
bind:user="@{user}"/>
<include layout="@layout/contact"
bind:user="@{user}"/>
</LinearLayout>
</layout>
L'associazione di dati non supporta un elemento include come elemento secondario diretto di un elemento merge. Ad esempio, il seguente layout non è supportato:
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:bind="http://schemas.android.com/apk/res-auto">
<data>
<variable name="user" type="com.example.User"/>
</data>
<merge><!-- Doesn't work -->
<include layout="@layout/name"
bind:user="@{user}"/>
<include layout="@layout/contact"
bind:user="@{user}"/>
</merge>
</layout>
Risorse aggiuntive
Per saperne di più sull'associazione di dati, consulta le seguenti risorse aggiuntive.