Adaptadores de vinculação

Os adaptadores de vinculação são responsáveis por fazer as chamadas de framework adequadas para definir valores. Um exemplo é definir um valor de propriedade, como chamar o método setText(). Outro exemplo é definir um listener de eventos, como chamar o método setOnClickListener().

A Biblioteca de vinculação de dados permite especificar a chamada de método para definir um valor, fornecer sua própria lógica de vinculação e especificar o tipo do objeto retornado usando adaptadores.

Definir valores de atributos

Sempre que um valor vinculado muda, a classe de vinculação gerada precisa chamar um método setter na visualização com a expressão de vinculação. Você pode deixar que a biblioteca de vinculação de dados determine o método automaticamente ou declarar explicitamente o método ou fornecer uma lógica personalizada para selecionar um método.

Seleção automática de método

Para um atributo chamado example, a biblioteca encontra automaticamente o método setExample(arg) que aceita tipos compatíveis como argumento. O namespace do atributo não é considerado. Somente o nome do atributo e o tipo são usados ao pesquisar um método.

Por exemplo, considerando a expressão android:text="@{user.name}", a biblioteca procura um método setText(arg) que aceite o tipo retornado por user.getName(). Se o tipo de retorno de user.getName() for String, a biblioteca vai procurar um método setText() que aceite um argumento String. Se a expressão retornar um int, a biblioteca vai procurar um método setText() que aceite um argumento int. A expressão precisa retornar o tipo correto. É possível transmitir o valor de retorno, se necessário.

A vinculação de dados funciona mesmo que não exista atributo com o nome específico. É possível criar atributos para qualquer setter usando a vinculação de dados. Por exemplo, a classe de suporte DrawerLayout não tem atributos, mas tem muitos setters. O layout a seguir usa automaticamente os métodos setScrimColor(int) e addDrawerListener(DrawerListener) como o setter para os atributos app:scrimColor e app:drawerListener, respectivamente:

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

Especificar um nome de método personalizado

Alguns atributos têm setters que não correspondem ao nome. Nessas situações, um atributo pode ser associado ao setter usando a anotação BindingMethods. A anotação é usada com uma classe e pode conter várias anotações BindingMethod, uma para cada método renomeado. Os métodos de vinculação são anotações que podem ser adicionadas a qualquer classe no app.

No exemplo a seguir, o atributo android:tint está associado ao método setImageTintList(ColorStateList), e não ao método 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"),
})

Normalmente, não é necessário renomear setters em classes do framework do Android. Os atributos já estão implementados usando a convenção de nomenclatura para encontrar automaticamente os métodos correspondentes.

Fornecer uma lógica personalizada

Alguns atributos precisam de uma lógica de vinculação personalizada. Por exemplo, não há um setter associado para o atributo android:paddingLeft. Em vez disso, o método setPadding(left, top, right, bottom) é fornecido. Um método de adaptador de vinculação estático com a anotação BindingAdapter permite personalizar como um setter de um atributo é chamado.

Os atributos das classes do framework do Android já têm anotações BindingAdapter. O exemplo abaixo mostra o adaptador de vinculação para o atributo 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());
}

Os tipos de parâmetro são importantes. O primeiro parâmetro determina o tipo da visualização associada ao atributo. O segundo parâmetro determina o tipo aceito na expressão de vinculação para o atributo fornecido.

Os adaptadores de vinculação também são úteis para outros tipos de personalização. Por exemplo, um carregador personalizado pode ser chamado de uma linha de execução de worker para carregar uma imagem.

Também é possível ter adaptadores que recebem vários atributos, como mostrado no exemplo a seguir:

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

É possível usar o adaptador no layout, como mostrado no exemplo a seguir. Observe que @drawable/venueError se refere a um recurso no app. Colocar o recurso entre @{} o torna uma expressão de vinculação válida.

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

O adaptador será chamado se imageUrl e error forem usados para um objeto ImageView, imageUrl for uma string e error for um Drawable. Se você quiser que o adaptador seja chamado quando qualquer um dos atributos for definido, defina a flag opcional requireAll do adaptador como false, conforme mostrado no exemplo a seguir:

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

Os métodos do adaptador de vinculação podem usar os valores antigos nos gerenciadores. Um método que usa valores antigos e novos precisa declarar primeiro todos os valores antigos para os atributos, seguidos pelos novos valores, como mostrado no exemplo a seguir:

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

Os manipuladores de eventos só podem ser usados com interfaces ou classes abstratas com um método abstrato, como mostrado no exemplo abaixo:

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

Use esse manipulador de eventos no seu layout da seguinte forma:

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

Quando um listener tem vários métodos, ele precisa ser dividido em vários listeners. Por exemplo, View.OnAttachStateChangeListener tem dois métodos: onViewAttachedToWindow(View) e onViewDetachedFromWindow(View). A biblioteca oferece duas interfaces para diferenciar os atributos e os gerenciadores deles:

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

Como a mudança de um listener pode afetar o outro, você precisa de um adaptador que funcione para um ou para os dois atributos. É possível definir requireAll como false na anotação para especificar que nem todos os atributos precisam receber uma expressão de vinculação, como mostrado no exemplo a seguir:

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

O exemplo acima é um pouco complicado porque a classe View usa os métodos addOnAttachStateChangeListener() e removeOnAttachStateChangeListener() em vez de um método setter para OnAttachStateChangeListener. A classe android.databinding.adapters.ListenerUtil ajuda a acompanhar esses listeners para que eles possam ser removidos no adaptador de vinculação.

Conversões de objeto

Conversão automática de objetos

Quando um Object é retornado de uma expressão de vinculação, a biblioteca seleciona o método usado para definir o valor da propriedade. O Object é transmitido para um tipo de parâmetro do método escolhido. Esse comportamento é conveniente em apps que usam a classe ObservableMap para armazenar dados, como mostrado no exemplo a seguir:

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

O objeto userMap na expressão retorna um valor, que é automaticamente transmitido para o tipo de parâmetro encontrado no método setText(CharSequence) usado para definir o valor do atributo android:text. Se o tipo de parâmetro for ambíguo, converta o tipo de retorno na expressão.

Conversões personalizadas

Em algumas situações, uma conversão personalizada é necessária entre tipos específicos. Por exemplo, o atributo android:background de uma visualização espera um Drawable, mas o valor color especificado é um número inteiro. O exemplo a seguir mostra um atributo que espera um Drawable, mas um número inteiro é fornecido:

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

Sempre que um Drawable for esperado e um número inteiro for retornado, converta o int em um ColorDrawable. Para realizar a conversão, use um método estático com uma anotação BindingConversion, da seguinte maneira:

Kotlin

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

Java

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

No entanto, os tipos de valores fornecidos na expressão de vinculação precisam ser consistentes. Não é possível usar tipos diferentes na mesma expressão, como mostrado no exemplo a seguir:

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

Outros recursos

Para saber mais sobre a vinculação de dados, consulte os recursos a seguir.

Amostras

Postagens do blog