android开源数据绑定框架android-databinding

1, github地址:

https://github.com/LightSun/android-databinding

插件地址： https://github.com/LightSun/android-databinding-plugin.

2, 为什么我要写这样一个框架。

自Google2015 io 大会后google官方出了一个数据绑定框架(虽然它目前有些问题).

它的工作原理是通过在layout 文件中数据绑定的配置，使得会在java中少写些代码，以达到类似javaweb端数据绑定的效果。

但是个人人为在layout中写数据绑定的东西不好。为什么呢？因为那样会使得layout文件的可读性大受影响。在javaweb的时候我就深深的体会到了,

不同的工作就该分别放置所以我很厌恶这种方式。and我写的这个框架配置文件主要在另一个文件夹下res/raw目录下。

3, 本框架特点及介绍

支持常用的数据绑定。 比如背景，图片(圆角边框，默认图同样支持)，文字，文字颜色等。以及ListView/RecyclerView/GridView…etc. adapter数据的绑定。自定义属性，自定义事件. xml schema约束支持，开源插件支持

丰富的表达式expression支持 :

支持java 方法，字段，数组的调用 (包括任意嵌套), 支持dp, sp （eg: '12dp'）,
支持#颜色(eg: "#ff0000") , 支持当前项目资源的引用 (eg: (@dimen/corner_size)或 R.drawable.ic_default ),
不支持赋值表达式。
Ps: 注意调用的过程中不要忘记xml中申明<variable> 和 <import> 下面会介绍。

1) 数据绑定xml配置文件的介绍

Root节点为 < DataBinding>.

@(1) DataBinding 子节点 < data> : 用于导入class和 声明一个变量的类型 。 eg:

这个定义了一个变量 imageParam, 它的classname 为com.heaven7.databinding.demo.samples.RoundImageBindTest$ImageParam,  eventHanlder同理。

Import节点: 表示导入了一个类，一般是静态方法或字段调用的时候使用。比如使用上面这个import后， 你就可以简单的使用Test.xxx 常量和静态方法了。
variable节点: type属性 表示是java bean还是callback.   Callback用于事件的绑定，必须定义.

@(2), 子节点< bind>

这个节点一般是所有属性绑定property/imageProperty的父节点。它有2个属性，id和referVariable. 这2个属性一般是互斥的。 所以不要同时使用.

id属性: 表示android view id的引用.  比如R.id.listview. 那么 id 就为 listview.
referVariable:  表示引用变量对应的对象

它有2种适用方式：

第一种,

<bind id="bt">
<property name="text" referVariable="user">@{user.username}</property>
<property name="textColor" referVariable="user" >user.male ? {@color/red} : {@color/random}</property>
</bind>

表明 将绑定属性text和textColor的值到 id为bt的控件上。

第2种:

<bind referVariable="user">
<property id ="bt2" name="text" >@{user.username}</property>
<property id ="bt3" name="text" >user.getNickname()</property>
</bind>

表示将表达式 user.username的值绑定到控件id = bt2 的 text属性上

将表达式 user.getNickname()的值绑定到控件id = bt3 的 text属性上

@(3) , bind子节点 < property>

它含有属性 id, name, referVariable.

id:

表示控件的id名称。

name:

表示要绑定的属性。

referVariable:

表示引用的变量

其中name是必须有的属性， referVariable是可选的。Id也是可选因为可以在bind元素节点声明id属性.

到此 android-databinding的基本绑定配置元素已说完。

@(4) , 绑定adapter的父节点 < bindAdapter>

含有属性： id, referVariable, selectMode

id :

表示要绑定adapter的控件id

referVariable

表示引用变量

selectMode

表示adapter item的选择模式，单选1 ，多选2

此属性是配合 ISelectable接口使用的。所以 referVariable引用 Bean Class必须实现 ISelectable接口。关于选择模式稍后将细作说明。

bindAdapter子节点 < item>

用于绑定1种或多种item， 1个item节点表示1种item, 以此类推。 它有3个属性.

layout, tag , referVariable.

Layout:

表示当前item绑定的layout id. ，必须

referVariable

表示引用变量 ，可选

tag

表示 给Item打一个1标签, 在多item布局时必须, 此时bean 的class 必须实现 ITag接口。

Item节点下的 < property>

这个节点下的 property 将作用于item的根布局上，所以是不用申明id属性的。只要name属性 以及 表达式即可。比如：

<item layout="item_xxx" tag = "1" referVariable="itemHandler">
<propertyname="onLongClick">itemHandler.onItemLongClick(user)</property>

