pulltorefresh

简介

PullToRefresh 是一款 OpenHarmony 环境下可用的下拉刷新、上拉加载组件。支持设置内置动画的各种属性，支持设置自定义动画，支持 LazyForEach 的数据作为数据源。

效果展示

内置动画效果

下载安装

ohpm install @ohos/pulltorefresh

OpenHarmony ohpm 环境配置等更多内容，请参考如何安装 OpenHarmony ohpm 包。

约束与限制

兼容性

在下述版本验证通过：

• DevEco Studio: NEXT Beta1-5.0.3.806, SDK: API12 Release(5.0.0.66), ROM: 5.0.0.66

使用限制

1. 目前只支持 List、Scroll、Tabs、Grid 和 WaterFlow 系统容器组件
2. 暂不支持设置系统容器组件的弹簧效果和阴影效果，使用时需要将系统组件 edgeEffect 属性的值设置为 EdgeEffect.None
3. 暂不支持页面触底时自动触发上拉加载功能
4. 暂不支持在页面数据不满一屏时触发上拉加载功能
5. 暂不支持通过代码的方式去触发下拉刷新功能
6. 暂不支持在下拉刷新动画结束时提供手势结束的回调

使用示例

// V1装饰器下的使用方式
import { PullToRefresh } from '@ohos/pulltorefresh'

// 需绑定列表或宫格组件
private scroller: Scroller = new Scroller();
  
PullToRefresh({
// 必传项，列表组件所绑定的数据
data: $data,
// 必传项，需绑定传入主体布局内的列表或宫格组件
scroller: this.scroller,
// 必传项，自定义主体布局，内部有列表或宫格组件
customList: () => {
  // 一个用@Builder修饰过的UI方法
  this.getListView();
},
// 可选项，下拉刷新回调
onRefresh: () => {
  return new Promise<string>((resolve, reject) => {
    // 模拟网络请求操作，请求网络2秒后得到数据，通知组件，变更列表数据
    setTimeout(() => {
      resolve('刷新成功');
      this.data = [...this.dataNumbers];
    }, 2000);
  });
},
// 可选项，上拉加载更多回调
onLoadMore: () => {
  return new Promise<string>((resolve, reject) => {
    // 模拟网络请求操作，请求网络2秒后得到数据，通知组件，变更列表数据
    setTimeout(() => {
      resolve('');
      this.data.push("增加的条目" + this.data.length);
    }, 2000);
  });
},
customLoad: null,
customRefresh: null,
})

// V2装饰器下的使用方式
import { PullToRefreshV2 } from '@ohos/pulltorefresh'

// 需绑定列表或宫格组件
private scroller: Scroller = new Scroller();

PullToRefreshV2({
   // 可选项，列表组件所绑定的数据
   data: this.data,
   // 必传项，需绑定传入主体布局内的列表或宫格组件
   scroller: this.scroller,
   // 必传项，自定义主体布局，内部有列表或宫格组件
   customList: () => {
      // 一个用@Builder修饰过的UI方法
      this.getListView();
   },
   // 可选项，下拉刷新回调
   onRefresh: () => {
      return new Promise<string>((resolve, reject) => {
         // 模拟网络请求操作，请求网络2秒后得到数据，通知组件，变更列表数据
         setTimeout(() => {
            resolve('刷新成功');
            this.data = [...this.dataNumbers];
         }, 2000);
      });
   },
   // 可选项，上拉加载更多回调
   onLoadMore: () => {
      return new Promise<string>((resolve, reject) => {
         // 模拟网络请求操作，请求网络2秒后得到数据，通知组件，变更列表数据
         setTimeout(() => {
            resolve('');
            this.data.push("增加的条目" + this.data.length);
         }, 2000);
      });
   },
   customLoad: null,
   customRefresh: null,
})

更多示例请查看 示例代码。

使用说明

PullToRefresh 组件（V1 装饰器）

PullToRefresh 组件用于包装 List、Scroll、Tabs、Grid 或 WaterFlow 组件，提供下拉刷新和上拉加载更多功能。

PullToRefreshV2 组件（V2 装饰器）

PullToRefreshV2 组件功能与 PullToRefresh 类似，但适配了新的 API 规范。

LazyForEach 数据源支持

LazyForEach 从提供的数据源中按需迭代数据，并在每次迭代过程中创建相应的组件。当 LazyForEach 在滚动容器中使用时，框架会根据滚动容器可视区域按需创建组件，当组件滑出可视区域外时，框架会进行组件销毁回收以降低内存占用。

接口描述：

LazyForEach(
    dataSource: IDataSource,             // 需要进行数据迭代的数据源
    itemGenerator: (item: any, index?: number) => void,  // 子组件生成函数
    keyGenerator?: (item: any, index?: number) => string // 键值生成函数
): void

IDataSource 类型说明

interface IDataSource {
    totalCount(): number; // 获得数据总数
    getData(index: number): Object; // 获取索引值对应的数据
    registerDataChangeListener(listener: DataChangeListener): void; // 注册数据改变的监听器
    unregisterDataChangeListener(listener: DataChangeListener): void; // 注销数据改变的监听器
}

DataChangeListener 类型说明

interface DataChangeListener {
    onDataReloaded(): void; // 重新加载数据时调用
    onDataAdded(index: number): void; // 添加数据时调用
    onDataMoved(from: number, to: number): void // 数据移动起始位置与数据移动目标位置交换时调用
    onDataDeleted(index: number): void; // 删除数据时调用
    onDataChanged(index: number): void; // 改变数据时调用
    onDataAdd(index: number): void; // 添加数据时调用
    onDataMove(from: number, to: number): void // 数据移动起始位置与数据移动目标位置交换时调用
    onDataDelete(index: number): void; // 删除数据时调用
    onDataChange(index: number): void; // 改变数据时调用
}

