Android DataBinding 使用指南

  本内容主要介绍如何使用 Android 架构组件中的 Data Binding。

  Android DataBinding 的官方介绍文档：https://developer.android.com/topic/libraries/data-binding/

一、简介

  Data Binding 库是一个支持库，它允许您在 App 中通过声明方式（而不是编程方式）将布局中的 UI 组件和数据源进行绑定。

  Data Binding 库具备灵活性和兼容性，可以在 Android 4.0（API 14）以及更高版本中使用。

  在 Android Gradle 插件的 1.5.0 以及更高版本中支持 Data Binding 库，不过推荐使用最新版本。

1.1 构建环境

  为了在您的 App 中使用 Data Binding，需要在您的 App 模块的 build.gradle 文件中添加 dataBinding 元素，如下所示：

android {
    ...
    dataBinding {
        enabled = true
    }
}

注意：即使您 App 模块没有直接使用 Data Binding，但是如果它的依赖库使用了 Data Binding，那么也需要像上面一样配置 dataBinding 元素。

1.2 Binding 类的新 Data Binding 编译器

  在 Android Gradle 插件的 3.1.0-alpha06 版本中包含了一个生成绑定类的新 Data Binding 编译器。新的编译器逐步创建绑定类，这在大多数情况下加快了构建过程。

  以前版本的 Data Binding 编译器在编译代码时生成绑定类。如果您的代码编译失败，您可能会收到多个报告绑定类无法找到的错误。新的 Data Binding 编译器将在编译代码之前生成绑定类，来避免这些错误。

  要启用新的 Data Binding 编译器，请在 gradle.properties 文件中添加以下选项：

android.databinding.enableV2=true

  你还可以通过在 gradle 命令中添加以下参数来启用新的编译器：

-Pandroid.databinding.enableV2=true

注意：Android Gradle 插件版本 3.1 中的 Data Binding 编译器不向后兼容。。然而，Android Gradle 3.2 版本中的新编译器与先前版本生成的绑定类兼容。在 3.2 版本中，默认启用新编译器。

二、Layout 和 Binding 表达式

  表达式语言允许您编写表达式，用于处理 View 分发的事件。Data Binding 库将自动产生一个类，用于将布局中的 View 与数据对象绑定。

  Data binding 布局文件略有不同，最外面是 layout 的根标记，里面包含一个 data 元素和一个 view 根元素。这个 view 元素实际上就是非 Data binding 布局文件的根元素。下面的代码显示了一个示例布局文件：

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

  在 data 元素中定义了 user 变量，在布局中可以使用它。

  布局中的表达式使用 "@{}" 语法写入属性中。上面的 TextView 的 text 被设置为 user 变量的 firstName 属性。

注意：布局表达式应该小而简单，因为它们不能进行单元测试，并且 IDE 对其支持有限。您可以使用自定义的 Binding Adapter 来简化布局表达式。

2.1 数据对象

  假设你有一个 POJO（Plain Old Java Object） 来描述 User 实体：

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

  这类对象持有的数据永不改变。也可以使用遵循一组约定的对象，如下面的示例所示：

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

  从 Data Binding 的角度来看，这两个类是等价的。用于 android:text 属性的表达式 @{user.firstName} 访问第一个类的 firstName 字段和第二个类的 getFirstName() （用 firstName() 替换也可以）方法。

2.2 绑定数据 (与“生成的绑定类”重复)

  为每个布局文件生成一个 Binding 类。默认情况下，基于布局文件的名称给这个 Binding 类命名，采用“帕斯卡命名法”（即大驼峰命名法）并添加 Binding 后缀。比如，布局文件的名称为 activity_main.xml，则对应的 Binding 类的名称为 ActivityMainBinding。这个 Binding 类拥有从布局属性（例如 user 变量）到布局中的 View 的所有 Binding，并知道如何为绑定表达式赋值。推荐在 inflate 布局时创建 Binding，如下面的代码所示：

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

  你也可以使用 LayoutInflater 获取 View，如下面的代码所示：

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

  如果在 Fragment、ListView 或 RecyclerView Adapter 中使用 Data Binding，您可以使用 Binding 类的 inflate() 方法或 DataBindingUtil 类。如下面的代码所示：

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

