Layouts und Bindungsausdrücke

Mit der Ausdruckssprache können Sie Ausdrücke schreiben, die Ereignisse verarbeiten, die von Ansichten ausgelöst werden. Die Datenbindungsbibliothek generiert automatisch die Klassen, die erforderlich sind, um die Ansichten im Layout mit Ihren Datenobjekten zu verknüpfen.

Die Layoutdateien für die Datenbindung unterscheiden sich leicht voneinander und beginnen mit dem Stamm-Tag layout, gefolgt von einem data- und einem view-Stammelement. Dieses Ansichtselement ist der Stamm in einer unverbindlichen Layoutdatei. Der folgende Code zeigt ein Beispiel für eine Layoutdatei:

<?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>

Die Variable user in data beschreibt eine Eigenschaft, die in diesem Layout verwendet werden kann:

<variable name="user" type="com.example.User" />

Ausdrücke im Layout werden mit der Syntax @{} in den Attributeigenschaften geschrieben. Im folgenden Beispiel wird der Text TextView auf das Attribut firstName der Variable user festgelegt:

<TextView android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:text="@{user.firstName}" />

Datenobjekte

Angenommen, Sie haben ein einfaches Objekt, um die User-Entität zu beschreiben:

data class User(val firstName: String, val lastName: String)

public class User {
  public final String firstName;
  public final String lastName;
  public User(String firstName, String lastName) {
      this.firstName = firstName;
      this.lastName = lastName;
  }
}

Dieser Objekttyp enthält Daten, die sich nie ändern. Daten, die nur einmal gelesen werden und sich danach nicht ändern, sind üblich. Es ist auch möglich, ein Objekt zu verwenden, das einer Reihe von Konventionen entspricht, z. B. Zugriffsmethoden in der Programmiersprache Java, wie im folgenden Beispiel gezeigt:

// Not applicable in Kotlin.
data class User(val firstName: String, val lastName: String)

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;
  }
}

Aus Sicht der Datenbindung sind diese beiden Klassen gleichwertig. Der Ausdruck @{user.firstName}, der für das Attribut android:text verwendet wird, greift auf das Feld firstName in der vorherigen Klasse und die Methode getFirstName() in der letzten Klasse zu. Sie wird auch in firstName() aufgelöst, sofern diese Methode vorhanden ist.

Bindung von Daten

Für jede Layoutdatei wird eine Bindungsklasse generiert. Der Name der Klasse basiert standardmäßig auf dem Namen der Layoutdatei, der in die Pascal-Case-Schreibweise konvertiert wird und dem das Suffix Binding hinzugefügt wird. Der vorherige Layoutdateiname ist beispielsweise activity_main.xml. Die entsprechende generierte Bindungsklasse lautet also ActivityMainBinding.

Diese Klasse enthält alle Bindungen aus den Layouteigenschaften, z. B. die Variable user, zu den Layoutansichten und weiß, wie Werte für die Bindungsausdrücke zugewiesen werden. Wir empfehlen, die Bindungen zu erstellen, während das Layout aufgebläht wird, wie im folgenden Beispiel gezeigt:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val binding: ActivityMainBinding = DataBindingUtil.setContentView(
            this, R.layout.activity_main)

    binding.user = User("Test", "User")
}

@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);
}

Zur Laufzeit wird der Test-Nutzer auf der Benutzeroberfläche der App angezeigt. Alternativ können Sie die Ansicht mit einem LayoutInflater abrufen, wie im folgenden Beispiel gezeigt:

val binding: ActivityMainBinding = ActivityMainBinding.inflate(getLayoutInflater())

ActivityMainBinding binding = ActivityMainBinding.inflate(getLayoutInflater());

Wenn Sie Datenbindungselemente in einem Fragment-, ListView- oder RecyclerView-Adapter verwenden, sollten Sie die inflate()-Methoden der Bindungsklassen oder die DataBindingUtil-Klasse verwenden, wie im folgenden Codebeispiel gezeigt:

