# SVRefresh

**Repository Path**: mervin1024/SVRefresh

## Basic Information

- **Project Name**: SVRefresh
- **Description**: SVRefresh 是一款 OpenHarmony 环境下，基于 ArkUI 封装的下拉刷新、上拉加载组件。

- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 11
- **Forks**: 0
- **Created**: 2024-02-28
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: HarmonyOS组件, UI

## README

# SVRefresh

### 介绍

> SVRefresh 是一款 OpenHarmony 环境下，基于 ArkUI 封装的下拉刷新、上拉加载组件。
>
> 支持使用 controller 控制刷新状态，主动触发刷新、开启/关闭刷新。

### 效果展示

![Refresh](gifs/refresh.gif)![Refresh](gifs/loadMore.gif)

### 安装教程

```shell
ohpm install @mervin/svrefresh
```

### 使用说明

#### 快速使用

```typescript
import { SVRefresh, RefreshController } from '@mervin/SVRefresh'

// 需绑定列表或宫格组件
private
scroller: Scroller = new Scroller()
// 刷新控制器
private
refreshController = new RefreshController()

SVRefresh({
  // 必传项，需绑定传入主体布局内的列表或宫格组件
  scroller: this.scroller,
  // 必传项，用来控制刷新状态
  controller: this.refreshController
    .setHeaderHidden(false)
    .setFooterHidden(false),
  // 必传项，自定义主体布局，内部为列表或宫格组件
  childList: () => {
    this.getListView()
  },
  onRefreshing: () => {
    setTimeout(() => {
      /// 数据更新
      this.refreshController.endRefresh()
      /// 是否还有更多数据
      let hasMoreData = true
      this.refreshController.endLoadMore(hasMoreData)
    }, 2000)
  },
  onLoadingMore: () => {
    setTimeout(() => {
      if (this.data.length <= 8) {
        this.data.push(`额外加载数据 ${this.data.length}`)
      }
      let hasMoreData = this.data.length <= 8
      this.refreshController.endLoadMore(hasMoreData)
    }, 2000)
  }
})
```

其中List组件的 edgeEffect 属性不要设置为(EdgeEffect.Fade)，展示效果不好

#### 属性（接口）说明

#### SVRefresh 组件属性

|         属性          |                 类型                  |                  释义                   | 是否可选 |
|:-------------------:|:-----------------------------------:|:-------------------------------------:|:----:|
|     controller      |          RefreshController          |    刷新组件的控制器，详见下方 RefreshController    |  必传  |
|      scroller       |              Scroller               |         列表或宫格组件所绑定的Scroller对象         |  必传  |
|      childList      |    @BuilderParam```() => void```    |          自定义主体布局，内部有列表或宫格组件           |  必传  |
|   uiConfigurator    |       SVRefreshUIConfigurator       | 刷新组件属性配置，详见下方 SVRefreshUIConfigurator |  可选  |
|      headerUI       |    @BuilderParam```() => void```    |           自定义下拉刷新组件，不传为默认样式           |  可选  |
|      footerUI       |    @BuilderParam```() => void```    |           自定义上拉加载组件，不传为默认样式           |  可选  |
| onHeaderStateChange | ```(state: RefreshState) => void``` | header 刷新状态改变回调，用来辅助外部实现自定义 headerUI  |  可选  |
| onFooterStateChange | ```(state: RefreshState) => void``` | footer 刷新状态改变回调，用来辅助外部实现自定义 footerUI  |  可选  |
|    onRefreshing     |          ```() => void ```          |                下拉刷新回调                 |  可选  |
|    onLoadingMore    |          ```() => void```           |                上拉加载回调                 |  可选  |

#### RefreshController 类接口

|            接口            |  参数类型   |                           释义                           |       
|:------------------------:|:-------:|:------------------------------------------------------:|
|     setHeaderHidden      | boolean |                   可以用来 禁用/启用 下拉刷新组件                    |
|     setFooterHidden      | boolean |                   可以用来 禁用/启用 上拉加载组件                    |
|       beginRefresh       |         |                        主动触发下拉刷新                        |
|        endRefresh        |         |                         结束下拉刷新                         |
| endLoadMore(hasMoreData) | boolean | 结束上拉加载，参数默认值为 true。<br/>当 hasMoreData 为 false，继续拖拽将无效果 |

#### SVRefreshUIConfigurator 类接口

|              接口              |                 参数类型                  |            释义             |    默认值    |
|:----------------------------:|:-------------------------------------:|:-------------------------:|:---------:|
|       setHeaderHeight        |                number                 | 下拉刷新控件的展示高度，同时也是触发下拉事件的高度 |    64     |
|       setFooterHeight        |                number                 | 上拉加载控件的展示高度，同时也是触发上拉事件的高度 |    54     |
|       setAutoLoadMore        |                boolean                | 可以控制上拉加载组件的触发方式，自动 or 拖拽  |   true    |
|       setHeaderBounces       |                boolean                |        下拉是否支持弹性效果         |   true    |
|       setFooterBounces       |                boolean                |        上拉是否支持弹性效果         |   true    |
|      setHeaderTextSize       |      number 或 string 或 Resource       |      默认 header 的字体大小      |    18     |
|      setFooterTextSize       |      number 或 string 或 Resource       |      默认 footer 的字体大小      |    18     |
| setHeaderLoadingProgressSize |                length                 |  header 的默认 loading 组件尺寸  |    36     |
| setFooterLoadingProgressSize |                length                 |  footer 的默认 loading 组件尺寸  |    36     |
|        setHeaderText         | ```(state: RefreshState) => string``` |    各刷新状态下 header 展示的文字    | undefined |
|        setFooterText         | ```(state: RefreshState) => string``` |    各刷新状态下 footer 展示的文字    | undefined |

### 约束与限制

在下述版本验证通过：
- DevEco Studio: 4.1 Canary(4.1.3.500), SDK: API11 (4.1.0.36)

### 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitee.com/mervin1024/SVRefresh/issues)
给我们，当然，我们也非常欢迎你给我们发 [PR](https://gitee.com/mervin1024/SVRefresh/pulls) 。

### 开源协议

本项目基于 [Apache License 2.0](https://gitee.com/openharmony-sig/PullToRefresh/blob/master/LICENSE) ，请自由地享受和参与开源。