<property name="onClick" >itemHandler.onItemClick(user)</property>
</item>

即给这个item的根布局添加2个事件。onClick 和 onLongClick .

关于item 其他view 绑定等同于< bind> 节点的说明.

图片属性的绑定. < imageProperty>介绍.

含有3个属性： id, type, referVariable 和 roundSize，borderWidth，borderColor，url，default，errorResId 6个子节点。

type

只有3个值， round/oval/circle其他属性之前类似的说过了，我就不再说了。

roundSize :

圆角大小 只有在type = “round”时有效.

borderWidth:

边框宽度

borderColor:

边框颜色

url

网络图片地址

default

默认图片。支持 drawable ,bitmap, resource id

errorResId

只支持 图片iresource id类型。

参考配置：

<bind id="eniv2">
<property name="onClick" referVariable="eventHandler" > eventHandler.onClickImage()</property>
<imageProperty type="round" referVariable="imageParam">  <!-- round / circle / oval -->
<roundSize>{@dimen/corner_size}</roundSize>
<borderWidth>5dp</borderWidth>
<borderColor>#ff0000</borderColor>

<url>imageParam.link</url>
<default>{@drawable/ic_default}</default>     <!-- support drawable ,bitmap,  resource id -->
<errorResId>R.drawable.ic_error</errorResId>  <!-- only support resource id -->

</imageProperty>
</bind>

2) , 标准的属性（包含事件属性）

//event name
String ON_CLICK                =    "onClick";
String ON_LONG_CLICK           =    "onLongClick";
String TEXT_CHANGE_BEFORE      =    "textChange_before";
String TEXT_CHANGE             =    "textChange";
String TEXT_CHANGE_AFTER       =    "textChange_after";
String ON_FOCUS_CHANGE         =    "onFocusChange";

// String ON_TOUCH                =    "onTouch";

//common name
String BACKGROUND              =    "background";
String BACKGROUND_COLOR        =    "backgroundColor";
String BACKGROUND_RES          =    "background_res";

String TEXT                    =    "text";
String TEXT_RES                =    "text_res";

String TEXT_COLOR              =    "textColor";
String TEXT_COLOR_RES          =    "textColor_res";
String TEXT_COLOR_STATE        =    "textColor_state";
String TEXT_COLOR_STATE_RES    =    "textColor_stateRes";
String TEXT_SIZE               =    "textSize";
String TEXT_SIZE_RES           =    "textSize_res";

String VISIBILITY              =    "visibility";
//image
String IMGAE_URL               =    "img_url";
String IMGAE_BITMAP            =    "img_bitmap";
String IMGAE_DRAWABLE          =    "img_drawable";
String IMGAE_ROUND_BUILDER     =    "img_round_builder";

3) 绑定自定义属性（view child）说明

含义：绑定一个自定义的属性到 指定的控件(view 子类) 上。

如何使用？

类似java bean.比如事件名称为 user. 那么 一定要有对应的方法： setUser，

参数可以接收 表达式的值即可.

4), 事件绑定详细说明.（包含自定义）

比如你要绑定onClickUser的方法到 onClick事件上。那么data-binding的 property配置 如下:

<property name="onClick" referVariable="user,mainHanlder" >mainHanlder. onClickUser(user)</property>

对应的对象绑定的方法如下：

public void onClickUser (View v,User user)

@(1), 事件绑定到的对象方法, 参数说明

事件的第一个参数一定是 View类型. 自定义的参数都是按顺序放置在最末尾的。 示例：

比如我要监听EditText 文本变化的onTextChanged. 原本android sdk的标准参数是 (CharSequence s, int start, int count, int after)

而在本框架中 对应onTextChanged的方法参数 是这样的：

(View v, CharSequence s, int start, int before, int count)

名字可任意写, 对应即可 .

@(2) adapter中item事件绑定的不同之处

为了方便大家的使用我封装好了一个标准的item内的事件参数类型。当然同样支持

传递其他对象，按顺序放置于末尾，你需要在data-binding的xml中配置。

(View v, Integer position,ImageInfo item, AdapterManager<?> am)

第1个参数 代表绑定该事件的view,

第2个参数 表示item的position属性

第3个参数 表示数据的 bean对象。你绑定的什么类型就写什么类型。

第4个参数 是AdapterManager , 这个对象是做什么的呢？

答案就是方便notifyDataSetChanged()等方法的调用. 当然还有操作选择状态的SelectHelper （支持单选,多选）. 和 IHeaderFooterManager. 通过get方式可以获取。

