绑定适配器

绑定适配器负责进行适当的框架调用以设置值。一个例子是设置属性值，例如调用 setText() 方法。另一个例子是设置事件监听器，例如调用 setOnClickListener() 方法。

数据绑定库允许您指定用于设置值的调用的方法，提供您自己的绑定逻辑，并使用适配器指定返回对象的类型。

设置属性值

每当绑定值发生变化时，生成的绑定类都必须在具有绑定表达式的视图上调用 setter 方法。您可以让数据绑定库自动确定方法，也可以显式声明方法或提供自定义逻辑来选择方法。

自动方法选择

对于名为 example 的属性，库会自动查找接受兼容类型作为参数的方法 setExample(arg)。不会考虑属性的命名空间。在搜索方法时，仅使用属性名称和类型。

例如，给定 android:text="@{user.name}" 表达式，库将查找一个接受 user.getName() 返回的类型的 setText(arg) 方法。如果 user.getName() 的返回类型是 String，库将查找一个接受 String 参数的 setText() 方法。如果表达式返回一个 int，库将搜索一个接受 int 参数的 setText() 方法。表达式必须返回正确的类型。如果需要，您可以强制转换返回值。

即使没有与给定名称匹配的属性，数据绑定也能正常工作。您可以使用数据绑定为任何 setter 创建属性。例如，支持类 DrawerLayout 没有属性，但它有许多 setter。以下布局会自动使用 setScrimColor(int) 和 addDrawerListener(DrawerListener) 方法分别作为 app:scrimColor 和 app:drawerListener 属性的 setter。

<androidx.drawerlayout.widget.DrawerLayout
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:scrimColor="@{@color/scrim}"
    app:drawerListener="@{fragment.drawerListener}">

指定自定义方法名称

某些属性的 setter 与名称不匹配。在这些情况下，可以使用 BindingMethods 注解将属性与 setter 关联。该注解用于类，可以包含多个 BindingMethod 注解，每个注解对应一个重命名的方法。绑定方法是您可以添加到应用程序中任何类的注解。

在以下示例中，android:tint 属性与 setImageTintList(ColorStateList) 方法关联，而不是 setTint() 方法。

Kotlin

@BindingMethods(value = [
    BindingMethod(
        type = android.widget.ImageView::class,
        attribute = "android:tint",
        method = "setImageTintList")])

Java

@BindingMethods({
       @BindingMethod(type = "android.widget.ImageView",
                      attribute = "android:tint",
                      method = "setImageTintList"),
})

通常，您不需要重命名 Android 框架类中的 setter。这些属性已经使用名称约定实现，以便自动查找匹配的方法。

提供自定义逻辑

某些属性需要自定义绑定逻辑。例如，android:paddingLeft 属性没有关联的 setter。相反，提供了 setPadding(left, top, right, bottom) 方法。使用 BindingAdapter 注解的静态绑定适配器方法允许您自定义如何调用属性的 setter。

Android 框架类的属性已经具有 BindingAdapter 注解。以下示例显示了 paddingLeft 属性的绑定适配器。

Kotlin

@BindingAdapter("android:paddingLeft")
fun setPaddingLeft(view: View, padding: Int) {
    view.setPadding(padding,
                view.getPaddingTop(),
                view.getPaddingRight(),
                view.getPaddingBottom())
}

Java

@BindingAdapter("android:paddingLeft")
public static void setPaddingLeft(View view, int padding) {
  view.setPadding(padding,
                  view.getPaddingTop(),
                  view.getPaddingRight(),
                  view.getPaddingBottom());
}

参数类型很重要。第一个参数确定与属性关联的视图的类型。第二个参数确定在给定属性的绑定表达式中接受的类型。

绑定适配器对于其他类型的自定义也很有用。例如，可以从工作线程调用自定义加载器来加载图像。

您还可以拥有接收多个属性的适配器，如下面的示例所示。

Kotlin

@BindingAdapter("imageUrl", "error")
fun loadImage(view: ImageView, url: String, error: Drawable) {
    Picasso.get().load(url).error(error).into(view)
}

Java

@BindingAdapter({"imageUrl", "error"})
public static void loadImage(ImageView view, String url, Drawable error) {
  Picasso.get().load(url).error(error).into(view);
}

