pulltorefresh

简介

PullToRefresh 是基于 OpenHarmony ArkUI 的下拉刷新、上拉加载组件。支持配置内置动画属性、自定义动画，以及 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. 暂不支持在下拉刷新动画结束时提供手势结束的回调

使用示例

// @Component 组件的使用方式
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,
})

// @ComponentV2 组件的使用方式
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,
})

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

半模态 bindSheet 下拉关闭

在半模态 bindSheet 内使用 PullToRefresh 时，若需要下拉关闭 Sheet，可通过已有配置关闭下拉刷新：new PullToRefreshConfigurator().setHasRefresh(false)。关闭后，组件仅处理上拉加载手势，不会拦截向下拖动手势。

同时，ArkUI 要求半模态中的滚动容器配置 nestedScroll。PullToRefresh / PullToRefreshV2 提供布尔属性 enableNestedScroll；设置为 true 后，组件内部主体 Scroll 会应用默认 nestedScroll 配置（scrollForward 与 scrollBackward 均为 NestedScrollMode.SELF_FIRST）。

private refreshConfigurator = new PullToRefreshConfigurator()
  .setHasRefresh(false);

PullToRefresh({
  data: $data,
  scroller: this.scroller,
  enableNestedScroll: true,
  refreshConfigurator: this.refreshConfigurator,
  customList: () => { this.getContentView(); },
  // ...
})

完整示例见 entry 中的 pages/bindSheetPullRefresh.ets。

说明：下拉刷新与下拉关闭 Sheet 均为向下手势，半模态关闭场景建议关闭下拉刷新（setHasRefresh(false)）。上拉加载为向上手势，不受影响，开启 enableNestedScroll 后仍可通过 Scroll.onReachEnd 正常触发。setHasRefresh(false) 不会自动启用嵌套滚动；若需要 bindSheet 与内部 Scroll 协同，需设置 enableNestedScroll: true。开启后组件不再基于 scroller 处理下拉手势，customList 由内部 Scroll 承载，且不要在 customList 内将同一 scroller 绑定到 List、Scroll 等滚动容器。V2 示例见 pages/bindSheetPullRefreshV2.ets。

使用说明

PullToRefresh 组件（@Component）

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

PullToRefreshV2 组件（@ComponentV2）

PullToRefreshV2 提供与 PullToRefresh 相同的刷新与加载能力，面向 @ComponentV2 状态管理能力。

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	是	是
enableNestedScroll	boolean	是否启用组件内置嵌套滚动；开启后主体使用 Scroll 承载，并应用默认 nestedScroll 配置（scrollForward 与 scrollBackward 均为 NestedScrollMode.SELF_FIRST）。下拉刷新不生效，上拉加载通过 Scroll.onReachEnd 触发	false	否	是
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 平台支持
PullToRefreshConfigurator	无	PullToRefreshConfigurator	创建配置类实例	否	是
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: string	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	设置上拉加载更多中时的文本	否	是
getHasRefresh	无	boolean | undefined	获取是否具有下拉刷新功能	否	是
getHasLoadMore	无	boolean | undefined	获取是否具有上拉加载功能	否	是
getMaxTranslate	无	number | undefined	获取可下拉上拉的最大距离	否	是
getSensitivity	无	number | undefined	获取下拉上拉灵敏度	否	是
getListIsPlacement	无	boolean | undefined	获取滑动结束后列表是否归位	否	是
getAnimDuration	无	number | undefined	获取滑动结束后，回弹动画执行时间	否	是
getRefreshHeight	无	number	获取下拉动画高度	否	是
getRefreshWidth	无	number	获取下拉动画宽度（计算值：refreshHeight / 3 * 4）	否	是
getRefreshColor	无	string	获取下拉动画颜色	否	是
getRefreshBackgroundColor	无	ResourceColor	获取下拉动画区域背景色	否	是
getRefreshTextColor	无	ResourceColor	获取下拉加载完毕后提示文本的字体颜色	否	是
getRefreshTextSize	无	number | string | Resource	获取下拉加载完毕后提示文本的字体大小	否	是
getRefreshAnimDuration	无	number | undefined	获取下拉动画执行一次的时间，仅在自定义下拉刷新动画时有效	否	是
getRefreshCompleteTextHoldTime	无	number	获取下拉刷新完毕后，刷新成功文本停留的时间	否	是
getLoadImgHeight	无	number	获取上拉动画中图片的高度	否	是
getLoadBackgroundColor	无	ResourceColor	获取上拉动画区域背景色	否	是
getLoadTextColor	无	ResourceColor	获取上拉文本的字体颜色	否	是
getLoadTextSize	无	number | string | Resource	获取上拉文本的字体大小	否	是
getLoadTextPullUp1	无	ResourceStr | undefined	获取上拉 1 阶段文本	否	是
getLoadTextPullUp2	无	ResourceStr | undefined	获取上拉 2 阶段文本	否	是
getLoadTextLoading	无	ResourceStr	获取上拉加载更多中时的文本	否	是

关于混淆

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

如果希望 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，请自由地享受和参与开源。