具体使用请参考 OpenHarmony 官方文档：LazyForEach：数据懒加载

接口说明

PullToRefresh / PullToRefreshV2 组件属性

属性	类型	描述	默认值	必填	OpenHarmony 平台支持
data	Object[] | undefined	列表或宫格组件所绑定的数据	undefined	部分(在PullToRefresh中是必填项，在PullToRefreshV2中不是必填项)	是
scroller	Scroller	列表或宫格组件所绑定的 Scroller 对象	undefined	是	是
customList	() => void	自定义主体布局，内部有列表或宫格组件	undefined	是	是
refreshConfigurator	PullToRefreshConfigurator	组件属性配置	PullToRefreshConfigurator	否	是
mWidth	Length	容器宽度	undefined（自适应）	否	是
mHeight	Length	容器高度	undefined（自适应）	否	是
onRefresh	() => Promise<string>	下拉刷新回调	1秒后后结束下拉刷新动画并提示"刷新失败"	否	是
onLoadMore	() => Promise<string>	上拉加载更多回调	1秒后后结束上拉加载动画	否	是
customRefresh	() => void	自定义下拉刷新动画布局	undefined	否	是
onAnimPullDown	(value?: number, width?: number, height?: number) => void | undefined	下拉中回调	undefined	否	是
onAnimRefreshing	(value?: number, width?: number, height?: number) => void | undefined	刷新中回调	undefined	否	是
customLoad	() => void	自定义上拉加载动画布局	undefined	否	是
onAnimPullUp	(value?: number, width?: number, height?: number) => void | undefined	上拉中回调	undefined	否	是
onAnimLoading	(value?: number, width?: number, height?: number) => void | undefined	加载中回调	undefined	否	是

PullToRefreshConfigurator 配置类

方法	参数	返回值	描述	必填	OpenHarmony 平台支持
setHasRefresh	hasRefresh: boolean	this	设置是否具有下拉刷新功能	否	是
setHasLoadMore	hasLoadMore: boolean	this	设置是否具有上拉加载功能	否	是
setMaxTranslate	maxTranslate: number	this	设置可下拉上拉的最大距离	否	是
setSensitivity	sensitivity: number	this	设置下拉上拉灵敏度	否	是
setListIsPlacement	listIsPlacement: boolean	this	设置滑动结束后列表是否归位	否	是
setAnimDuration	animDuration: number	this	设置滑动结束后，回弹动画执行时间	否	是
setRefreshHeight	refreshHeight: number	this	设置下拉动画高度	否	是
setRefreshColor	refreshColor: ResourceColor	this	设置下拉动画颜色	否	是
setRefreshBackgroundColor	refreshBackgroundColor: ResourceColor	this	设置下拉动画区域背景色	否	是
setRefreshTextColor	refreshTextColor: ResourceColor	this	设置下拉加载完毕后提示文本的字体颜色	否	是
setRefreshTextSize	refreshTextSize: number | string | Resource	this	设置下拉加载完毕后提示文本的字体大小	否	是
setRefreshAnimDuration	refreshAnimDuration: number	this	设置下拉动画执行一次的时间，仅在自定义下拉刷新动画时有效	否	是
setRefreshCompleteTextHoldTime	refreshCompleteTextHoldTime: number	this	设置下拉刷新完毕后，刷新成功文本停留的时间	否	是
setLoadImgHeight	loadImgHeight: number	this	设置上拉动画中图片的高度	否	是
setLoadBackgroundColor	loadBackgroundColor: ResourceColor	this	设置上拉动画区域背景色	否	是
setLoadTextColor	loadTextColor: ResourceColor	this	设置上拉文本的字体颜色	否	是
setLoadTextSize	loadTextSize: number | string | Resource	this	设置上拉文本的字体大小	否	是
setLoadTextPullUp1	loadTextPullUp1: ResourceStr	this	设置上拉 1 阶段文本	否	是
setLoadTextPullUp2	loadTextPullUp2: ResourceStr	this	设置上拉 2 阶段文本	否	是
setLoadTextLoading	loadTextLoading: ResourceStr	this	设置上拉加载更多中时的文本	否	是

关于混淆

代码混淆请参考 代码混淆简介。

如果希望 pulltorefresh 库在代码混淆过程中不会被混淆，需要在混淆规则配置文件 obfuscation-rules.txt 中添加相应的排除规则：

-keep
./oh_modules/@ohos/pulltorefresh

目录结构

ohos_pull_to_refresh
├── entry/           # 示例代码目录
│   └── src/
│       └── main/
│           ├── ets/
│           │   └── pages/  # 示例页面
│           ├── module.json5
│           └── resources/
├── library/         # 核心代码目录
│   ├── index.ets    # 导出入口文件
│   └── src/
│       └── main/
│           └── ets/
│               └── components/
│                   └── PullToRefresh/  # 组件实现
├── gifs/            # 效果展示图片
├── build-profile.json5
├── oh-package.json5
├── hvigorfile.js
└── README_zh.md

贡献代码

使用过程中发现任何问题都可以提 Issue 给组件，也非常欢迎发 PR 共建。

开源协议

本项目基于 Apache License 2.0，请自由地享受和参与开源。