您可以在布局中使用适配器，如下面的示例所示。请注意，@drawable/venueError 指的是应用程序中的资源。将资源用 @{} 包裹使其成为有效的绑定表达式。

<ImageView app:imageUrl="@{venue.imageUrl}" app:error="@{@drawable/venueError}" />

如果 imageUrl 和 error 用于 ImageView 对象，imageUrl 是字符串，error 是 Drawable，则会调用适配器。如果您希望在设置任何属性时调用适配器，请将适配器的可选 requireAll 标志设置为 false，如下面的示例所示。

Kotlin

@BindingAdapter(value = ["imageUrl", "placeholder"], requireAll = false)
fun setImageUrl(imageView: ImageView, url: String?, placeHolder: Drawable?) {
    if (url == null) {
        imageView.setImageDrawable(placeholder);
    } else {
        MyImageLoader.loadInto(imageView, url, placeholder);
    }
}

Java

@BindingAdapter(value={"imageUrl", "placeholder"}, requireAll=false)
public static void setImageUrl(ImageView imageView, String url, Drawable placeHolder) {
  if (url == null) {
    imageView.setImageDrawable(placeholder);
  } else {
    MyImageLoader.loadInto(imageView, url, placeholder);
  }
}

绑定适配器方法可以在其处理程序中获取旧值。获取旧值和新值的的方法必须首先声明所有属性的旧值，然后声明新值，如下面的示例所示。

Kotlin

@BindingAdapter("android:paddingLeft")
fun setPaddingLeft(view: View, oldPadding: Int, newPadding: Int) {
    if (oldPadding != newPadding) {
        view.setPadding(newPadding,
                    view.getPaddingTop(),
                    view.getPaddingRight(),
                    view.getPaddingBottom())
    }
}

Java

@BindingAdapter("android:paddingLeft")
public static void setPaddingLeft(View view, int oldPadding, int newPadding) {
  if (oldPadding != newPadding) {
      view.setPadding(newPadding,
                      view.getPaddingTop(),
                      view.getPaddingRight(),
                      view.getPaddingBottom());
   }
}

事件处理程序只能与接口或只有一个抽象方法的抽象类一起使用，如下面的示例所示。

Kotlin

@BindingAdapter("android:onLayoutChange")
fun setOnLayoutChangeListener(
        view: View,
        oldValue: View.OnLayoutChangeListener?,
        newValue: View.OnLayoutChangeListener?
) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
        if (oldValue != null) {
            view.removeOnLayoutChangeListener(oldValue)
        }
        if (newValue != null) {
            view.addOnLayoutChangeListener(newValue)
        }
    }
}

Java

@BindingAdapter("android:onLayoutChange")
public static void setOnLayoutChangeListener(View view, View.OnLayoutChangeListener oldValue,
       View.OnLayoutChangeListener newValue) {
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
    if (oldValue != null) {
      view.removeOnLayoutChangeListener(oldValue);
    }
    if (newValue != null) {
      view.addOnLayoutChangeListener(newValue);
    }
  }
}

在您的布局中使用此事件处理程序，如下所示。

<View android:onLayoutChange="@{() -> handler.layoutChanged()}"/>

当侦听器具有多个方法时，必须将其拆分为多个侦听器。例如，View.OnAttachStateChangeListener 有两个方法：onViewAttachedToWindow(View) 和 onViewDetachedFromWindow(View)。库提供了两个接口来区分它们各自的属性和处理程序。

Kotlin

// Translation from provided interfaces in Java:
@TargetApi(Build.VERSION_CODES.HONEYCOMB_MR1)
interface OnViewDetachedFromWindow {
    fun onViewDetachedFromWindow(v: View)
}

@TargetApi(Build.VERSION_CODES.HONEYCOMB_MR1)
interface OnViewAttachedToWindow {
    fun onViewAttachedToWindow(v: View)
}

Java

@TargetApi(VERSION_CODES.HONEYCOMB_MR1)
public interface OnViewDetachedFromWindow {
  void onViewDetachedFromWindow(View v);
}

@TargetApi(VERSION_CODES.HONEYCOMB_MR1)
public interface OnViewAttachedToWindow {
  void onViewAttachedToWindow(View v);
}

由于更改一个侦听器可能会影响另一个侦听器，因此您需要一个适用于任何属性或两个属性的适配器。您可以在注解中将 requireAll 设置为 false，以指定不需要为每个属性分配绑定表达式，如下面的示例所示。

