docs(0.9.5): 增加注释和更新README中版本号

Signed-off-by: free46000 <[email protected]>

README.md

@@ -4,7 +4,7 @@
 - 直接使用业务中的实体类为`RecyclerView Adapter`设置数据源，不需要做任何封装
 - `RecyclerView Adapter`零编码，解放了复杂的`Adapter`类
 - 支持`DataBinding`，让你清爽的编写列表代码
-- 表单录入，懒加载，可复用，支持`DataBinding`、隐藏域、录入值是否改变
+- 支持Form表单录入，懒加载易复用，支持`DataBinding`、隐藏域、输入内容验证及是否变化
 
 ## 系列文章
 ### 用法与详解(详见下文)
@@ -22,7 +22,6 @@
 ![缩放后跨Recycler拖动](https://github.com/free46000/cloud/raw/master/multiitem/panel_drag_scale.gif)
 
 ## 下一步要做什么
-- 录入界面的复用和封装的demo代码（录入业务较多同学可以多多关注）
 - 思考动画分割线等一些功能封装
 
 ## 用法
@@ -41,7 +40,7 @@ allprojects {
 在`Module`中添加：
 ```
 dependencies {
-    compile 'com.github.free46000:MultiItem:0.9.4'
+    compile 'com.github.free46000:MultiItem:0.9.5'
 }
 ```
 

demo/src/main/java/com/freelib/multiitem/demo/InputActivity.java

@@ -5,21 +5,11 @@
 import android.support.v7.app.AppCompatActivity;
 import android.support.v7.widget.LinearLayoutManager;
 import android.support.v7.widget.RecyclerView;
-import android.widget.Button;
-import android.widget.Toast;
 
-import com.freelib.multiitem.adapter.BaseItemAdapter;
 import com.freelib.multiitem.adapter.InputItemAdapter;
-import com.freelib.multiitem.demo.bean.ImageBean;
-import com.freelib.multiitem.demo.bean.ImageTextBean;
-import com.freelib.multiitem.demo.bean.TextBean;
 import com.freelib.multiitem.demo.input.ItemEdit;
-import com.freelib.multiitem.demo.input.ItemInfo;
+import com.freelib.multiitem.demo.input.ItemInfoDataBind;
 import com.freelib.multiitem.demo.input.ItemNameAndSex;
-import com.freelib.multiitem.demo.viewholder.ImageAndTextManager;
-import com.freelib.multiitem.demo.viewholder.ImageViewManager;
-import com.freelib.multiitem.demo.viewholder.TextViewManager;
-import com.freelib.multiitem.item.HiddenItemInput;
 
 import org.androidannotations.annotations.AfterViews;
 import org.androidannotations.annotations.Click;
@@ -32,7 +22,6 @@
 
 /**
  * todo 增加验证Rule，怎样增加更灵活
- * todo ItemInfo利用Data bind增加数字统计，可以查看之前写文章的例子
  */
 @EActivity(R.layout.activity_input)
 public class InputActivity extends AppCompatActivity {
@@ -54,23 +43,30 @@ protected void initViews() {
         adapter = new InputItemAdapter();
         recyclerView.setAdapter(adapter);
         List<Object> list = new ArrayList<>();
-        //姓名和性别录入Item，一个录入item对应多个提交的{"name":"","sex":""}
+        //姓名和性别录入Item，一个录入item对应多个提交的值{"name":"","sex":""}
         list.add(new ItemNameAndSex());
         //正常的EditText录入Item
         list.add(new ItemEdit("height").setName("身高:"));
         list.add(new ItemEdit("weight").setName("体重:"));
         list.add(new ItemEdit("age").setName("年龄:"));
         list.add(new ItemEdit("default").setName("国家:").setDefValue("中国"));
-        list.add(new ItemInfo("info").setName("介绍:"));
+        //利用DataBinding的录入Item
+        list.add(new ItemInfoDataBind("info").setName("介绍:"));
+        //添加user id对应的隐藏域的Item（用户不可见）
         adapter.addHiddenItem("id", "隐藏域中携带id");
         adapter.setDataItems(list);
     }
 
     @Click(R.id.submit_btn)
     public void submit() {
+        //通过adapter.isValueChange()判断表单内容是否改变
+        //通过adapter.isValueValid()判断表单内容是否有效
+        //通过adapter.getInputJson()直接获取表单录入Json，还有获取录入Map的方法
         String tipTxt = "表单内容" + (adapter.isValueChange() ? "　已经　" : "　没有　") +
                 "被用户改变！\n表单　　" + (adapter.isValueValid() ? "　已经　" : "　没有　") +
                 "通过验证！\n自动组装的表单内容为：\n";
+
+        //表单内容json格式化后的字符串
         String valueTxt = null;
         try {
             valueTxt = adapter.getInputJson().toString(4);

demo/src/main/java/com/freelib/multiitem/demo/input/ItemEdit.java

@@ -22,7 +22,7 @@
 public class ItemEdit extends BaseItemInput<ItemEdit> {
     private EditText editText;
     private String name;
-    private String defValue;
+    private String defValue = "";
     private String hint;
 
 
@@ -33,6 +33,11 @@ public ItemEdit(String key) {
         super(key);
     }
 
+    /**
+     * 设置展示列名
+     *
+     * @param name 展示列名
+     */
     public ItemEdit setName(String name) {
         this.name = name;
         return this;
@@ -43,23 +48,31 @@ public ItemEdit setHint(String hint) {
         return this;
     }
 
+    /**
+     * 设置默认值
+     *
+     * @param defValue 默认值
+     */
     public ItemEdit setDefValue(String defValue) {
         this.defValue = defValue;
         return this;
     }
 
     @Override
     public String getValue() {
+        //返回录入的值，和{@link #getKey()}一起组装为Map  如果为null则不组装
         return editText == null ? defValue : editText.getText().toString();
     }
 
     @Override
     public boolean isValueValid() {
+        //是否验证有效，如Item不能为空，如用户手动更改，true:有效；false:无效
         return !TextUtils.isEmpty(getValue());
     }
 
     @Override
     protected void initInputView(BaseViewHolder holder) {
+        //初始化Input视图，由于Input视图不可以复用，所以直接在初始化视图时设置好相关内容即可
         TextView nameText = getView(holder.itemView, R.id.text);
         nameText.setText(name);
 

demo/src/main/java/com/freelib/multiitem/demo/input/ItemInfo.java → demo/src/main/java/com/freelib/multiitem/demo/input/ItemInfoDataBind.java

@@ -8,18 +8,20 @@
 import com.freelib.multiitem.item.DataBindItemInput;
 
 /**
+ * 利用DataBinding实现的多行录入Item
  * Created by free46000 on 2017/4/16.
  */
-public class ItemInfo extends DataBindItemInput<ItemInfo> {
+public class ItemInfoDataBind extends DataBindItemInput<ItemInfoDataBind> {
     private String name;
     private String info;
 
-    public ItemInfo(String key) {
+    public ItemInfoDataBind(String key) {
         super(key);
     }
 
     @Override
     protected void initInputView(ViewDataBinding dataBinding) {
+        //把自身实例对象通过ViewDataBinding绑定到视图中
         dataBinding.setVariable(BR.itemData, this);
     }
 
@@ -38,7 +40,11 @@ public boolean isValueValid() {
         return !TextUtils.isEmpty(info);
     }
 
-    public ItemInfo setName(String name) {
+    /**
+     * 设置展示列名
+     * @param name 展示列名
+     */
+    public ItemInfoDataBind setName(String name) {
         this.name = name;
         return this;
     }

demo/src/main/java/com/freelib/multiitem/demo/input/ItemNameAndSex.java

@@ -12,6 +12,7 @@
 import java.util.Map;
 
 /**
+ * 姓名和性别录入Item，一个录入item对应多个提交的值{"name":"","sex":""}
  * Created by free46000 on 2017/4/13.
  */
 public class ItemNameAndSex extends BaseItemInput<ItemNameAndSex> {
@@ -27,10 +28,10 @@ protected int getItemLayoutId() {
         return R.layout.item_name_sex;
     }
 
-    //本例中需要返回两组key-value所以去覆写
+    //本例中需要返回两组key-value所以去覆写getValueMap()
     @Override
     public Object getValue() {
-        //在getValue中返回两个值的组合，用以判断表单的值是否被改变
+        //在本方法中返回两个值的组合，作用是为判断表单的值是否被改变提供依据
         //也可以直接覆写isValueChange()方法达到定制化
         if (nameEdit == null) {
             return null;
@@ -40,6 +41,7 @@ public Object getValue() {
 
     @Override
     public boolean isValueValid() {
+        //如果名字输入框录入的值不为空则有效；其它无效
         return nameEdit != null && !TextUtils.isEmpty(nameEdit.getText().toString());
     }
 
@@ -49,6 +51,7 @@ public Map<String, Object> getValueMap() {
             return null;
         }
 
+        //此处自己组装Map{name:name,sex:sex}并返回，这样可以达到一个Item返回两组值的效果
         Map<String, Object> valueMap = new HashMap<>(2);
         valueMap.put("name", nameEdit.getText().toString());
         int sexStrResId = sexRadio.getCheckedRadioButtonId() == R.id.man ? R.string.man : R.string.woman;

demo/src/main/res/layout/item_info_input_data_bind.xml

@@ -6,7 +6,7 @@
 
         <variable
             name="itemData"
-            type="com.freelib.multiitem.demo.input.ItemInfo"/>
+            type="com.freelib.multiitem.demo.input.ItemInfoDataBind"/>
     </data>
 
     <LinearLayout
@@ -26,7 +26,6 @@
             />
 
         <EditText
-            android:id="@+id/editText"
             android:layout_width="match_parent"
             android:layout_height="wrap_content"
             android:lines="3"

library/src/main/java/com/freelib/multiitem/adapter/InputItemAdapter.java

@@ -23,10 +23,22 @@ public class InputItemAdapter extends BaseItemAdapter {
     protected List<InputHolderManager> inputHolderManagers = new ArrayList<>();
     protected List<HiddenItemInput> hiddenItemInputs = new ArrayList<>();
 
+    /**
+     * 添加隐藏域的Item，本Item用户不可见，{@link #getInputValueMap}时返回{key:value}
+     *
+     * @param key   String
+     * @param value Object
+     * @see #addHiddenItem(HiddenItemInput...)
+     */
     public void addHiddenItem(@NonNull String key, Object value) {
         addHiddenItem(new HiddenItemInput(key, value));
     }
 
+    /**
+     * 添加隐藏域的Item，本Item用户不可见，{@link #getInputValueMap}时返回{key:value}
+     *
+     * @param hiddenItems String
+     */
     public void addHiddenItem(@NonNull HiddenItemInput... hiddenItems) {
         if (hiddenItems.length == 0) {
             return;
@@ -36,10 +48,24 @@ public void addHiddenItem(@NonNull HiddenItemInput... hiddenItems) {
 
 //    public boolean isValueValidate()
 
+    /**
+     * 获取所有Input Item和隐藏域的表单内容并组装
+     *
+     * @return 表单内容json
+     * @see #getInputValueMap()
+     * @see InputHolderManager#getValueMap()
+     */
     public JSONObject getInputJson() {
         return new JSONObject(getInputValueMap());
     }
 
+    /**
+     * 获取所有Input Item和隐藏域的表单内容并组装
+     *
+     * @return 表单内容Map
+     * @see #getInputValueMap()
+     * @see InputHolderManager#getValueMap()
+     */
     public Map<String, Object> getInputValueMap() {
         Map<String, Object> valueMap = new HashMap<>();
         Map<String, Object> itemValueMap;
@@ -77,7 +103,12 @@ protected void addItem(int position, @NonNull List<? extends Object> items) {
         fillInputHolderManagers(position, items);
     }
 
-
+    /**
+     * 查找ItemInput并填充InputHolderManager集合
+     *
+     * @param position int
+     * @param items    add和set的数据源
+     */
     protected void fillInputHolderManagers(int position, @NonNull List<? extends Object> items) {
         for (Object item : items) {
             if (item instanceof ItemInput) {
@@ -95,6 +126,12 @@ public BaseViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
         return viewHolder;
     }
 
+    /**
+     * 表单内容是否在初始化后发生改变，常见的如用户手动改变表单Item的某项值
+     *
+     * @return true:已改变；false:未改变
+     * @see InputHolderManager#isValueChange()
+     */
     public boolean isValueChange() {
         for (InputHolderManager inputHolderManager : inputHolderManagers) {
             if (inputHolderManager.isValueChange()) {
@@ -104,6 +141,12 @@ public boolean isValueChange() {
         return false;
     }
 
+    /**
+     * 表单是否验证有效，如Item为空验证
+     *
+     * @return true:有效；false:无效
+     * @see InputHolderManager#isValueValid()
+     */
     public boolean isValueValid() {
         for (InputHolderManager inputHolderManager : inputHolderManagers) {
             if (!inputHolderManager.isValueValid()) {

library/src/main/java/com/freelib/multiitem/adapter/holder/InputHolderManager.java

@@ -10,6 +10,7 @@
 import static android.R.attr.value;
 
 /**
+ * 录入的的ViewHolderManager
  * Created by free46000 on 2017/4/10.
  */
 public abstract class InputHolderManager<T extends ItemInput> extends BaseViewHolderManager<T> {
@@ -40,6 +41,11 @@ protected void onCreateViewHolder(@NonNull BaseViewHolder holder) {
         viewHolder = holder;
     }
 
+    /**
+     * 初始化Input视图，由于Input视图不可以复用，所以直接在初始化视图时设置好相关内容即可
+     *
+     * @param holder BaseViewHolder
+     */
     protected abstract void initInputView(BaseViewHolder holder);
 
     @Deprecated
@@ -67,11 +73,22 @@ public Map<String, Object> getValueMap() {
         return Collections.singletonMap(key, value);
     }
 
+    /**
+     * 是否在初始化后发生改变，如用户手动更改<br>
+     * 在{@link #initInputView(BaseViewHolder)}的时候会记录当时的value，然后调用本方法时去做对比
+     *
+     * @return true:已改变；false:未改变
+     */
     public boolean isValueChange() {
         Object value = getValue();
         return value == null ? value != originalValue : !value.equals(originalValue);
     }
 
+    /**
+     * 是否验证有效，如Item不能为空
+     *
+     * @return true:有效；false:无效  默认true
+     */
     public boolean isValueValid() {
         return true;
     }

library/src/main/java/com/freelib/multiitem/item/BaseItemInput.java

@@ -6,6 +6,7 @@
 import com.freelib.multiitem.adapter.holder.InputHolderManager;
 
 /**
+ * 基础的录入Input
  * Created by free46000 on 2017/4/10.
  */
 public abstract class BaseItemInput<T extends BaseItemInput> extends InputHolderManager<T> implements ItemInput {

library/src/main/java/com/freelib/multiitem/item/DataBindItemInput.java

@@ -4,8 +4,10 @@
 import android.databinding.ViewDataBinding;
 
 import com.freelib.multiitem.adapter.holder.BaseViewHolder;
+import com.freelib.multiitem.adapter.holder.InputHolderManager;
 
 /**
+ * 数据绑定的录入Item
  * Created by free46000 on 2017/4/16.
  */
 public abstract class DataBindItemInput<T extends BaseItemInput> extends BaseItemInput<T> {
@@ -27,6 +29,12 @@ protected void initInputView(BaseViewHolder holder) {
         initInputView(dataBinding);
     }
 
+    /**
+     * 通过ViewDataBinding初始化Input视图
+     *
+     * @param dataBinding
+     * @see InputHolderManager#initInputView(BaseViewHolder)
+     */
     protected abstract void initInputView(ViewDataBinding dataBinding);
 
 }