2.3 表达式语言

2.3.1 共同特征

  在表达式语言中，您可以使用如下运算符和关键字：

• 数学的 + - / * %
• 字符串连接 +
• 逻辑 && ||
• 二进制 & | ^
• 一元 + - ! ~
• 移动 >> >>> <<
• 比较 == > < >= <=（注意：< 需要转义为 <）
• instanceof
• 分组 ()
• 文字 - 字符、字符串、数字、null
• Cast
• 方法调用
• 字段访问
• 数组访问 []
• 三元操作符 ?:

例子：

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

2.3.2 不支持的操作（Missing operations）

  在表达式语法中，不能使用以下操作：

• this
• super
• new
• 显式通用调用

2.3.3 空合并运算符（Null coalescing operator）

  以下两种方法等效：

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

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

2.3.4 属性引用

  表达式可以按照以下格式引用类的属性，引用方法对字段、getter 和 ObservableField 对象都是相同。

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

2.3.5 避免空指针异常

  生成的 Data Binding 代码会自动检查 null 值，从而避免空指针异常。例如，在表达式 @{user.name} 中，如果 user 为 null，user.name 将被赋为默认的 null。如果您引用 user.age，因为 age 是 int 类型，那它的默认值为 0。

2.3.6 集合

  为了方便，可以使用 [] 运算符访问常用集合（比如 array、list、稀疏 list 和 map）。

<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]}"

注意：需要转义 < 字符，来确保 XML 语法正确。所以需要使用 List<String> 来代替 List。

  您还可以使用 object.key 表示法引用 map 中的值。例如，可以使用 @{map.key} 代替 map[key]。

