docs: 更新开发文档

liangjingkanji · Aug 8, 2023 · 48fe08f · 48fe08f
1 parent 462477a
commit 48fe08f
Show file tree

Hide file tree

Showing 22 changed files with 115 additions and 92 deletions.
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@
 <p align="center">
 <a href="https://jitpack.io/#liangjingkanji/BRV"><img src="https://jitpack.io/v/liangjingkanji/BRV.svg"/></a>
 <img src="https://img.shields.io/badge/language-kotlin-orange.svg"/>
-<img src="https://img.shields.io/badge/license-Apache-blue"/>
+<img src="https://img.shields.io/badge/license-MIT-blue"/>
 <a href="http://liangjingkanji.github.io/BRV/updates"><img src="https://img.shields.io/badge/changed-%E6%9B%B4%E6%96%B0%E6%97%A5%E5%BF%97-brightgreen"/></a>
 <a href="http://liangjingkanji.github.io/BRV/api"><img src="https://img.shields.io/badge/api-%E5%87%BD%E6%95%B0%E6%96%87%E6%A1%A3-red"/></a>
 <a href="https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/img/group-qrcode.png"><img src="https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/img/group.svg"/></a>
@@ -34,9 +34,8 @@
 
 <p align="center"><img src="https://github.com/liangjingkanji/BRV/blob/master/docs/img/preview.png?raw=true" align="center" width="30%;" /></p>
 
-本框架在不影响RecyclerView的任何函数组件使用基础上开发. 本项目承诺会永远保持社区维护
+BRV为快速构建RV列表工具, 以开源分享来完善, 将一直保持社区维护
 
-欢迎将本项目文档/注释进行国际化翻译, 感谢您的支持! <br>
 Welcome to international translation of this project's documents/notes, thank you for your support!
 
 <br>

diff --git a/docs/animation.md b/docs/animation.md
@@ -1,7 +1,7 @@
-列表动画即自定义列表Item出现时的动画
+自定义列表Item出现时的动画
 
 ## 动画类型