Kotlin

@BindingAdapter(
        "android:onViewDetachedFromWindow",
        "android:onViewAttachedToWindow",
        requireAll = false
)
fun setListener(view: View, detach: OnViewDetachedFromWindow?, attach: OnViewAttachedToWindow?) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB_MR1) {
        val newListener: View.OnAttachStateChangeListener?
        newListener = if (detach == null && attach == null) {
            null
        } else {
            object : View.OnAttachStateChangeListener {
                override fun onViewAttachedToWindow(v: View) {
                    attach.onViewAttachedToWindow(v)
                }

                override fun onViewDetachedFromWindow(v: View) {
                    detach.onViewDetachedFromWindow(v)
                }
            }
        }

        val oldListener: View.OnAttachStateChangeListener? =
                ListenerUtil.trackListener(view, newListener, R.id.onAttachStateChangeListener)
        if (oldListener != null) {
            view.removeOnAttachStateChangeListener(oldListener)
        }
        if (newListener != null) {
            view.addOnAttachStateChangeListener(newListener)
        }
    }
}

Java

@BindingAdapter({"android:onViewDetachedFromWindow", "android:onViewAttachedToWindow"}, requireAll=false)
public static void setListener(View view, OnViewDetachedFromWindow detach, OnViewAttachedToWindow attach) {
    if (VERSION.SDK_INT >= VERSION_CODES.HONEYCOMB_MR1) {
        OnAttachStateChangeListener newListener;
        if (detach == null && attach == null) {
            newListener = null;
        } else {
            newListener = new OnAttachStateChangeListener() {
                @Override
                public void onViewAttachedToWindow(View v) {
                    if (attach != null) {
                        attach.onViewAttachedToWindow(v);
                    }
                }
                @Override
                public void onViewDetachedFromWindow(View v) {
                    if (detach != null) {
                        detach.onViewDetachedFromWindow(v);
                    }
                }
            };
        }

        OnAttachStateChangeListener oldListener = ListenerUtil.trackListener(view, newListener,
                R.id.onAttachStateChangeListener);
        if (oldListener != null) {
            view.removeOnAttachStateChangeListener(oldListener);
        }
        if (newListener != null) {
            view.addOnAttachStateChangeListener(newListener);
        }
    }
}

上面的示例稍微复杂一些，因为 View 类使用 addOnAttachStateChangeListener() 和 removeOnAttachStateChangeListener() 方法，而不是 OnAttachStateChangeListener 的 setter 方法。 android.databinding.adapters.ListenerUtil 类有助于跟踪这些侦听器，以便可以在绑定适配器中移除它们。

对象转换

自动对象转换

当绑定表达式返回 Object 时，库会选择用于设置属性值的方法。 Object 会被强制转换为所选方法的参数类型。此行为在使用 ObservableMap 类存储数据的应用程序中很方便，如下面的示例所示。

<TextView
   android:text='@{userMap["lastName"]}'
   android:layout_width="wrap_content"
   android:layout_height="wrap_content" />

表达式中的 userMap 对象返回一个值，该值会自动强制转换为用于设置 android:text 属性值的 setText(CharSequence) 方法中找到的参数类型。如果参数类型不明确，请在表达式中强制转换返回值类型。

自定义转换

在某些情况下，特定类型之间需要自定义转换。例如，视图的 android:background 属性期望一个 Drawable，但指定的 color 值是整数。以下示例显示了一个期望 Drawable 的属性，但提供了一个整数。

<View
   android:background="@{isError ? @color/red : @color/white}"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

无论何时期望 Drawable 并返回整数，请将 int 转换为 ColorDrawable。要执行转换，请使用带有 BindingConversion 注解的静态方法，如下所示。

Kotlin

@BindingConversion
fun convertColorToDrawable(color: Int) = ColorDrawable(color)

Java

@BindingConversion
public static ColorDrawable convertColorToDrawable(int color) {
    return new ColorDrawable(color);
}

但是，绑定表达式中提供的值类型必须一致。您不能在同一表达式中使用不同的类型，如下面的示例所示。

// The @drawable and @color represent different value types in the same
// expression, which causes a build error.
<View
   android:background="@{isError ? @drawable/error : @color/white}"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>

其他资源

要详细了解数据绑定，请参阅以下资源。

示例

Codelabs

博客文章