2.3.7 字符串文字（String literals）

  您可以使用单引号括起属性值，在表达式中使用双引号，如下面代码所示：

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

  您也可以使用双引号括起属性值，在表达式中使用反引号（`），注意不是单引号：

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

2.3.8 资源

  在表达式中，您可以使用如下语法访问资源：

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

  格式字符串和复数可以通过参数进行计算：

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

  当复数有多个参数时，应传递所有参数：

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

  有些资源需要指定显示类型，如下表所示：

Type	Normal reference	Expression reference
String[]	@array	@stringArray
int[]	@array	@intArray
TypedArray	@array	@typedArray
Animator	@animator	@animator
StateListAnimator	@animator	@stateListAnimator
color int	@color	@color
ColorStateList	@color	@colorStateList

2.4 事件处理

  Data Binding 允许您编写表达式来处理 View 分发的事件（例如，onClick() 方法）。事件的属性名由监听器（Listener）方法的名称确定，不过也存在一些例外。例如，View.OnClickListener 有一个 onClick() 方法，因此这个事件的属性是 android:onClick。

  对于点击事件，有一些特殊的事件处理程序需要一个不同于 android:onClick 的属性来避免冲突。您可以使用以下属性来避免这些类型的冲突：

类	监听器设置者（Listener setter）	属性
SearchView	setOnSearchClickListener(View.OnClickListener)	android:onSearchClick
ZoomControls	setOnZoomInClickListener(View.OnClickListener)	android:onZoomIn
ZoomControls	setOnZoomOutClickListener(View.OnClickListener)	android:onZoomOut

  您可以使用以下机制来处理事件：

• 方法引用：在表达式中，您可以引用符合监听器方法签名的方法。当表达式的值为方法引用时，Data Binding 将方法引用和所有者对象包装在监听器中，并在目标 View 上设置该监听器。如果表达式的值为 null，Data Binding 不会创建监听器，并将目标 View 的监听器设置为 null。
• Listener 绑定：即 lambda 表达式，在事件发生时进行计算。Data Binding 总是会创建一个监听器，并将它设置给 View。当分发事件时，监听器计算 lambda 表达式。

2.4.1 方法引用

  事件可以直接绑定到处理方法，类似于可以将 android:onClick 分配给 Activity 中的一个方法。绑定表达式是在编译时处理，如果该方法不存在或者其签名不正确，则会出现编译错误。

  在方法应用中，当数据被绑定时会创建实际的监听器实现。

  若要将事件分配给它的处理程序，请使用普通的绑定表达式，该表达式的值就是要调用的方法名。例如：

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

  绑定表达式可以将 View 的点击监听器分配给 onClickFriend() 方法，如下所示：

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

注意：表达式中方法的签名必须与监听器对象中方法的签名完全匹配。即方法的参数必须与事件监听器的参数匹配，并且返回相同的类型（除非返回的是 void）。

2.4.2 监听器绑定

  监听器绑定是在事件发生时运行的绑定表达式。它们与方法引用类似，但是它们允许您运行任意的数据绑定表达式。这个特性在 Android Gradle 插件的 2.0 以及更高版本中支持。

  在方法引用中，方法的参数必须与事件监听器的参数匹配。在监听器绑定中，只要您的返回值必须与监听器的返回值匹配（除非返回的是 void）。例如，考虑下面的拥有 onSaveClick() 方法的 presenter 类：

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

  然后，可以将点击事件绑定到 onSaveClick() 方法，如下所示：

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

  当在表达式中使用回调时，Data Binding 会自动创建必要的监听器并为事件注册它。当 View 触发事件时，Data Binding 会计算给定的表达式。与常规绑定表达式一样，在计算监听器表达式时，将得到 null，并且是线程安全的。

  在上面的例子中，我们没有定义传递给 onClick(View) 的 view 参数。监听器绑定为监听器参数提供了两种选择：忽略方法的所有参数，或命名所有参数。如果您想命名参数，可以在表达式中使用它们。例如，上面的表达式可以写成下面的形式：

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

  或者，如果您想在表达式中使用参数，则可以按照下面的方式工作：

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

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

  您可以使用带有多个参数的 lambda 表达式：

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

  如果您正在监听的事件返回的值的类型不是 void，那么您的表达式也必须返回相同类型的值。例如，如果您想监听长按事件，那么表达式应返回布尔值。

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

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

  如果由于 null 对象而无法计算表达式，那么 Data Binding 将返回该类型的默认值。例如，引用类型为 null，int 为 0，boolean 为 false 等等。

  如果需要使用带判断的表达式（例如，三元表达式），您可以将 void 作为符号使用。

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

  监听器表达式功能非常强大，并且可以使您的代码易于阅读。另一方面，包含复杂表达式的监听器会使您的布局难以阅读和维护。这些表达式应该像将可用数据从 UI 传递到回调方法一样简单。您应该在回调方法中实现业务逻辑。

2.5 Import、Variable 和 Include

  Data Binding 库提供 Import、Variable 和 Include 等特性。Import 使得很容易在布局文件中引用类。Variable 允许您描述可用于 Binding 表达式的属性。Include 让您在整个 App 中重用复杂布局。

2.5.1 Import

2.5.1.1 如何导入类

  Import 允许您在布局文件中轻松引用类，就在代码中一样。在 data 元素中可以包含 0 个或多个 import 元素。下面的示例将 View 类导入布局文件：

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

2.5.1.2 类型别名

  当存在类名冲突时，可以为一个类设置别名。下面的示例为 com.example.real.estate.View 设置别名 Vista：

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

  您可以使用 Vista 引用 com.example.real.estate.View。

2.5.1.3 使用导入的类

• 用作变量和表达式的类型引用

  下面的示例展示了将 User 和 List 用作变量的类型：

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

• 进行类型强制转换

  下面的示例将 connnection 属性强制转换为 User 类型：

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

• 引用导入类的 static 字段和方法

  下面的示例如何引用 View 类的 VISIBLE 和 GONE 常量：

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

  下面的示例引用了 MyStringUtils 类的 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"/>
  

2.5.2 Variable（变量）

  可以在 data 元素中添加多个 variable 元素。每个 variable 元素描述一个可以在布局上设置的属性，可以在 Binding 表达式中使用这个 variable。下面的示例描述了 user、image 和 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>

  在编译时检查变量类型，因此如果一个变量实现了 Observable 接口或者是一个可观察集合，则应该反映在类型中。如果变量是没有实现 Observable 接口的基类和接口，则不会观察这个变量。

  当各种配置（例如，横屏和竖屏）使用不同布局文件时，Variable 就会被组合起来。因此在这些布局文件中不能出现变量命名冲突。

  在生成的 Binding 类中，每个 Variable 都有 setter 和 getter 方法。在调用 setter 方法前，变量拥有默认值（例如，引用类型为 null，int 类型为 0，boolean 类型为 false）。

  将会自动生成一个名为 context 的特殊 Variable。这个 context 的值是通过根 View 的 getContext() 方法获取。如果显示声明了一个名为 context 的 Variable，将会覆盖自动生成的 context 变量。

2.5.3 Include

  可以将 Variable 传入 Include 的布局文件中。例如：

<layout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:bind="http://schemas.android.com/apk/res-auto">
   <data>
       <variable name="testUser" 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="@{testUser}"/>
       <include layout="@layout/contact"
           bind:user="@{testUser}"/>
   LinearLayout>
layout>

  使用 bind:user="@{testUser}" 可以将变量 testUser 传递给 name.xml 和 contact.xml 布局文件中的变量 user。

  Data Binding 不支持 include 作为 merge 元素的直接子元素。例如，不支持以下布局：

<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>
       <include layout="@layout/name"
           bind:user="@{user}"/>
       <include layout="@layout/contact"
           bind:user="@{user}"/>
   merge>
layout>

三、使用可观察的数据对象

  可观察性是指一个对象在其数据发生变化时通知其他对象的能力。Data Binding 库允许您使对象（Object）、字段（Field）或集合（Collection）可观察。

  任何 plain-old 对象（POJO）都可用于 Data Binding，但是修改对象不会自动更新 UI。Data Binding 能够让数据对象拥有当数据发生变化时通知其他对象的能力，即监听器（Listener）。有三种不同类型的可观察类：对象、字段和集合。

  当可观察数据对象被绑定到 UI 后，如果这个数据对象的属性发生变化，UI 将自动更新。

3.1 可观察字段

  提供泛型 ObservableField 类和一些使字段可观察的原始具体类：ObservableBoolean、ObservableByte、ObservableChar、ObservableShort、ObservableInt、ObservableLong、ObservableFloat、ObservableDouble 和 ObservableParcelable。

  可观察字段是具有单个字段的自包含可观察对象。原始的版本在访问期间避免装箱和解箱。要使用此机制，请在 Java 编程语言中创建一个 public final 属性，如下面的例子所示：

private static class User {
    public final ObservableField<String> firstName = new ObservableField<>();
    public final ObservableField<String> lastName = new ObservableField<>();
    public final ObservableInt age = new ObservableInt();
}

  使用 get() 和 get() 方法访问字段值，如下所示：

user.firstName.set("Google");
int age = user.age.get();

注意：在 Android Studio 3.1 以及更高版本中，可以使用 LiveData 对象替换可观察字段。

3.2 可观察集合

  一些 App 使用动态结构来保存数据。可观察集合允许访问使用 Key 的这类结构。

3.2.1 ObservableArrayMap

  当 Key 是引用类型（例如，String）时，可以使用 ObservableArrayMap。如下面的例子所示：

ObservableArrayMap<String, Object> user = new ObservableArrayMap<>();
user.put("firstName", "Google");
user.put("lastName", "Inc.");
user.put("age", 17);

  在布局文件中，可以使用 String Key 找到 Map，如下所示：

<data>
    <import type="android.databinding.ObservableMap"/>
    <variable name="user" type="ObservableMap"/>
data>
…
<TextView
    android:text="@{user.lastName}"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"/>
<TextView
    android:text="@{String.valueOf(1 + (Integer)user.age)}"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"/>

3.2.2 ObservableArrayList

  当 Key 是整数时，可以使用 ObservableArrayMap。如下所示：

ObservableArrayList<Object> user = new ObservableArrayList<>();
user.add("Google");
user.add("Inc.");
user.add(17);

  在布局中，可以通过索引访问列表，如下所示：

<data>
    <import type="android.databinding.ObservableList"/>
    <import type="com.example.my.app.Fields"/>
    <variable name="user" type="ObservableList