繫結配接器

繫結轉接器負責進行適當的架構呼叫,以設定值。例如設定屬性值,像是呼叫 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 物件會傳回值,該值會自動轉換為 setText(CharSequence) 方法中用於設定 android:text 屬性值的參數類型。如果參數類型不明確,請在運算式中轉換傳回類型。

自訂轉換

在某些情況下,特定類型之間需要自訂轉換。舉例來說,檢視畫面的 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"/>

其他資源

如要進一步瞭解資料繫結,請參閱下列資源。

範例

網誌文章