docs: 重写开发文档

docs/animation.md

@@ -1,4 +1,4 @@
-列表动画只是实现列表Item出现的动画
+列表动画即自定义列表Item出现时的动画
 
 ## 动画类型
 通过函数快速设置BRV自带的几种动画类型

docs/checked.md

@@ -53,9 +53,7 @@
 
 ## 默认选择
 
-如果你想默认选中某些Item, 应当使用`setChecked`函数去设置, 而不是直接在Model中设置`isChecked`属性为true(这是不会触发选中回调的)
-
-例如在Demo中就有这么一行代码默认选中第一个Item
+首次加载列表默认选中指定Item, 应调用`setChecked`而不是将Model中某个属性置为true
 
 ```kotlin
 // 切换选择模式
@@ -65,9 +63,18 @@ tv_manage.setOnClickListener {
 }
 ```
 
+!!! question "原因"
+    为自由扩展功能BRV的选中属性由开发者定义, 实际上BRV并不知道什么属性决定的选中状态
+
+    1. `checkedXX()`函数通知BRV更新选中索引
+    2. `onChecked()`通知开发者选中状态更新
+
 ## 数据变化
+如果列表发生插入/覆盖数据集行为, 那么集合位置/数量和BRV内部保存的选中索引`checkedPosition`可能对不上
 
-如果数据位置发生变化, 例如增删, 请使用`BindingAdapter.checkedPosition.clear()`清除选中位置集合(也不一定就是清除), 否则可能发生数据错误导致的无法单选
+网络请求刷新列表场景
+
+    建议由开发者保存选中索引+业务Id, 如果新的数据集存在之前已选中Id进行选中状态恢复
 
 ## 函数
 