-通过函数快速设置BRV自带的几种动画类型
+设置BRV自带的动画类型
 
 ```kotlin
 fun setAnimation(animationType: AnimationType)

diff --git a/docs/api/styles/jetbrains-mono.css b/docs/api/styles/jetbrains-mono.css
@@ -1,33 +1,31 @@
 @font-face{
     font-family: 'JetBrains Mono';
-    src: local('JetBrains Mono'),
-         url('https://raw.githubusercontent.com/JetBrains/JetBrainsMono/master/fonts/webfonts/JetBrainsMono-Regular.woff2') format('woff2'),
-         url('https://raw.githubusercontent.com/JetBrains/JetBrainsMono/master/fonts/ttf/JetBrainsMono-Regular.ttf') format('truetype');
+    src: local('Iosevka Curly Medium'),
+         url('https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/font/iosevka-curly/iosevka-curly-medium.woff2') format('woff2');
     font-display: swap;
     font-weight: normal;
     font-style: normal;
 }
 @font-face{
     font-family: 'JetBrains Mono';
-    src: local('JetBrains Mono'),
-         url('https://raw.githubusercontent.com/JetBrains/JetBrainsMono/master/fonts/webfonts/JetBrainsMono-Bold.woff2') format('woff2'),
-         url('https://raw.githubusercontent.com/JetBrains/JetBrainsMono/master/fonts/ttf/JetBrainsMono-Bold.ttf') format('truetype');
+    src: local('Iosevka Curly Bold'),
+         url('https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/font/iosevka-curly/iosevka-curly-bold.woff2') format('woff2');
     font-display: swap;
     font-weight: bold;
     font-style: normal;
 }
 @font-face{
     font-family: 'HYZhengYuan';
-    src: local('HYZhengYuan'),
-         url('https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/font/HYZhengYuan.ttf') format('truetype');
+    src: local('HYYouYuan-55W'),
+         url('https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/font/HYYouYuan/HYYouYuan-55W.ttf') format('truetype');
     font-display: swap;
     font-weight: normal;
     font-style: normal;
 }
 @font-face{
     font-family: 'HYZhengYuan';
-    src: local('HYZhengYuan-75W'),
-         url('https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/font/HYZhengYuan-75W.ttf') format('truetype');
+    src: local('HYYouYuan-75W'),
+         url('https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/font/HYYouYuan/HYYouYuan-75W.ttf') format('truetype');
     font-display: swap;
     font-weight: bold;
     font-style: normal;

diff --git a/docs/checked.md b/docs/checked.md
@@ -1,6 +1,9 @@
-<img src="https://i.loli.net/2021/08/14/MIe74pdKf5c1hTX.gif" width="250"/>
+<figure markdown>
+  ![](https://i.loli.net/2021/08/14/MIe74pdKf5c1hTX.gif){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/CheckModeFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
+</figure>
 
-可编辑/多选列表在开发中很常见, BRV可以几行代码实现[选择模式](https://github.com/liangjingkanji/BRV/blob/master/sample/src/main/java/com/drake/brv/sample/ui/fragment/CheckModeFragment.kt)
+BRV可快速实现支持单选/多选的[选择模式](https://github.com/liangjingkanji/BRV/blob/master/sample/src/main/java/com/drake/brv/sample/ui/fragment/CheckModeFragment.kt)
 
 ## 多选列表
 
@@ -16,13 +19,13 @@
     data class CheckModel(
         var isChecked: Boolean = false,
         var visibility: Boolean = false
-    ) : BaseObservable() // BaseObservable 这是DataBinding的数据绑定写法
+    ) : BaseObservable() // 支持DataBinding数据绑定
     ```
 
 3. 监听选择事件
     ```kotlin hl_lines="3"
     rv.linear().setup {
-       addType<CheckModel>(R.layout.item_check_mode)
+       // ...
        onChecked { position, isChecked, isAllChecked ->
             val model = getModel<CheckModel>(position)
             model.isChecked = isChecked
@@ -32,20 +35,9 @@
     ```
 
 4. 触发选择事件
-    ```kotlin hl_lines="11"
-    rv.linear().setup {
-       addType<CheckModel>(R.layout.item_check_mode)
-       onChecked { position, isChecked, isAllChecked ->
-            val model = getModel<CheckModel>(position)
-            model.isChecked = isChecked
-            model.notifyChange() // 通知UI跟随数据变化
-       }
-
-       onClick(R.id.cb, R.id.item) {
-            var isChecked = getModel<CheckModel>().isChecked
-            setChecked(adapterPosition, !isChecked) // 在点击事件中触发选择事件, 即点击列表条目就选中
-       }
-    }.models = getData
+    ```kotlin hl_lines="2"
+    val isChecked = getModel<CheckModel>().isChecked
+    setChecked(adapterPosition, !isChecked) // 在点击事件中触发选择事件, 即点击列表条目就选中
     ```
 
 
@@ -56,11 +48,7 @@
 首次加载列表默认选中指定Item, 应调用`setChecked`而不是将Model中某个属性置为true
 
 ```kotlin
-// 切换选择模式
-tv_manage.setOnClickListener {
-    adapter.toggle()
-    rv.bindingAdapter.setChecked(0, true) // 一开始就选中第一个
-}
+rv.bindingAdapter.setChecked(0, true) // 一开始就选中第一个
 ```
 
 !!! question "原因"

diff --git a/docs/divider-customize.md b/docs/divider-customize.md
@@ -1,5 +1,5 @@
-1. 扩展函数`divider`为简化创建`DefaultDecoration`
-2. 如`DefaultDecoration`不满足需求可以继承`RecyclerView.ItemDecoration`实现
+!!! note "列表间隔"
+    有时在布局中使用`layout_margin_bottom`等属性更简单
 
 ## 组合间距
 
@@ -22,6 +22,8 @@ binding.rv.grid(3).divider { // 水平间距
 
 ## 方法
 
+函数`divider`简化创建`DefaultDecoration`, 其实现接口`ItemDecoration`
+
 | 函数 | 描述 |
 |-|-|
 | onEnabled | 根据回调返回值是否绘制分隔线 |
@@ -44,4 +46,21 @@ data class Edge(
 )
 ```
 