IHeaderFooterManager 目前只适用于 RecyclerView的adapter.

AdapterManager 如图：



它除了notifyXxx方法外还提供了 ‘crud’item 数据的方法。这些是会自动调用notify的。所以你不用 额外调用了。

@(3), 自定义事件注册器

ListenerFactory 这个类主要是注册事件的，如下这个，默认已经注册好了OnClick ,OnLongClick .Text改变监听

static{
sRegistedListenerMap = new SparseArray<String>();

registEventListener(PropertyNames.ON_CLICK      , OnClickListenerImpl.class);
registEventListener(PropertyNames.ON_LONG_CLICK , OnLongClickListenerImpl.class);
registEventListener(PropertyNames.TEXT_CHANGE  , TextWatcherImpl.OnTextChangeImpl.class);
registEventListener(PropertyNames.TEXT_CHANGE_AFTER  , TextWatcherImpl.AfterTextChangeImpl.class);
registEventListener(PropertyNames.TEXT_CHANGE_BEFORE, TextWatcherImpl.BeforeTextChangeImpl.class);

}

/** the class clazz must have empty constructor */
public static void registEventListener(String propertyName,Class<?> clazz){
sRegistedListenerMap.put(propertyName.hashCode(),clazz.getName());
}

@(4) 关于事件和属性绑定的方法最好都不要重载，否则很可能绑定数据失败.

Ps: 本来onLongClick事件的返回值一定是boolean 类型， 但我为了大家方便。

OnLongClick事件绑定的返回值可以为 void哦 （相当于true –> 消耗掉事件）。

4, 调用api说明

调用的入口api 均在 IDataBinder中声明. 下面是简要说明，具体见github. 实现类DataBinder.

/**
* 重置 ，重置后所有缓存的数据将丢失
*/
void reset();

/**

将指定的数据datas绑定到属性名称为propertyName的指定控件id上
*/
void bind(int id, String propertyName, boolean cacheData, Object... datas);

/**
* 绑定数据到指定的控件上。
*/
void bind(int id, boolean cacheData, Object... datas);

/**  绑定数据到多个控件上。
*/
void bind(Object data, int... ids);

/**
绑定数据到多个控件上
*/
void bind(String variable, Object data, int... ids);

/**
通知数据发生改变。不适用于adapter
*/
void notifyDataSetChanged(int viewId);
/**
通知指定属性的数据发生改变。不适用于adapter

*/
void notifyDataSetChanged(int viewId, String propertyName);

/**
绑定 adpter到指定adapterview 上。当前支持AdapterView 子类and RecycleVriew ,返回的AdapterManager用于管理adapter.
详见 @(2)  adapter中item事件绑定的不同之处
*/
< T extends ISelectable> AdapterManager<T> bindAdapter(int adapterViewId, List<T> data,Object...extras ) ;

选择模式 帮助类->SelectHeper说明, 方法如下图:



这个用于 搭配 实现了ISelectable接口的bean对象。 在本框架中是必须的。

这内部都是会自动调用notify, 除方法clearSelectedPositions().

只适用于单选模式的方法：

public void setSelected(int position)  选中
public void setUnselected(int position) 反选中

public  T getSelectedItem()    获取选中的item
public int getSelectedPosition() 获取选中的位置

只适用于多选模式的方法

public void addUnselected(int position)     添加反选中
public void addSelected(int selectPosition) 添加选中

public  List<T> getSelectedItems()           获取选中的所有item
public List<Integer> getSelectedPositions()  获取选中的所有位置

单选多选均适用的方法：

public void unselect(int position)     反选指定position的item
public void clearAllSelected()         清除选中状态
public void toogleSelected(int position)    切换选中状态,即选中或反选指定的position

其他的还有 自己挖掘吧…哈哈…

5, demo

见项目主页或者github下的sample。

7 ,希望 and 其他说明

pdf文档下载：

http://download.csdn.net/detail/pkjjun2012/9352397

这个框架我会尽力维护的，大家有什么问题或者好的建议可以到群里交流 或者 加我qq 978136772也可以的。 （添加时， 加备注android-databinding哈）.

再次提醒哦：

关于数据绑定的method 不要有重载方法， 否则很可能导致数据绑定失败。

本人是个技术宅哈，喜欢程序 ，对java和android 比较擅长。喜欢研究各种框架。从javaweb就开始了。希望和大家共同学习交流。嗯，新建了个QQ交流群群号，389960698