val listItemBinding = ListItemBinding.inflate(layoutInflater, viewGroup, false)
// or
val listItemBinding = DataBindingUtil.inflate(layoutInflater, R.layout.list_item, viewGroup, false)

ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, false);
// or
ListItemBinding binding = DataBindingUtil.inflate(layoutInflater, R.layout.list_item, viewGroup, false);

Ausdruckssprache

Gemeinsame Funktionen

Die Ausdruckssprache ähnelt den Ausdrücken im verwalteten Code. Sie können die folgenden Operatoren und Schlüsselwörter in der Ausdruckssprache verwenden:

• Mathematische Daten: + - / * %
• Stringverkettung: +
• Logisch: && ||
• Binär: & | ^
• Unär: + - ! ~
• Umschalttaste: >> >>> <<
• Vergleich: == > < >= <= (< muss als < maskiert werden)
• instanceof
• Gruppieren: ()
• Literale, z. B. Zeichen, String, numerisch, null
• Streamen
• Methodenaufrufe
• Feldzugriff
• Array-Zugriff: []
• Ternärer Operator: ?:

Hier einige Beispiele:

android:text="@{String.valueOf(index + 1)}"
android:visibility="@{age > 13 ? View.GONE : View.VISIBLE}"
android:transitionName='@{"image_" + id}'

Fehlende Vorgänge

In der Ausdruckssyntax fehlen die folgenden Vorgänge, die Sie im verwalteten Code verwenden können:

• this
• super
• new
• Expliziter generischer Aufruf

Null-Zusammenführungsoperator

Der Null-Zusammenführungsoperator (??) wählt den linken Operanden aus, wenn er nicht null ist, oder den rechten, wenn der erste Operand null ist:

android:text="@{user.displayName ?? user.lastName}"

Funktional gesehen entspricht dies Folgendem:

android:text="@{user.displayName != null ? user.displayName : user.lastName}"

Property-Verweise

Ein Ausdruck kann mithilfe des folgenden Formats, das für Felder, Getter und ObservableField-Objekte gleich ist, auf ein Attribut in einer Klasse verweisen:

android:text="@{user.lastName}"

Nullzeigerausnahmen vermeiden

Der generierte Datenbindungscode prüft automatisch auf null-Werte und vermeidet Nullzeigerausnahmen. Wenn im Ausdruck @{user.name} beispielsweise user null ist, wird user.name der Standardwert null zugewiesen. Wenn Sie auf user.age verweisen, wobei das Alter vom Typ int ist, verwendet die Datenbindung den Standardwert 0.

Verweise ansehen

Ein Ausdruck kann mit der folgenden Syntax nach ID auf andere Ansichten im Layout verweisen:

android:text="@{exampleText.text}"

Im folgenden Beispiel verweist die Ansicht TextView auf eine EditText-Ansicht im selben 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}"/>

Sammlungen

Sie können auf allgemeine Sammlungen wie Arrays, Listen, dünnbesetzte Listen und Karten zugreifen, indem Sie der []-Operator der Einfachheit halber verwenden.

<data>
    <import type="android.util.SparseArray"/>
    <import type="java.util.Map"/>
    <import type="java.util.List"/>
    <variable name="list" type="List&lt;String>"/>
    <variable name="sparse" type="SparseArray&lt;String>"/>
    <variable name="map" type="Map&lt;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]}"

Mit der object.key-Notation können Sie auch auf einen Wert in der Karte verweisen. So können Sie beispielsweise @{map[key]} im vorherigen Beispiel durch @{map.key} ersetzen.

Stringliterale

Sie können den Attributwert in einfache Anführungszeichen setzen. So können Sie im Ausdruck doppelte Anführungszeichen verwenden, wie im folgenden Beispiel gezeigt:

android:text='@{map["firstName"]}'