-`left`为true表示指定position位于列表左侧, `top`为true表示位于列表顶部, 类推
+`left`为true表示指定position位于列表左侧, `top`为true表示位于列表顶部, 类推
+
+## 超复杂分隔物
+超复杂分隔物建议在列表布局中绘制, 可根据`Edge.computeEdge()`禁止绘制四周
+
+```kotlin hl_lines="5"
+binding.rv.linear().divider(R.drawable.divider_horizontal).setup {
+    addType<DividerModel>(R.layout.item_divider_vertical)
+    onBind {
+        layoutManager = binding.rv.layoutManager!!
+        val edge = DefaultDecoration.Edge.computeEdge(layoutPosition, layoutManager, false)
+        if (edge.bottom) {
+            // 列表结尾不绘制分隔物
+            return@onBind
+        }
+    }
+}.models = getData()
+```
diff --git a/docs/divider-grid.md b/docs/divider-grid.md
@@ -44,7 +44,7 @@ rv.grid(3).divider {
 | [endVisible](api/-b-r-v/com.drake.brv/-default-decoration/index.html#-377591023%2FProperties%2F-900954490) | 是否显示左右边缘分隔线 |
 | [includeVisible](api/-b-r-v/com.drake.brv/-default-decoration/index.html#1716094302%2FProperties%2F-900954490) | 是否显示周围分隔线 |
 
-### 1) 上下
+### 上下
 
 <img src="https://i.loli.net/2021/08/14/JBjETuMoaORFWHK.png" width="250"/>
 
@@ -59,7 +59,7 @@ rv.grid(3).divider {
 ```
 
 
-### 2) 左右
+### 左右
 
 <img src="https://i.loli.net/2021/08/14/IcxHsWafFQXh4Eg.png" width="250"/>
 
@@ -73,7 +73,7 @@ rv.grid(3).divider {
 }.models = getData()
 ```
 
-### 3) 四周
+### 四周
 
 <img src="https://i.loli.net/2021/08/14/UmhH5BgFA3a1W2Q.png" width="250"/>
 

diff --git a/docs/divider-linear.md b/docs/divider-linear.md
@@ -2,7 +2,7 @@
 
 <img src="https://i.loli.net/2021/08/14/IoBfnz6ERXVHlq3.png" width="250" />
 
-创建一个`drawable`文件来描述分隔线, 其具备复用的特点
+创建`drawable`来描述分隔线
 
 ```xml
 <shape xmlns:android="http://schemas.android.com/apk/res/android">
@@ -25,7 +25,7 @@ rv.linear().divider(R.drawable.divider_horizontal).setup {
 
 <img src="https://i.loli.net/2021/08/14/rAeDXkfV6HxJUym.png" width="250"/>
 
-创建Drawable作为分隔线
+创建`drawable`来描述分隔线
 ```xml
 <shape xmlns:android="http://schemas.android.com/apk/res/android">
     <solid android:color="@color/dividerDecoration" />
@@ -41,9 +41,9 @@ rv.linear(RecyclerView.HORIZONTAL).divider(R.drawable.divider_vertical).setup {
 ```
 
 
-- 这里使用`Drawable`资源来快速设置分隔线, Drawable的宽高就是分隔线的宽高
-- 如果水平分隔线, 则Drawable的宽度值无效(实际宽度值为RecyclerView的宽)
-- 如果垂直分隔线, 则Drawable的高度值无效(实际分隔线高度为RecyclerView高度)
+- 使用`drawable`资源可复用分隔线, 其宽高就是分隔线的宽高
+- 如果水平分隔线, 则`drawable`的宽度值无效(实际宽度值为RecyclerView的宽)
+- 如果垂直分隔线, 则`drawable`的高度值无效(实际分隔线高度为RecyclerView高度)
 
 
 ## 边缘分隔线
@@ -56,7 +56,7 @@ rv.linear(RecyclerView.HORIZONTAL).divider(R.drawable.divider_vertical).setup {
 
 <img src="https://i.loli.net/2021/08/14/iL5epWdOQKnwZAc.png" width="250"/>
 
-通过两个字段可以控制首尾是否显示分隔线
+两个字段控制首尾是否显示分隔线
 
 ```kotlin hl_lines="3 4"
 rv.linear().divider {
@@ -93,9 +93,9 @@ rv.grid().divider{
 
 有两种方式
 
-1. 直接配置一个具备间隔margin的drawable, 以下为间距16的水平分隔线
+1. 创建有间隔`内间距`的drawable, 以下为间距16水平分隔线
 
-    ```xml
+    ```xml hl_lines="2"
     <inset xmlns:android="http://schemas.android.com/apk/res/android"
         android:insetLeft="16dp"
         android:insetRight="16dp">
@@ -108,7 +108,7 @@ rv.grid().divider{
 
 2. 使用setMargin()
 
-    ```kotlin
+    ```kotlin hl_lines="3"
     binding.rv.linear().divider {
         setDivider(1, true)
         setMargin(16, 0, dp = true)

diff --git a/docs/drag.md b/docs/drag.md
@@ -1,4 +1,7 @@
-<img src="https://i.loli.net/2021/08/14/9EUvCSnONYixWDT.gif" width="250"/>
+<figure markdown>
+  ![](https://i.loli.net/2021/08/14/9EUvCSnONYixWDT.gif){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef2/sample/src/main/java/com/drake/brv/sample/ui/fragment/DragFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
+</figure>
 
 Model实现接口`ItemDrag`即可开启拖拽功能
 

diff --git a/docs/extension.md b/docs/extension.md
@@ -12,7 +12,7 @@
 
 ## 布局管理器
 
-扩展函数快速创建布局管理器
+快速创建布局管理器
 
 === "线性列表"
     ```kotlin hl_lines="1"
@@ -43,7 +43,7 @@
 
 ## 分隔线
 
-扩展函数`divider`快速创建[DefaultDecoration](api/-b-r-v/com.drake.brv/-default-decoration/index.html)
+使用`divider`快速创建[DefaultDecoration](api/-b-r-v/com.drake.brv/-default-decoration/index.html)
 
 ```kotlin hl_lines="1"
 rv.linear().divider(R.drawable.divider_horizontal).setup {

diff --git a/docs/flexbox.md b/docs/flexbox.md
@@ -19,5 +19,8 @@ rv.setup {
 }.models = getData()
 ```
 
-<img src="https://i.loli.net/2021/08/14/KYkHmyCrDogiLsS.png" width="250"/>
+<figure markdown>
+  ![](https://i.loli.net/2021/08/14/KYkHmyCrDogiLsS.png){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef2/sample/src/main/java/com/drake/brv/sample/ui/fragment/FlexBoxFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
+</figure>
 
diff --git a/docs/group.md b/docs/group.md
@@ -1,6 +1,6 @@
 <figure markdown>
-  ![](https://i.loli.net/2021/08/14/Pl53LCpG8tdhuMW.gif){ width="300" }
-  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/group/GroupFragment.kt#L26" target="_blank"><figcaption>示例代码</figcaption></a>
+  ![](https://i.loli.net/2021/08/14/Pl53LCpG8tdhuMW.gif){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/group/GroupFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
 </figure>
 
 ## 特点
@@ -80,16 +80,16 @@ rv.linear().setup {
 ## 分组多类型
 
 <figure markdown>
-  ![](https://s2.loli.net/2021/12/10/wo1CAqL5SDIZRKu.png){ width="300" }
-  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/group/GroupGridFragment.kt#L19" target="_blank"><figcaption>示例代码</figcaption></a>
+  ![](https://s2.loli.net/2021/12/10/wo1CAqL5SDIZRKu.png){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/group/GroupGridFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
 </figure>
 
 自定义`GridLayoutManager.spanSizeLookup`即可, 多类型和分组不存在影响
 
 ## 分组拖拽/侧滑
 <figure markdown>
-  ![](https://s2.loli.net/2021/12/14/RSpGEF2DWyqPb5J.gif){ width="300" }
-  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/group/GroupDragFragment.kt#L25" target="_blank"><figcaption>示例代码</figcaption></a>
+  ![](https://s2.loli.net/2021/12/14/RSpGEF2DWyqPb5J.gif){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef245e7f312a0077194611f1c2aded647a3c/sample/src/main/java/com/drake/brv/sample/ui/fragment/group/GroupDragFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
 </figure>
 
 [拖拽](drag.md)/[侧滑](swipe.md)功能和分组原本互不影响, 但删除/移动已展开的分组未同步他的子列表会导致数据错乱, 需要以下处理

diff --git a/docs/header-footer.md b/docs/header-footer.md
@@ -1,4 +1,7 @@
-<img src="https://s2.loli.net/2022/04/24/JgSrqjWAP26b8x5.gif" width="250"/>
+<figure markdown>
+  ![](https://s2.loli.net/2022/04/24/JgSrqjWAP26b8x5.gif){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef2/sample/src/main/java/com/drake/brv/sample/ui/fragment/HeaderFooterFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
+</figure>
 
 !!! Warning "多类型列表"
     1. 头/脚布局在RV中只是多类型item, 所以在计算`position`时应当考虑其中
@@ -21,7 +24,7 @@ binding.rv.bindingAdapter.run {
 }
 ```
 
-其他头/脚布局实现
+其他头/脚布局实现方式
 
 1. 可使用[ConcatAdapter](https://developer.android.com/reference/androidx/recyclerview/widget/ConcatAdapter)连接多个`BindingAdapter`
 1. `NestedScrollView`嵌套RV会导致RV一次性加载全部列表, 大量列表数据时会卡顿

diff --git a/docs/hover.md b/docs/hover.md
@@ -1,6 +1,9 @@
 悬停条目又常被称为`粘性头部`
 
-<p align="center"><img src="https://i.loli.net/2021/08/14/4wUngbV2qZFAf5H.gif" width="250"/></p>
+<figure markdown>
+  ![](https://i.loli.net/2021/08/14/4wUngbV2qZFAf5H.gif){ width="250" }
+  <a href="https://github.com/liangjingkanji/BRV/blob/5269ef2/sample/src/main/java/com/drake/brv/sample/ui/fragment/hover/HoverLinearFragment.kt" target="_blank"><figcaption>示例代码</figcaption></a>
+</figure>
 
 Model实现接口`ItemHover`
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,4 @@
-
-本框架在不影响RecyclerView的任何函数组件使用基础上开发, 本项目将一直保持社区维护
+BRV为快速构建RV列表工具, 以开源分享来完善, 将一直保持社区维护
 
 <br>
 <p align="center"><strong>STAR/分享可以让更多人参与到本开源项目</strong></p>
@@ -115,15 +114,10 @@ android {
 
 
 ### 3. 自动绑定
-DataBinding会根据配置的`modelId`自动绑定models中数据到xml中
 
+在Application中初始化, DataBinding会根据`modelId`自动绑定`models`到xml中
 ```kotlin
-class App : Application() {
-    override fun onCreate() {
-        // ...
-        BRV.modelId = BR.m
-    }
-}
+BRV.modelId = BR.m
 ```
 
 1. 先在某个布局中声明`<layout>`布局中的变量`m`(推荐命名), `BR.m`才能被生成 <br>一旦声明`BRV.model = BR.m`所有BRV使用的item布局使用`name="m"`来声明才能自动绑定

diff --git a/docs/lifecycle.md b/docs/lifecycle.md
@@ -47,7 +47,7 @@ binding.rv.linear().adapter = object : BindingAdapter() {
 ```
 
 !!! warning "不允许重复调用"
-    onBind或onCreate只有最后设置的有效, 存在覆盖关系
+    onBind或onCreate请勿重复调用, 其存在覆盖关系
 
 ```kotlin
 rv.linear().setup {