doc: 重构开发文档

liangjingkanji · Aug 8, 2023 · acbc77e · acbc77e
1 parent dbfca03
commit acbc77e
Show file tree

Hide file tree

Showing 60 changed files with 1,281 additions and 1,786 deletions.
diff --git a/README.md b/README.md
@@ -8,31 +8,31 @@
  | <a href="https://github.com/liangjingkanji/Net/releases/latest/download/net-sample.apk">下载体验</a>
 </p>
 
-<p align="center"><img src="https://user-images.githubusercontent.com/21078112/169665591-1bf3de50-888e-467a-9b64-0a9d03f73751.png" width="320"/></p>
+<p align="center"><img src="https://raw.githubusercontent.com/liangjingkanji/Net/master/docs/img/code-preview.png" width="400"/></p>
 
 <p align="center">
 <a href="https://jitpack.io/#liangjingkanji/Net"><img src="https://jitpack.io/v/liangjingkanji/Net.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="https://liangjingkanji.github.io/Net/api/"><img src="https://img.shields.io/badge/api-%E5%87%BD%E6%95%B0%E6%96%87%E6%A1%A3-red"/></a>
-<img src="https://raw.githubusercontent.com/liangjingkanji/liangjingkanji/master/img/group.svg"/>
+<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>
 <a href="http://liangjingkanji.github.io/Net/updates"><img src="https://img.shields.io/badge/updates-%E6%9B%B4%E6%96%B0%E6%97%A5%E5%BF%97-brightgreen"/></a>
 <a href="https://github.com/liangjingkanji/Net/blob/master/docs/issues.md"><img src="https://raw.githubusercontent.com/liangjingkanji/Net/master/docs/img/issues.svg"/></a>
 </p>
 
-<p align="center"><img src="https://github.com/liangjingkanji/Net/assets/21078112/c33d8a25-0a53-4594-a10a-026a5278432d" align="center" width="30%;" /></p>
+<p align="center"><img src="https://raw.githubusercontent.com/liangjingkanji/Net/master/docs/img/preview.png" align="center" width="30%;" /></p>
 
 <br>
 