Der Attributwert kann auch in doppelte Anführungszeichen gesetzt werden. Dabei müssen Stringliterale wie hier gezeigt von Backticks (`) umgeben sein:

android:text="@{map[`firstName`]}"

Ressourcen

Ein Ausdruck kann mit der folgenden Syntax auf Anwendungsressourcen verweisen:

android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}"

Formatstrings und Pluralformen können durch Angeben von Parametern ausgewertet werden:

android:text="@{@string/nameFormat(firstName, lastName)}"
android:text="@{@plurals/banana(bananaCount)}"

Sie können Property-Verweise und Ansichtsreferenzen als Ressourcenparameter übergeben:

android:text="@{@string/example_resource(user.lastName, exampleText.text)}"

Wenn für einen Plural mehrere Parameter verwendet werden, übergeben Sie alle Parameter:

  Have an orange
  Have %d oranges

android:text="@{@plurals/orange(orangeCount, orangeCount)}"

Einige Ressourcen erfordern eine explizite Typbewertung, wie in der folgenden Tabelle gezeigt:

Ereignisverarbeitung

Mit der Datenbindung können Sie Ausdrücke zur Verarbeitung von Ereignissen schreiben, die aus den Ansichten ausgelöst werden, z. B. mit der Methode onClick(). Die Namen von Ereignisattributen werden bis auf wenige Ausnahmen durch den Namen der Listener-Methode bestimmt. Zum Beispiel hat View.OnClickListener die Methode onClick(), also ist das Attribut für dieses Ereignis android:onClick.

Es gibt einige spezielle Event-Handler für das Klickereignis, für die ein anderes Attribut als android:onClick erforderlich ist, um einen Konflikt zu vermeiden. Mit den folgenden Attributen können Sie solche Konflikte vermeiden:

Sie können die beiden Mechanismen verwenden, die in den folgenden Abschnitten ausführlich beschrieben werden, um ein Ereignis zu verarbeiten:

• Methodenverweise: In Ihren Ausdrücken können Sie auf Methoden verweisen, die der Signatur der Listener-Methode entsprechen. Wenn ein Ausdruck als Methodenverweis ausgewertet wird, werden der Methodenverweis und das Inhaberobjekt durch die Datenbindung in einen Listener eingebunden und dieser Listener in der Zielansicht festgelegt. Wenn der Ausdruck null ergibt, wird durch die Datenbindung kein Listener erstellt und stattdessen ein null-Listener festgelegt.
• Listener-Bindungen: Dies sind Lambda-Ausdrücke, die beim Eintreten des Ereignisses ausgewertet werden. Die Datenbindung erstellt immer einen Listener, der für die Ansicht festgelegt wird. Wenn das Ereignis gesendet wird, wertet der Listener den Lambda-Ausdruck aus.

Methodenreferenzen

Sie können Ereignisse direkt an Handler-Methoden binden, ähnlich wie Sie einer Methode in einer Aktivität android:onClick zuweisen. Ein Vorteil gegenüber dem onClick-Attribut View besteht darin, dass der Ausdruck bei der Kompilierung verarbeitet wird. Wenn also die Methode nicht existiert oder ihre Signatur falsch ist, wird ein Kompilierungszeitfehler angezeigt.

Der Hauptunterschied zwischen Methodenverweisen und Listener-Bindungen besteht darin, dass die tatsächliche Listener-Implementierung beim Binden der Daten und nicht beim Auslösen des Ereignisses erstellt wird. Wenn Sie den Ausdruck beim Eintreten des Ereignisses auswerten möchten, verwenden Sie Listener-Bindungen.

Wenn Sie dem Handler ein Ereignis zuweisen möchten, verwenden Sie einen normalen Bindungsausdruck, wobei der Wert der aufzurufende Methodenname ist. Betrachten Sie zum Beispiel das folgende Beispiel für ein Layoutdatenobjekt:

class MyHandlers {
    fun onClickFriend(view: View) { ... }
}

public class MyHandlers {
    public void onClickFriend(View view) { ... }
}

Mit dem Bindungsausdruck kann der Klick-Listener für eine Ansicht der Methode onClickFriend() zugewiesen werden:

<?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>

Listener-Bindungen

Listener-Bindungen sind Bindungsausdrücke, die ausgeführt werden, wenn ein Ereignis eintritt. Sie ähneln Methodenreferenzen, ermöglichen es Ihnen jedoch, beliebige Datenbindungsausdrücke auszuführen. Diese Funktion ist mit dem Android Gradle-Plug-in für Gradle Version 2.0 und höher verfügbar.

In Methodenreferenzen müssen die Parameter der Methode mit den Parametern des Ereignis-Listeners übereinstimmen. In Listener-Bindungen muss nur der Rückgabewert mit dem erwarteten Rückgabewert des Listeners übereinstimmen, es sei denn, er erwartet void. Betrachten Sie beispielsweise die folgende Präsentationsklasse mit der Methode onSaveClick():

class Presenter {
    fun onSaveClick(task: Task){}
}

public class Presenter {
    public void onSaveClick(Task task){}
}

So binden Sie das Klickereignis an die Methode onSaveClick():

<?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>

Wenn ein Callback in einem Ausdruck verwendet wird, erstellt die Datenbindung automatisch den erforderlichen Listener und registriert ihn für das Ereignis. Wenn das Ereignis in der Ansicht ausgelöst wird, wertet die Datenbindung den angegebenen Ausdruck aus. Wie bei regulären Bindungsausdrücken erhalten Sie auch hier die Null- und Thread-Sicherheit der Datenbindung, während diese Listener-Ausdrücke ausgewertet werden.

Im vorherigen Beispiel ist der an onClick(View) übergebene Parameter view nicht definiert. Listener-Bindungen bieten zwei Auswahlmöglichkeiten für Listener-Parameter: Sie können alle Parameter für die Methode ignorieren oder alle benennen. Wenn Sie die Parameter lieber benennen möchten, können Sie sie in Ihrem Ausdruck verwenden. Sie können den vorherigen Ausdruck beispielsweise so schreiben:

android:onClick="@{(view) -> presenter.onSaveClick(task)}"

Wenn Sie den Parameter im Ausdruck verwenden möchten, können Sie dies so tun:

class Presenter {
    fun onSaveClick(view: View, task: Task){}
}

public class Presenter {
    public void onSaveClick(View view, Task task){}
}

android:onClick="@{(theView) -> presenter.onSaveClick(theView, task)}"

Und Sie können einen Lambda-Ausdruck mit mehr als einem Parameter verwenden:

class Presenter {
    fun onCompletedChanged(task: Task, completed: Boolean){}
}

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)}" />

Wenn das Ereignis, das Sie überwachen, einen Wert zurückgibt, dessen Typ nicht void ist, müssen Ihre Ausdrücke auch denselben Werttyp zurückgeben. Wenn Sie beispielsweise auf das Ereignis „Berühren und halten“ (langes Klicken) warten möchten, muss der Ausdruck einen booleschen Wert zurückgeben.

class Presenter {
    fun onLongClick(view: View, task: Task): Boolean { }
}

public class Presenter {
    public boolean onLongClick(View view, Task task) { }
}

android:onLongClick="@{(theView) -> presenter.onLongClick(theView, task)}"

Wenn der Ausdruck aufgrund von null-Objekten nicht ausgewertet werden kann, gibt die Datenbindung den Standardwert für diesen Typ zurück, z. B. null für Referenztypen, 0 für int oder false für boolean.

Wenn Sie einen Ausdruck mit einem Prädikat verwenden müssen (z. B. ein ternär), können Sie void als Symbol verwenden:

android:onClick="@{(v) -> v.isVisible() ? doSomething() : void}"

Komplexe Listener vermeiden

Listener-Ausdrücke sind leistungsstark und können das Lesen des Codes erleichtern. Listener mit komplexen Ausdrücken erschweren jedoch das Lesen und Verwalten Ihrer Layouts schwer. Halten Sie Ihre Ausdrücke so einfach wie das Übergeben verfügbarer Daten von Ihrer UI an Ihre Callback-Methode. Implementieren Sie Geschäftslogik innerhalb der Callback-Methode, die Sie über den Listener-Ausdruck aufrufen.

Importe, Variablen und Einschleusungen

Die Datenbindungsbibliothek bietet Features wie Importe, Variablen und Enthalten. Durch Importe können in Layoutdateien leicht auf Klassen verwiesen werden. Mit Variablen können Sie eine Eigenschaft beschreiben, die in Bindungsausdrücken verwendet werden kann. Mit „Einschließen“ können Sie komplexe Layouts in Ihrer App wiederverwenden.

Importe

Mit Importen können Sie in Ihrer Layoutdatei, wie z. B. in verwaltetem Code, auf Klassen verweisen. Innerhalb des data-Elements können Sie null oder mehr import-Elemente verwenden. Mit dem folgenden Codebeispiel wird die Klasse View in die Layoutdatei importiert:

<data>
    <import type="android.view.View"/>
</data>

Wenn Sie die View-Klasse importieren, können Sie in Ihren Bindungsausdrücken darauf verweisen. Das folgende Beispiel zeigt, wie auf die Konstanten VISIBLE und GONE der Klasse View verwiesen wird:

<TextView
   android:text="@{user.lastName}"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"/>

Typaliasse

Bei Konflikten mit Klassennamen können Sie eine der Klassen in einen Alias umbenennen. Im folgenden Beispiel wird die Klasse View im Paket com.example.real.estate in Vista umbenannt:

<import type="android.view.View"/>
<import type="com.example.real.estate.View"
        alias="Vista"/>

Sie können dann Vista verwenden, um auf com.example.real.estate.View zu verweisen, und View, um in der Layoutdatei auf android.view.View zu verweisen.

Andere Kurse importieren

Sie können importierte Typen als Typverweise in Variablen und Ausdrücken verwenden. Im folgenden Beispiel werden User und List als Variablentyp verwendet:

<data>
    <import type="com.example.User"/>
    <import type="java.util.List"/>
    <variable name="user" type="User"/>
    <variable name="userList" type="List&lt;User>"/>
</data>

Sie können die importierten Typen verwenden, um einen Teil eines Ausdrucks umzuwandeln. Im folgenden Beispiel wird das Attribut connection in den Typ User umgewandelt:

<TextView
   android:text="@{((User)(user.connection)).lastName}"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

Sie können importierte Typen auch verwenden, wenn Sie in Ausdrücken auf statische Felder und Methoden verweisen. Mit dem folgenden Code wird die Klasse MyStringUtils importiert und auf ihre Methode capitalize verwiesen:

<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"/>

Genau wie bei verwaltetem Code wird java.lang.* automatisch importiert.

Variablen

Innerhalb des data-Elements kannst du mehrere variable-Elemente verwenden. Jedes variable-Element beschreibt eine Eigenschaft, die für das Layout festgelegt werden kann, um es in Bindungsausdrücken innerhalb der Layoutdatei zu verwenden. Im folgenden Beispiel werden die Variablen user, image und note deklariert:

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

Die Variablentypen werden beim Kompilieren überprüft. Wenn eine Variable also Observable implementiert oder eine beobachtbare Sammlung ist, muss dies im Typ widergespiegelt werden. Wenn die Variable eine Basisklasse oder Schnittstelle ist, in der die Observable-Schnittstelle nicht implementiert ist, werden die Variablen nicht beobachtet.

Wenn es für verschiedene Konfigurationen (z. B. Quer- oder Hochformat) verschiedene Layoutdateien gibt, werden die Variablen kombiniert. Zwischen diesen Layoutdateien dürfen keine Variablendefinitionen in Konflikt stehen.

Die generierte Bindungsklasse hat für jede der beschriebenen Variablen einen Setter und einen Getter. Die Variablen verwenden die standardmäßigen verwalteten Codewerte, bis der Setter aufgerufen wird: null für Referenztypen, 0 für int, false für boolean usw.

Zur Verwendung in Bindungsausdrücken wird bei Bedarf eine spezielle Variable mit dem Namen context generiert. Der Wert für context ist das Objekt Context aus der Methode getContext() der Stammansicht. Die Variable context wird durch eine explizite Variablendeklaration mit diesem Namen überschrieben.

Umfasst

Sie können Variablen an die Bindung eines enthaltenen Layouts aus dem enthaltenen Layout übergeben, indem Sie den App-Namespace und den Variablennamen in einem Attribut verwenden. Das folgende Beispiel zeigt user-Variablen aus den Layoutdateien name.xml und 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>

Die Datenbindung unterstützt keinen Einschluss als direktes untergeordnetes Element eines Zusammenführungselements. Das folgende Layout wird beispielsweise nicht unterstützt:

<?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>