# easy_refresh

**Repository Path**: mxlj/easy_refresh

## Basic Information

- **Project Name**: easy_refresh
- **Description**: HarmonyOsRefresh是基于ArkUI封装的上拉下拉刷新组件，支持List、Grid、WaterFlow,Scroll组件刷新
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 16
- **Forks**: 5
- **Created**: 2024-05-04
- **Last Updated**: 2025-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 名称

EasyRefresh上拉，下拉刷新工具。主要希望构建一种对使用者来说使用快捷，方便的工具，不要使用者在使用过程中感到复杂，繁琐的操作。

# 装饰器版本

[v1 装饰器版本](https://gitee.com/mxlj/easy_refresh.git)

[v2 装饰器版本](https://gitee.com/mxlj/easy_refresh_scrolls.git)

# 介绍

基于ArkUI封装的上拉下拉刷新组件，支持列表、网格、瀑布流、以及各种自定义组件的刷新。

- 1、支持List列表、Gird、WaterFlow、自定义组件的Scroll上拉下拉刷新
- 2、支持自定义刷新header,footer刷新样式
- 3、支持自定义插入头部信息，以及底部信息

# 效果展示

动态效果：
<p align="center">
<img src="https://gitee.com/mxlj/easy_refresh_scrolls/raw/main/%E6%95%88%E6%9E%9C%E5%9B%BE.gif" />
</p>

静态效果：
注：请下载demo详情查看效果。

#### 更多案例

可以查看相关[Demo并下载](https://gitee.com/mxlj/easy_refresh.git)。

运行Demo，如果自身相关开发环境不一致，会运行失败，可更改环境或者直接源码复制至您的项目即可。

# 开发环境

DevEco Studio NEXT Developer Beta2,Builder Version:5.0.3.706

Api版本：12

# 快速上手

## 安装方式

### 1、命令安装：

在Terminal窗口中，执行如下命令安装三方包，DevEco Studio会自动在工程的oh-package.json5中自动添加三方包依赖。

建议：可以自行指定安装目录
安装：

```
ohpm install @easy_refresh/easy_refresh
```

版本更新：

```
ohpm update @easy_refresh/easy_refresh
```

### 2、在工程的oh-package.json5中设置三方包依赖，配置示例如下：

```
"dependencies": { "@easy_refresh/easy_refresh": "^1.1.1"}
```

### 3、本地静态共享包har包使用

首先，下载har包，[点击下载](https://gitee.com/mxlj/lib_easy_refresh/raw/master/EasyRefresh.har)

下载之后，把har包复制项目中，目录自己创建，如下，我创建了一个libs目录，复制进去

引入之后，进行同步项目，点击Sync Now即可，当然了你也可以，将鼠标放置在报错处会出现提示，在提示框中点击Run 'ohpm install'。

需要注意，**@easy_refresh/easy_refresh**，是用来区分目录的，可以自己定义，比如@aa/bb等，关于静态共享包的创建和使用，请查看如下我的介绍，这里就不过多介绍

HarmonyOS开发：走进静态共享包的依赖与使用

# List的使用

#### 关于网络请求部分的模拟代码：

```
//属性：
@State
dataArray: number[] = []
@State total: number = 30
@State
title: string = ''
page: number = 1
@State
isRefresh:boolean = false //主动触发的设置条件--如果无此需要可以不用设置

//网络请求方法：
async getData(append: boolean) {
    setTimeout(() => {
      if (!append) {
        this.page = 1
      }
      let array: number[] = [];
      let startIndex = (this.page - 1) * 10;
      let endIndex = this.page * 10;

      for (let index = startIndex; index < endIndex; index++) {
        array.push(index);
      }

      if(append){
        this.dataArray.push(...array)
      }else {
        this.dataArray = []
        this.dataArray = array
      }
      this.page ++

    }, 500)
  }

```

#### 自定义没有更多内容

```
@Builder
  noMoreView() {
    Row() {
      Text('我是list自定义的没有更多内容了')
        .fontColor(Color.White)
    }
    .justifyContent(FlexAlign.Center)
    .backgroundColor(Color.Brown)
    .width('100%')
    .height(60)
  }

```

#### 自定义空白页

```
@Builder
  customEmptyView(){
    Row(){
      Text('我是list自定义的空白页')
        .fontSize(16)
        .fontColor(Color.Red)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
```

#### 普通List使用

```
EasyRefresh({
        refreshType: EasyRefreshType.ListType, //使用类型
        finished: this.dataArray.length < this.total ? true : false, //是否有下一页
        dataSource: this.dataArray,
        isCustomNoMore: false, //是否自定义没有更多内容
        isCustomEmptyView: false, //是否自定义空白页
        refreshing: this.isRefresh, //主动触发下拉刷新
        // isShowAutoEmptyView: false, //是否启用默认空白页，默认启动
        //自定义没有更多的显示内，如果不需要自定义的话，就不需要实现这个
        customNoMoreView: () => {
          this.noMoreView()
        },
        customEmptyView: () => {
          this.customEmptyView() //自定义空白页
        },
        contentItem: (item?: Object, index?: number) => {
          this.contentItem(item) //主内容
        },
        refreshCallBack: (async () => {
          await this.getData(false) //下拉网络请求的回调
        }),
        loadMoreCallBack: (async () => {
          await this.getData(true) //上拉加载更多的回调
        })
      })
        .width('100%')
        .height('100%')
```

注意：如果需要主动触发下拉刷新的功能，需要在触发的时候设置为this.isRefresh true，当完成后需要设置false，否则下次无法主动触发下拉刷新。

### Stikcy吸顶List使用

```
//数据源需要使用:StickyItemGroupModel模型，也可以继承它
@State
dataArray: StickyItemGroupModel<number>[] = []
initData() {
    this.dataArray = [
      {
        title: '星期一',
        items: []
      },
      {
        title: '星期二',
        items: []

      },
      {
        title: '星期三',
        items: []

      },
      {
        title: '星期四',
        items: []

      },
      {
        title: '星期五',
        items: []

      },
      {
        title: '星期六',
        items: []

      },
      {
        title: '星期天',
        items: []

      }
    ]
  }
  async getData(append: boolean) {
    setTimeout(() => {
      if (!append) {
        this.page = 1
        // this.isRefresh = false
      }
      let array: number[] = [];
      let startIndex = (this.page - 1) * 10;
      let endIndex = this.page * 10;

      for (let index = startIndex; index < endIndex; index++) {
        array.push(index);
      }

      if (append) {
        let pt: StickyItemGroupModel<number>[] = []
        this.dataArray.map((obj) => {
          if (obj.items) {
            obj.items = [...(obj.items || []), ...array];
            pt.push(obj);
            console.log('333');
          } else {
            obj.items = array;
            pt.push(obj);
          }
          console.log('333')
        })
        this.dataArray = pt.slice()
        console.log('333')
      } else {
        this.initData()

        const p = this.dataArray.map((item) => {

          return {
            title: item.title,
            items: array
          } as StickyItemGroupModel<number>
        })
        this.dataArray = p
        console.log('333')
      }
      this.isFinish = this.getFinish()
      this.page++

    }, 500)
  }
  @Builder
  itemHead(text: string) {
    Text(text)
      .fontSize(20)
      .backgroundColor(0xAABBCC)
      .width("100%")
      .padding(10)
  }

  @Builder
  itemFoot(num: number) {
    Text('共' + num + "节课")
      .fontSize(16)
      .backgroundColor(0xAABBCC)
      .width("100%")
      .padding(5)
  }
  EasyRefresh({
      refreshType: EasyRefreshType.ListStickyType, //使用类型
        finished: this.dataArray[0]?.items!.length < this.total ? true : false, //是否有下一页
        dataSource: this.dataArray,
        isCustomNoMore: false, //是否自定义没有更多内容
        isCustomEmptyView: false, //是否自定义空白页
        refreshing: this.isRefresh, //主动触发下拉刷新
        // isDisEnablePullRefresh: true, //是否启用禁止下拉刷新
        // isShowAutoEmptyView: false, //是否启用默认空白页，默认启动
        //自定义没有更多的显示内，如果不需要自定义的话，就不需要实现这个
        stickyItemHead: (item?: StickyItemGroupModel<number>, index?: number) => {
          this.itemHead(item!.title!)
        },
        stickItemFoot: (item?: Object, index?: number) => {
          this.itemFoot(index!)
        },
        customNoMoreView: () => {
          this.noMoreView()
        },
        customEmptyView: () => {
          this.customEmptyView() //自定义空白页
        },
        contentItem: (item?: Object, index?: number) => {
          this.contentItem(item) //主内容
        },
        refreshCallBack: (async () => {
          await this.getData(false) //下拉网络请求的回调
        }),
        loadMoreCallBack: (async () => {
          await this.getData(true) //上拉加载更多的回调
        })
      })
        .width('100%')
        .height('100%')
    }

```

# Gird的使用

```
EasyRefresh({
        refreshType: EasyRefreshType.GirdType,
        finished: this.dataArray.length < this.total ? true : false, //是否有下一页
        dataSource: this.dataArray,
        gridAttribute: (g: GridAttrModel) => {
          g.columnsTemplate = '1fr 1fr 1fr'
        },
        isCustomNoMore:false, //是否自定义没有更多内容
        isCustomEmptyView:false, //是否自定义空白页显示
        //自定义没有更多的显示内，如果不需要自定义的话，就不需要实现这个
        customNoMoreView: () => {
          this.noMoreView()
        },
        customEmptyView:()=>{
          this.customEmptyView()
        },
        contentItem: (item?: Object,index?:number) => {
          this.contentItem(item)
        },
        refreshCallBack: (async () => {
          await this.getData(false)
        }),
        loadMoreCallBack: (async () => {
          await this.getData(true)
        })
      })
        .width('100%')
        .height('100%')
```

# WaterFlow的使用

```
EasyRefresh({
        refreshType: EasyRefreshType.WaterFlowType,
        finished: this.dataArray.length < this.total ? true : false, //是否有下一页
        dataSource: this.dataArray,
        gridAttribute: (g: GridAttrModel) => {
          g.columnsTemplate = '1fr 1fr'
        },
        isCustomNoMore:true, //是自定义没有更多的内容显示
        isCustomEmptyView:true, //是否自定义空白页设置
        //自定义没有更多的显示内，如果不需要自定义的话，就不需要实现这个
        customNoMoreView: () => {
          this.noMoreView()
        },
        customEmptyView:()=>{
          this.customEmptyView()
        },
        contentItem: (item?: Object, index?: number) => {
          this.contentItem(item, index)
        },
        refreshCallBack: (async () => {
          await this.getData(false)
        }),
        loadMoreCallBack: (async () => {
          await this.getData(true)
        })
      })
        .width('100%')
        .height('100%')
```

# Scroll自定义的使用

```
EasyRefresh({
        refreshType: EasyRefreshType.ScrollType,
        finished: false,
        dataSource: this.dataArray,
        isCustomNoMore: false, //是自定义没有更多的内容显示
        isCustomEmptyView: false, //是否自定义空白页设置
        //自定义没有更多的显示内，如果不需要自定义的话，就不需要实现这个
        customNoMoreView: () => {
          this.noMoreView()
        },
        customEmptyView: () => {
          this.customEmptyView()
        },
        contentItem: (item?: Object, index?: number) => {
          this.contentItem()
        },
        customHeader: (() => {
          this.getCustomHeader()
        }),
        customFooter: (() => {
          this.getCustomFooter()
        }),
        refreshCallBack: (async () => {
          await this.getData(false)
        }),
        loadMoreCallBack: (async () => {
          await this.getData(true)
        })
      })
        .layoutWeight(1)
```

#### 更多案例

可以查看相关[Demo并下载](https://gitee.com/mxlj/easy_refresh.git)。

运行Demo，如果自身相关开发环境不一致，会运行失败，可更改环境或者直接源码复制至您的项目即可。

#### 联系作者

如果您在使用上有问题，解决不了，或者查看精华的鸿蒙技术文章，QQ邮箱:3316368400@qq.com。

#### 贡献者

非常感谢大家对本项目的付出，在此感谢大家的努力，欢迎更多的同学加入进来交流，名次不分先后。

<div style="display: flex; flex-wrap: wrap; gap: 10px; justify-content: flex-start;">
<div style="text-align: center; margin: 0px;">
    <a href="https://gitee.com/mxlj" target="_blank" style="text-decoration: none; color: black;">
      <img src="https://foruda.gitee.com/avatar/1676918797874240133/540911_mxlj_1578927078.jpg!avatar30" style="width: 60px; height: 60px; border-radius: 50%; display: block; margin: 0 auto;">
      <p style="margin-top: 10px;">marlonxlj</p>
    </a>
  </div>
    <div style="text-align: center; margin: 0px;">
    <a href="https://gitee.com/dodo" target="_blank" style="text-decoration: none; color: black;">
      <img src="https://foruda.gitee.com/avatar/1719905635042572825/20322_dodo_1719905635.png!avatar30" style="width: 60px; height: 60px; border-radius: 50%; display: block; margin: 0 auto;">
      <p style="margin-top: 10px;">dodo</p>
    </a>
  </div>


</div>

#### License

```
Copyright (C) AbnerMing, HarmonyOsRefresh Open Source Project

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

```