-Android上可能是最强的网络框架, 基于[OkHttp](https://github.com/square/okhttp)/协程的非侵入式框架(不影响原有功能). 学习成本低/使用简单, 一行代码发起网络请求, 甚至无需初始化
+Net是基于[OkHttp](https://github.com/square/okhttp)/协程的非侵入式框架(可使用所有Api), 可升级OkHttp版本保持网络安全
 
 <br>
 
-欢迎将本项目文档/注释进行国际化翻译, 感谢您的支持! <br>
 Welcome to international translation of this project's documents/notes, thank you for your support!
 
 [Net 1.x](https://github.com/liangjingkanji/Net/tree/1.x) 版本使用RxJava实现 <br>
 [Net 2.x](https://github.com/liangjingkanji/Net/tree/2.x) 版本使用协程实现 <br>
+[Net-okhttp3](https://github.com/liangjingkanji/Net-okhttp3) Net3.x的Android低版本兼容库 <br>
 [Net 3.x](https://github.com/liangjingkanji/Net/) 版本使用协程实现, 可自定义OkHttp版本
 
 <br>
@@ -44,9 +44,9 @@ Welcome to international translation of this project's documents/notes, thank yo
 - [x] 专为Android而生
 - [x] OkHttp最佳实践
 - [x] 使用高性能Okio
-- [x] 支持OkHttp所有功能/组件
+- [x] 支持OkHttp所有Api
 - [x] 随时升级OkHttp版本保证网络安全性
-- [x] 优秀的源码/注释/文档/示例
+- [x] 详细文档/低学习成本
 - [x] 永远保持社区维护
 
 ## 主要功能

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/auto-dialog.md b/docs/auto-dialog.md
@@ -1,9 +1,9 @@
-Net支持发起请求的时候自动弹出和关闭对话框(Loading Dialog)
+Net支持发起请求开始时显示加载框, 请求结束时隐藏加载框(无论成败)
 
-## 自动显示加载框
+## 自动显示
 
-只需要使用`scopeDialog`作用域即可.
-```kotlin
+
+```kotlin hl_lines="1"
 scopeDialog {
     tvFragment.text = Post<String>("dialog") {
         param("u_name", "drake") // 请求参数
@@ -14,14 +14,14 @@ scopeDialog {
 
 <br>
 
-加载框默认使用的是Android原生加载框(MaterialDesign Dialog), 当然也提供参数传入指定每个请求的对话框
+默认是原生加载框(MaterialDesign Dialog), 可自定义
 
 <img src="https://i.loli.net/2021/08/14/JqIenA56F1cgyHs.png" width="250"/>
 
 
-## 指定单例加载框
+## 单例自定义
 
-就是仅针对当前网络请求指定加载框
+指定当前请求加载框
 
 ```kotlin
 val dialog = BubbleDialog(requireActivity(), "加载中")
@@ -36,61 +36,46 @@ scopeDialog(dialog) {
 
 <img src="https://i.loli.net/2021/08/14/8eDp7Oz2CQT9Jcq.gif" width="250"/>
 
-> 这里使用的iOS风格对话框: [BubbleDialog](https://liangjingkanji.github.io/Tooltip/bubble.html)
+!!! quote "菊花加载对话框"
+    示例使用的iOS风格对话框: [BubbleDialog](https://liangjingkanji.github.io/Tooltip/bubble.html)
 
-## 指定全局加载框
+## 全局自定义
 
-在Application中配置Net时就可以设置默认的Dialog
+初始化时指定加载对话框构造器`NetDialogFactory`
 
-=== "初始配置全局加载框"
-    ```kotlin
-    NetConfig.initialize("https://github.com/liangjingkanji/Net/", this) {
-            setDialogFactory { // 全局加载对话框
-                ProgressDialog(it).apply {
-                    setMessage("我是全局自定义的加载对话框...")
-                }
+```kotlin
+NetConfig.initialize(Api.HOST, this) {
+        setDialogFactory {
+            ProgressDialog(it).apply {
+                setMessage("我是全局自定义的加载对话框...")
             }
-    }
-    ```
-=== "修改全局加载框"
-    ```kotlin
-    NetConfig.dialogFactory = NetDialogFactory {
-        ProgressDialog(it).apply {
-            setMessage("我是全局自定义的加载对话框...")
         }
-    }
-    ```
-
-<br>
-
-如果不想修改全局加载框样式只是修改加载框文本, 可以覆盖文本(国际化同理)
+}
+```
 
-在当前项目下的values目录下的strings.xml添加以下一行可以修改文本
+如仅修改加载对话框文本, 在项目`values`目录的strings.xml添加以下
 
 ```xml
 <!--对话框-->
 <string name="net_dialog_msg">加载中</string>
 ```
 
-## 生命周期
+!!! question "自定义的加载框不是Dialog"
+    由于`scopeDialog`只能指定Dialog类型, 因此只能手动实现`Dialog`接口
 
-使用`scopeDialog`发起请求后, Dialog分为以下三个生命周期
+    仅要求复写 [DialogCoroutineScope](https://github.com/liangjingkanji/Net/blob/2abf07e1d003ef44574278fd2010f3375225d964/net/src/main/java/com/drake/net/scope/DialogCoroutineScope.kt#L47) 内调用的`Dialog`方法
 
-|生命周期|描述|
-|-|-|
-|Dialog 显示|执行`scopeDialog`时显示加载框|
-|Dialog 自动结束|作用域内任务结束时关闭加载框|
-|Dialog 手动结束|加载框被手动取消时取消作用域内网络请求|
+## 生命周期
 
-## 自定义加载对话框
+使用`scopeDialog`发起请求后, 分为三个生命周期
 
-我想要自定义加载框视图
+| 加载框状态 | 作用域                        |
+| ---------- | ----------------------------- |
+| 显示       | 执行`scopeDialog`时显示加载框 |
+| 隐藏       | 作用域内任务结束时隐藏加载框  |
+| 手动取消   | 取消作用域内所有网络请求      |
 
-- Dialog属于布局容器, 你可以继承Dialog然后创建属于自己的显示内容(类似Activity/Fragment), 比如该[iOS风格对话框](https://github.com/liangjingkanji/Tooltip/blob/HEAD/tooltip/src/main/java/com/drake/tooltip/dialog/BubbleDialog.kt)
 
-<br>
 
-我的加载框不是Dialog
 
-- 虽然我们指定`scopeDialog`的加载框或者`setNetDialogFactory`时只允许传入一个Dialog对象, 但即使你使用的不是Dialog你也可以创建一个类继承Dialog, 然后在其生命周期函数中处理`自己特殊对话框`的展示和隐藏
 
diff --git a/docs/auto-page.md b/docs/auto-page.md
diff --git a/docs/auto-pull.md b/docs/auto-pull.md
@@ -0,0 +1,38 @@
+首先请阅读上章节 [自动下拉刷新](auto-refresh.md), 已提及内容不再重复
+
+
+## 自动分页
+
+提供`addData()`来简化分页, 开发者可以借鉴实现
+
+```kotlin
+page.onRefresh {
+    scope {
+        val data = Get<ListModel>("list") {
+            param("page", index)
+        }.await().data
+        addData(data.list) {
+            index < data.total
+        }
+    }
+}.autoRefresh()
+```
+
+## 索引自增
+`index` 每次上拉加载自动++1, 刷新列表重置为`PageRefreshLayout.startIndex`
+
+## 有更多页
+
+根据`hasMore`返回结果是否关闭上拉加载, `isEmpty`决定是否显示`空数据`缺省页
+
+```kotlin
+fun addData(
+    data: List<Any?>?,
+    adapter: BindingAdapter? = null,
+    isEmpty: () -> Boolean = { data.isNullOrEmpty() },
+    hasMore: BindingAdapter.() -> Boolean = { true }
+)
+```
+
+<br>
+1. [PageRefreshLayout 下拉刷新/上拉加载](https://liangjingkanji.github.io/BRV/refresh.html)
diff --git a/docs/auto-refresh.md b/docs/auto-refresh.md
@@ -1,17 +1,17 @@
-Net属于低耦合框架, 自动下拉刷新需要依赖第三方组件: [BRV](https://github.com/liangjingkanji/BRV)(点击链接按文档依赖)
+!!! success "模块化依赖"
+    如果自己处理下拉刷新可跳过本章, Net可以仅仅作为简单的网络框架存在
+
 <br>
+Net可依赖三方库 [BRV](https://github.com/liangjingkanji/BRV) 实现自动处理下拉刷新
 
 <a href="https://jitpack.io/#liangjingkanji/BRV"><img src="https://jitpack.io/v/liangjingkanji/BRV.svg"/></a>
 
-使用固定版本号替换+符号
-
 ```groovy
-implementation 'com.github.liangjingkanji:BRV:+'
+implementation 'com.github.liangjingkanji:BRV:+' // 使用固定版本号替换+符号
 ```
 
-> 当然如果自己处理下拉刷新也是可以的, Net可以仅仅作为网络框架存在
+## PageRefreshLayout
 
-创建PageRefreshLayout
 ```xml
 <com.drake.brv.PageRefreshLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
@@ -29,14 +29,20 @@ implementation 'com.github.liangjingkanji:BRV:+'
 </com.drake.brv.PageRefreshLayout>
 ```
 
-创建列表
+## 创建列表
+
 ```kotlin
 rv_push.linear().setup {
     addType<String>(R.layout.item_list)
 }
 ```
 
-创建网络请求
+## 网络请求
+
+1. 请求开始, 显示下拉刷新动画
+2. 请求成功, 显示`内容`缺省页
+3. 请求失败,  显示`错误`缺省页
+
 ```kotlin hl_lines="2"
 page.onRefresh {
     scope {
@@ -46,19 +52,9 @@ page.onRefresh {
 }.autoRefresh()
 ```
 
-<br>
-
-> 注意高亮处使用的是`scope`而不是其他作用域, 只能使用scope, 否则无法跟随PageRefreshLayout生命周期等功能
-
-<br>
-
-- 使用上和自动缺省页相似
-- BRV同样属于具备完善功能独立的RecyclerView框架
-- BRV的下拉刷新扩展自[SmartRefreshLayout_v2](https://github.com/scwang90/SmartRefreshLayout), 支持其全部功能且更多
-
 ## 生命周期
 
-|生命周期|描述|
-|-|-|
-|开始|PageRefreshLayout执行`showLoading/autoRefresh`后触发`onRefresh`, 然后开始网络请求|
-|结束|PageRefreshLayout被销毁(例如其所在的Activity或Fragment被销毁), 网络请求自动取消|
+| 生命周期 | 描述                                               |
+| -------- | -------------------------------------------------- |
+| 开始     | `showLoading/autoRefresh`触发`onRefresh`, 开始请求 |
+| 结束     | PageRefreshLayout被销毁, 请求自动取消              |