# Gloading
**Repository Path**: HarmonyOS-tpc/Gloading
## Basic Information
- **Project Name**: Gloading
- **Description**: 深度解耦Hos Hap中全局加载中、加载失败及空数据视图，为组件化改造过程中的解耦长征助力
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 9
- **Forks**: 3
- **Created**: 2021-04-15
- **Last Updated**: 2024-05-24
## Categories & Tags
**Categories**: harmonyos-loading
**Tags**: None
## README
# Gloading
## 介绍
- 深度解耦Hos Hap中全局加载中、加载失败及空数据视图，为组件化改造过程中的解耦长征助力
- 分离全局加载状态视图的实现和使用
- 不需要在每个页面的布局文件中额外添加加载状态视图
- 可用于Ability、Slice，也可用于为某个Component显示加载状态，还可用于各种列表Item（ListContainer等）
- 轻量级：只有一个java文件，没有任何其它依赖，不到300行，其中注释占100+行，jar仅6K
- 兼容性好： 兼容绝大多数第三方炫酷的LoadingComponent（在Adapter中将其作为Component提供给Gloading）
- 可扩展：默认提供4种加载状态（加载中、加载失败、空数据、加载成功），支持自定义其它状态
## 演示
为Ability添加加载状态
加载成功|加载失败
点击重试|加载成功
无数据|个别页面使用特殊的Loading视图
:---:|:---:|:---:|:---:
|
|
|
为Component添加加载状态
用于Slice|用于ScrollView|用于ListContainer
:---:|:---:|:---:
|
|
## 背景
Loading动画几乎每个Hos Hap中都有。
一般在需要用户等待的场景，显示一个Loading动画可以让用户知道Hap正在加载数据，而不是程序卡死，从而给用户较好的使用体验。
同样的道理，当加载的数据为空时显示一个数据为空的视图、在数据加载失败时显示加载失败对应的UI并支持点击重试会比白屏的用户体验更好一些。
加载中、加载失败、空数据的UI风格，一般来说在Hap内的所有页面中需要保持一致，也就是需要做到全局统一。
#### 传统的做法
1. 定义一个(或多个)显示不同加载状态的控件或者xml布局文件（例如：`LoadingComponent`）
2. 每个页面的布局中都写上这个component
3. 在`BaseAbility/BaseSlice`中封装`LoadingComponent`的初始化逻辑，并封装加载状态切换时的UI显示逻辑，暴露给子类以下方法：
- `void showLoading();` //调用此方法显示加载中的动画
- `void showLoadFailed();` //调用此方法显示加载失败界面
- `void showEmpty();` //调用此方法显示空页面
- `void onClickRetry();` //子类中实现，点击重试的回调方法
4. 在`BaseAbility/BaseSlice`的子类中可通过上一步的封装比较方便地使用加载状态显示功能
这种使用方式耦合度太高，每个页面的布局文件中都需要添加`LoadingComponent`，使用起来不方便而且维护成本较高，一旦UI设计师需要更改布局，修改起来成本较高。
#### 好一点的封装方法
1. 定义一个(或多个)显示不同加载状态的控件或者xml布局文件（例如：`LoadingComponent`）
2. 定义一个工具类(`LoadingUtil`)来管理`LoadingComponent`，不同状态显示不同的UI（或者在多个Component之间切换显示）
3. 在`BaseAbility/BaseSlice`中对`LoadingUtil`的使用进行封装，暴露给子类以下方法：
- `void showLoading();` //调用此方法显示加载中的动画
- `void showLoadFailed();` //调用此方法显示加载失败界面
- `void showEmpty();` //调用此方法显示空页面
- `void onClickRetry();` //子类中实现，点击重试的回调方法
- `abstract int getContainerId();` //子类中实现，`LoadingUtil`动态创建`LoadingComponent`并添加到该方法返回id对应的控件中
4. 在`BaseAbility/BaseSlice`的子类中可通过上一步的封装比较方便地使用加载状态显示功能
这种封装的好处是通过封装动态地创建`LoadingComponent`并添加到指定的父容器中，让具体页面无需关注`LoadingComponent`的实现，只需要指定在哪个容器中显示即可，很大程度地进行了解耦。如果公司只在一个Hap中使用，这基本上就够了。
但是，这种封装方式还是存在耦合：页面与它所使用的`LoadingComponent`仍然存在绑定关系。如果需要复用到其它Hap中，因为每个App的UI风格可能不同，对应的`LoadingComponent`布局也可能会不一样，要想复用必须先将页面与`LoadingComponent`解耦。
## 如何解耦？
#### 梳理一下我们需要实现的效果
- 页面的`LoadingComponent`可切换，且不需要改动页面代码
- 页面中可指定`LoadingComponent`的显示区域（例如导航栏Title不希望被`LoadingComponent`覆盖）
- 支持在Slice中使用
- 支持加载失败页面中点击重试
- 兼容不同页面显示的UI有细微差别（例如提示文字可能不同）
## 使用Gloading来解耦
Gloading是一个基于Adapter思路实现的深度解耦Hap中全局LoadingComponent的轻量级工具(只有一个java文件，不到300行，其中注释占100+行，aar仅6K)
1、 依赖
```java
allprojects{
repositories{
mavenCentral()
}
}
implementation 'io.openharmony.tpc.thirdlib:Gloading:1.0.3'
```
2、 创建`Adapter`，在`getComponent`方法中实现创建各种状态视图（加载中、加载失败、空数据等）的逻辑
Gloading不侵入UI布局，完全由用户自定义
```java
public class GlobalAdapter implements Gloading.Adapter {
@Override
public Component getComponent(Gloading.Holder holder, Component convertComponent, int status) {
GlobalLoadingStatusView loadingStatusView = null;
//convertComponent为可重用的布局
//Holder中缓存了各状态下对应的View
// 如果status对应的Component为null，则convertComponent为上一个状态的Component
// 如果上一个状态的Component也为null，则convertComponent为null
if (convertComponent != null && convertComponent instanceof GlobalLoadingStatusView) {
loadingStatusView = (GlobalLoadingStatusView) convertComponent;
}
if (loadingStatusView == null) {
loadingStatusView = new GlobalLoadingStatusView(holder.getContext(), holder.getRetryTask());
}
loadingStatusView.setStatus(status);
return loadingStatusView;
}
class GlobalLoadingStatusView extends DependentLayout {
public GlobalLoadingStatusView(Context context, Runnable retryTask) {
super(context);
//初始化LoadingComponent
//如果需要支持点击重试，在适当的时机给对应的控件添加点击事件
}
public void setStatus(int status) {
//设置当前的加载状态：加载中、加载失败、空数据等
//其中，加载失败可判断当前是否联网，可现实无网络的状态
// 属于加载失败状态下的一个分支,可自行决定是否实现
}
}
}
```
3、 初始化`Gloading`的默认`Adapter`
```java
Gloading.initDefault(new GlobalAdapter());
```
4、在需要使用`LoadingComponent`的地方获取`Holder`
```java
//在Ability中显示, 父容器为: mLayout
Gloading.Holder holder = Gloading.getDefault().wrap(ability, mLayout);
//需要支持加载失败后点击重试
Gloading.Holder holder = Gloading.getDefault().wrap(ability, mLayout).withRetry(retryTask);
```
or
```java
//为某个Component显示加载状态
//Gloading会自动创建一个FrameLayout，将Component包裹起来，LoadingComponent也显示在其中
Gloading.Holder holder = Gloading.getDefault().wrap(component);
//需要支持加载失败后点击重试
Gloading.Holder holder = Gloading.getDefault().wrap(component).withRetry(retryTask);
```
4.1 如果父容器为 `DependentLayout`，用cover可以保持与同级其它控件之间的关联关系
```java
Gloading.Holder holder = Gloading.getDefault().cover(component);
//或
Gloading.Holder holder = Gloading.getDefault().cover(component).withRetry(retryTask);
```
5、 使用`Holder`来显示各种加载状态
```java
//显示加载中的状态，通常是显示一个加载动画
holder.showLoading()
//显示加载成功状态（一般是隐藏LoadingComponent）
holder.showLoadSuccess()
//显示加载失败状态
holder.showFailed()
//数据加载完成，但数据为空
holder.showEmpty()
//如果以上默认提供的状态不能满足使用，可使用此方法调用其它状态
holder.showLoadingStatus(status)
```
6、 兼容多App场景下的页面、Component的复用
每个Hap的`LoadingComponent`可能会不同，只需为每个Hap提供不同的`Adapter`，不同App调用不同的`Gloading.initDefault(new GlobalAdapter());`，具体页面中的使用代码无需改动。
## 开启/关闭Debug模式
```java
//设置为true时Logcat会输出日志
Gloading.debug(trueOrFalse);
```
## 调用差异
```java
Gloading.Holder holder = Gloading.getDefault().wrap(activity);
```
改为
```java
//需要将父布局传入
Gloading.Holder holder = Gloading.getDefault().wrap(ability, mLayout);
```
## 示例entry运行要求
通过DevEco studio,并下载SDK
将项目中的build.gradle文件中dependencies→classpath版本改为对应的版本（即你的IDE新建项目中所用的版本）