@@ -86,4 +93,3 @@ tv_manage.setOnClickListener {
 | checkedPosition | 被选择的item的position集合 |
 | checkedCount | 已选择数量 |
 | onChecked | 选择回调 |
-

docs/flexbox.md

@@ -1,20 +1,15 @@
 
-BRV对于伸缩布局的实现可以自行添加Google开源库 [flexbox-layout](https://github.com/google/flexbox-layout)
+使用Google官方库 [flexbox-layout](https://github.com/google/flexbox-layout) 来实现流式伸缩布局
 
-添加依赖
+依赖
 
 ```groovy
 dependencies {
     implementation 'com.google.android.flexbox:flexbox:3.0.0'
 }
 ```
 
-
-
-然后创建列表
-
-
-<img src="https://i.loli.net/2021/08/14/KYkHmyCrDogiLsS.png" width="250"/>
+创建列表
 
 ```kotlin
 rv.layoutManager = FlexboxLayoutManager(activity)
@@ -24,3 +19,5 @@ rv.setup {
 }.models = getData()
 ```
 
+<img src="https://i.loli.net/2021/08/14/KYkHmyCrDogiLsS.png" width="250"/>
+

docs/header-footer.md

@@ -0,0 +1,90 @@
+<img src="https://s2.loli.net/2022/04/24/JgSrqjWAP26b8x5.gif" width="250"/>
+
+!!! Warning "多类型列表"
+    1. 头/脚布局在RV中只是多类型item, 所以在计算`position`时应当考虑其中
+    2. 头/脚布局也需要使用`addType`函数添加类型
+
+    ```kotlin
+    BRV数据集 = Header + Models + Footer
+    ```
+
+```kotlin
+binding.rv.linear().setup {
+    addType<Model>(R.layout.item_simple)
+    addType<Header>(R.layout.item_header)
+    addType<Footer>(R.layout.item_footer)
+}.models = getData()
+
+binding.rv.bindingAdapter.run {
+    addHeader(Header(), animation = true)
+    addFooter(Footer(), animation = true)
+}
+```
+
+其他头/脚布局实现
+
+1. 可使用[ConcatAdapter](https://developer.android.com/reference/androidx/recyclerview/widget/ConcatAdapter)连接多个`BindingAdapter`
+1. `NestedScrollView`嵌套RV会导致RV一次性加载全部列表, 大量列表数据时会卡顿
+
+<br>
+
+
+## 列表局部缺省页
+
+如果使用`CoordinatorLayout`方案来解决列表缺省页覆盖头/脚布局问题, 但是期望从页面顶部开始下拉刷新动画
+
+- [PagePartStateFragment](https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/PagePartStateFragment.kt#L27)
+
+```kotlin title="fragment_page_part_state_header.xml"
+<com.drake.brv.PageRefreshLayout
+    android:id="@+id/page"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    app:page_rv="@id/rv"
+    app:page_state="@id/state">
+
+    <androidx.coordinatorlayout.widget.CoordinatorLayout>
+
+        <com.google.android.material.appbar.AppBarLayout>
+
+            // ... HEADER
+
+        </com.google.android.material.appbar.AppBarLayout>
+
+        <com.drake.statelayout.StateLayout
+            android:id="@+id/state"
+            android:layout_width="match_parent"
+            android:layout_height="match_parent"
+            app:layout_behavior="com.google.android.material.appbar.AppBarLayout$ScrollingViewBehavior">
+
+            <androidx.recyclerview.widget.RecyclerView
+                android:id="@+id/rv"
+                android:layout_width="match_parent"
+                android:layout_height="match_parent" />
+
+        </com.drake.statelayout.StateLayout>
+
+    </androidx.coordinatorlayout.widget.CoordinatorLayout>
+
+</com.drake.brv.PageRefreshLayout>
+
+```
+
+1. `app:page_rv` 指定嵌套的rv
+2. `app:page_state` 指定嵌套的缺省页
+
+## 函数
+
+| 函数 | 描述 |
+|-|-|
+| addHeader/addFooter | 添加头布局/脚布局 |
+| removeHeader/removeFooter | 删除头布局/脚布局 |
+| removeHeaderAt/removeFooterAt | 删除指定索引的头布局/脚布局 |
+| clearHeader/clearFooter | 清除全部头布局/脚布局 |
+| isHeader/isFooter | 指定索引是否是头布局/脚布局 |
+| headerCount/footerCount | 头布局/脚布局数量 |
+
+
+
+
+

docs/hover.md

@@ -1,6 +1,6 @@
 <p align="center"><img src="https://i.loli.net/2021/08/14/4wUngbV2qZFAf5H.gif" width="250"/></p>
 
-通过实现接口`ItemHover`
+实现接口`ItemHover`
 
 ```kotlin
 class HoverHeaderModel : ItemHover {
@@ -9,67 +9,53 @@ class HoverHeaderModel : ItemHover {
 }
 ```
 
-然后这个Item就会悬停在顶部了
 
-
-
-完整示例
+## 监听悬停事件
 
 ```kotlin
-override fun onActivityCreated(savedInstanceState: Bundle?) {
-    super.onActivityCreated(savedInstanceState)
-
-    rv.linear().setup {
-        addType<Model>(R.layout.item_simple)
-        addType<HoverHeaderModel>(R.layout.item_hover_header)
-        models = getData()
-
-        // 点击事件
-        onClick(R.id.item) {
-            when (itemViewType) {
-                R.layout.item_hover_header -> toast("悬停条目")
-                else -> toast("普通条目")
-            }
+rv.linear().setup {
+    addType<Model>(R.layout.item_simple)
+    addType<HoverHeaderModel>(R.layout.item_hover_header)
+
+    // 点击事件
+    onClick(R.id.item) {
+        when (itemViewType) {
+            R.layout.item_hover_header -> toast("悬停条目")
+            else -> toast("普通条目")
         }
+    }
 
-        // 可选项, 粘性监听器
-        onHoverAttachListener = object : OnHoverAttachListener {
-            // 黏住顶部的时候, v表示指定悬停的itemView对象
-            override fun attachHover(v: View) {
-                ViewCompat.setElevation(v, 10F)
-            }
-
-            // 从顶部分离的时候
-            override fun detachHover(v: View) {
-                ViewCompat.setElevation(v, 0F)
-            }
+    // 可选项, 粘性监听器
+    onHoverAttachListener = object : OnHoverAttachListener {
+        // 黏住顶部的时候, v表示指定悬停的itemView对象
+        override fun attachHover(v: View) {
+            ViewCompat.setElevation(v, 10F)
         }
 
+        // 从顶部分离的时候
+        override fun detachHover(v: View) {
+            ViewCompat.setElevation(v, 0F)
+        }
     }
+
 }
+}.models = getData()
 ```
 
-> 不同于大部分悬停框架, BRV无需特殊处理支持全部的点击事件
-
-[BindingAdapter] 判断当前位置是否属于悬停
-
-```kotlin
-fun isHover(position: Int): Boolean
-```
+!!! success "支持点击事件"
+    不同于大部分悬停框架, BRV无需特殊处理支持全部的点击/长按事件
 
 ## 网格悬停
 
-Demo截图
-
 <img src="https://i.loli.net/2021/08/14/4CfDnegM2kOi8WK.png" width="250"/>
 
-可以看到图片中悬停的item比普通的item要宽两倍, 这里需要确定悬停的Item的动态`SpanSize`, 所以不能直接使用`grid(3)`而是需要手动创建`HoverGridLayoutManager`
+可以看到图中悬停的item比普通item要宽两倍, 所以需要返回动态`SpanSize`
 
 ```kotlin
 val layoutManager = HoverGridLayoutManager(requireContext(), 2)
 layoutManager.spanSizeLookup = object : GridLayoutManager.SpanSizeLookup() {
     override fun getSpanSize(position: Int): Int {
-        return if(rv.bindingAdapter.isHover(position)) 2 else 1 // 具体的业务逻辑由你确定
+        return if(rv.bindingAdapter.isHover(position)) 2 else 1 // 具体判断逻辑由你确定
     }
 }
 rv.layoutManager = layoutManager

docs/preload.md

@@ -1,20 +1,17 @@
-`预加载`就是还没显示到列表末尾就会开始加载下一页, 执行上拉加载的逻辑, 前提是当前列表有下一页
-
-`预拉取`就是提前拉取. 和上面预加载差不多理解. 不知道拉取是什么请阅读[拉取更多](upfetch.md)
 
+!!! question "预加载/预拉取"
+    即列表末尾还未显示就会开始加载下一页
 
 ## 当前列表预加载索引
 
-BRV默认开启预加载/预拉取. 通过函数可以指定成员属性`preloadIndex`可以控制显示到倒数第几个条目时就开始预加载
-
-> 预拉取和预加载条件都是使用的同一个字段. 设置preloadIndex后两者都会生效
+BRV默认开启预加载/预拉取, 指定字段`preloadIndex`控制显示到倒数第几个条目时开始预加载
 
-默认值是: 3
+以下为默认值
 
 ```kotlin
 var preloadIndex = 3
 ```
 
 ## 全局预加载索引
 
-通过`PageRefreshLayout.preloadIndex`可以设置全局默认值. 这样所有列表都默认就是你指定的索引开始预加载
+`PageRefreshLayout.preloadIndex`设置全局默认值, 所有列表都按照你指定的索引开始预加载

docs/refresh-animate.md → docs/refresh-animation.md

@@ -1,4 +1,4 @@
-上一章介绍过BRV内嵌[SmartRefreshLayout](https://github.com/scwang90/SmartRefreshLayout)来实现下拉刷新/上拉加载, 以下演示自定义刷新动画
+BRV使用[SmartRefreshLayout](https://github.com/scwang90/SmartRefreshLayout)来实现下拉刷新/上拉加载, 支持他的自定义刷新动画
 
 ## 关闭上拉加载动画