• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 下拉刷新与上滑加载案例
2
3### 介绍
4
5本示例介绍使用第三方库的PullToRefresh组件实现列表的下拉刷新数据和上滑加载后续数据。
6
7### 效果图预览
8
9<img src="./pulltorefresh/src/main/resources/base/media/pull_to_refresh_news.gif" width="300">
10
11**使用说明**
12
131. 进入页面，下拉列表触发刷新数据事件，等待数据刷新完成。
142. 上滑列表到底部，触发加载更多数据事件，等待数据加载完成。
15
16### 实现思路
17
181. 使用第三方库pullToRefresh组件，将列表组件、绑定的数据对象和scroller对象包含进去，并添加上滑与下拉方法。源码参考[PullToRefreshNews.ets](./pulltorefresh/src/main/ets/pages/PullToRefreshNews.ets)
19    ```typescript
20    PullToRefresh({
21      // 必传项，列表组件所绑定的数据
22      data: $newsData,
23      // 必传项，需绑定传入主体布局内的列表或宫格组件
24      scroller: this.scroller,
25      // 必传项，自定义主体布局，内部有列表或宫格组件
26      customList: () => {
27        // 一个用@Builder修饰过的UI方法
28        this.getListView();
29      },
30      // 下拉刷新回调
31      onRefresh: () => {
32        return new Promise<string>((resolve, reject) => {
33          ...
34        });
35      },
36      // 上滑加载回调
37      onLoadMore: () => {
38        return new Promise<string>((resolve, reject) => {
39          ...
40        });
41      },
42      customLoad: () => this.customLoad(),
43      customRefresh: null,
44    })
45    ```
462. 使用LazyForEach循环渲染列表。源码参考[PullToRefreshNews.ets](./pulltorefresh/src/main/ets/pages/PullToRefreshNews.ets)
47    ```typescript
48    LazyForEach(this.newsData, (item: NewsData) => {
49      ListItem() {
50        ...
51      }
52    });
53    ```
543. 模拟列表总页数，加载完全部信息后提示已经到底部。源码参考[PullToRefreshNews.ets](./pulltorefresh/src/main/ets/pages/PullToRefreshNews.ets)
55   ```javascript
56   onLoadMore: () => {
57     return new Promise<string>((resolve, reject) => {
58       // 模拟数据列表页超过4页后已到达底部，无法继续加载
59       if (this.newsDataListIndex < NEWS_MAX_LIST) {
60         // 模拟网络请求操作，请求网络1.5秒后得到数据，通知组件变更列表数据
61         setTimeout(() => {
62           let newsModelMockData: Array<NewsData> = getNews(MOCK_DATA_FILE_ONE_DIR)
63           for (let j = 0; j < NEWS_MOCK_DATA_COUNT; j++) {
64             this.newsData.pushData(newsModelMockData[j]);
65           }
66           this.newsDataListIndex++;
67           resolve('');
68         }, NEWS_REFRESH_TIME);
69       } else {
70           // 如果已满4页，更改上拉提示信息提示已经加载完所有数据
71           setTimeout(() => {
72           resolve('');
73         }, NEWS_REFRESH_TIME);
74       }
75     });
76   }
77   ```
784. 自定义下拉更新动画。源码参考[PullToRefreshNews.ets](./pulltorefresh/src/main/ets/pages/PullToRefreshNews.ets)
79   ```typescript
80   @Builder
81   private customRefresh() {
82      Row() {
83         // 下滑加载图片
84         Image($r('app.media.pull_icon_load'))
85            .width($r('app.string.pull_refresh_load_width'))
86            .height($r('app.string.pull_refresh_load_height'))
87            .objectFit(ImageFit.Contain)
88            .rotate({
89               z: 1,
90               angle: this.angle2 !== undefined ? this.angle2 : 0
91            })
92            .width(this.refreshConfigurator.getLoadImgHeight())
93            .height(this.refreshConfigurator.getLoadImgHeight())
94
95         // 下拉时提示文本
96         Stack() {
97            Text(CURRENT_DATA_TIP)
98               .height($r('app.string.pull_refresh_load_height'))
99               .textAlign(TextAlign.Center)
100               .margin({ left: this.newsDataListIndex === NEWS_MAX_LIST && this.isLoading ? 0 : 8 })
101               .fontColor(this.refreshConfigurator !== undefined ? this.refreshConfigurator.getLoadTextColor() : 0)
102               .fontSize(this.refreshConfigurator !== undefined ? this.refreshConfigurator.getLoadTextSize() : 0)
103               .visibility(this.pullHeightValue <= CHANGE_PAGE_STATE ? Visibility.Visible : Visibility.Hidden)
104            Text(NEW_DATA_TIP)
105               .height($r('app.string.pull_refresh_load_height'))
106               .textAlign(TextAlign.Center)
107               .margin({ left: this.newsDataListIndex === NEWS_MAX_LIST && this.isLoading ? 0 : 8 })
108               .fontColor(this.refreshConfigurator !== undefined ? this.refreshConfigurator.getLoadTextColor() : 0)
109               .fontSize(this.refreshConfigurator !== undefined ? this.refreshConfigurator.getLoadTextSize() : 0)
110               .visibility(this.pullHeightValue > CHANGE_PAGE_STATE ? Visibility.Visible : Visibility.Hidden)
111         }
112      }
113      .height($r('app.string.pull_refresh_load_height'))
114   }
115   ```
1165. 通过下拉距离判断页面是刷新当前数据还是更新为下一页。源码参考[PullToRefreshNews.ets](./pulltorefresh/src/main/ets/pages/PullToRefreshNews.ets)
117   ```typescript
118   onAnimPullDown: (value) => {
119      this.pullHeightValue = value;
120   },
121   onAnimRefreshing: (value, width, height) => {
122      if (value !== undefined && width !== undefined && height !== undefined) {
123         if (value) {
124            this.angle2 = value * 360;
125            if (this.pullHeightValue > LOAD_PULL_STATE_CHANGE && this.pullHeightValue <= CHANGE_PAGE_STATE) {
126               this.isChangePage = false;
127            } else {
128               // 当下拉到最顶部时，触发更新页面，不再刷新当前页。
129               this.isChangePage = true;
130            }
131         }
132      }
133   }
134   ```
1356. 自定义上拉加载动画。源码参考[PullToRefreshNews.ets](./pulltorefresh/src/main/ets/pages/PullToRefreshNews.ets)
136   ```typescript
137   @Builder
138   private customLoad() {
139     Row() {
140       Stack() {
141         // 上拉1阶段箭头图片
142         Image(pull_icon_up)
143           .width('100%')
144           .height('100%')
145           .objectFit(ImageFit.Contain)
146           .visibility(this.isPullUp ? Visibility.Visible : Visibility.Hidden)
147           .rotate({
148             z: 1,
149             angle: this.angle1 !== undefined ? this.angle1 : 0
150           })
151         // 加载时图片
152         Image(pull_icon_load)
153           .width('100%')
154           .height('100%')
155           .objectFit(ImageFit.Contain)
156           .visibility(this.isLoading ? Visibility.Visible : Visibility.Hidden)
157           .rotate({
158             z: 1,
159             angle: this.angle2 !== undefined ? this.angle2 : 0
160           })
161       }
162       // 最后一页加载时隐藏加载图片
163       .width(this.newsDataListIndex === NEWS_MAX_LIST && this.isLoading ? 0 :
164       this.refreshConfigurator.getLoadImgHeight())
165       .height(this.newsDataListIndex === NEWS_MAX_LIST && this.isLoading ? 0 :
166       this.refreshConfigurator.getLoadImgHeight())
167
168       // 上拉过程与加载时提示文本
169       Text(this.loadText)
170         .height('100%')
171         .textAlign(TextAlign.Center)
172         .margin({ left: this.newsDataListIndex === NEWS_MAX_LIST && this.isLoading ? 0 : 8 })
173         .fontColor(this.refreshConfigurator !== undefined ? this.refreshConfigurator.getLoadTextColor() : 0)
174         .fontSize(this.refreshConfigurator !== undefined ? this.refreshConfigurator.getLoadTextSize() : 0)
175     }
176     .height('100%')
177   }
178   ```
1797. 设置上拉与加载时的动画回调。源码参考[PullToRefreshNews.ets](./pulltorefresh/src/main/ets/pages/PullToRefreshNews.ets)
180   ```typescript
181   onAnimPullUp: (value, width, height) => {
182     if (value !== undefined && width !== undefined && height !== undefined) {
183       if (value) {
184         this.isLoading = false;
185         this.isPullUp = true;
186         // 判断上拉拖拽过程中高度是否超过阶段临界值
187         if (value < LOAD_PULL_STATE_CHANGE) {
188           // 归零角度，保持箭头朝上
189            this.angle1 = 0;
190            // 改变提示文本为上拉1阶段
191            this.loadText = LOAD_TEXT_PULL_UP_1;
192         } else {
193           // 翻转角度，保持箭头朝下
194            this.angle1 = 180;
195            // 改变提示文本为上拉2阶段
196            this.loadText = LOAD_TEXT_PULL_UP_2;
197         }
198       }
199     }
200   },
201
202   onAnimLoading: (value, width, height) => {
203     if (value !== undefined && width !== undefined && height !== undefined) {
204       if (value) {
205         this.isPullUp = false;
206         this.isLoading = true;
207         // 更改角度使加载图片保持旋转
208         this.angle2 = value * 360;
209         // 判读页码是否为最后一页
210         if (this.newsDataListIndex !== NEWS_MAX_LIST) {
211           this.loadText = LOAD_DEFAULT_TEXT;
212         } else {
213           // 最后一页更换文本提示已经到底了
214           this.loadText = LOAD_STOP_TEXT;
215         }
216       }
217     }
218   }
219   ```
220### 高性能知识点
221
222不涉及
223
224### 工程结构&模块类型
225   ```
226   pulltorefreshnews                     // har类型
227   |---model
228   |---|---AppInfo.ets                   // App信息
229   |---|---UserInformation.ets           // 用户信息
230   |---view
231   |---|---PullToRefreshNews.ets         // 视图层-场景列表页面
232   ```
233
234### 模块依赖
235
236[PullToRefresh](https://gitee.com/openharmony-sig/PullToRefresh)
237
238### 参考资料
239
240[PullToRefresh](https://gitee.com/openharmony-sig/PullToRefresh)
241[LazyForEach](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-rendering-control-lazyforeach.md)
242[PullToRefresh第三方库](https://ohpm.openharmony.cn/#/cn/detail/@ohos%2Fpulltorefresh)
243
244### 相关权限
245
246不涉及。
247
248### 依赖
249
250不涉及。
251
252### 约束与限制
253
2541.本示例仅支持标准系统上运行，支持设备：RK3586。
255
2562.本示例为Stage模型，支持API12版本SDK，SDK版本号（API Version 12 Release）。
257
2583.本示例需要使用DevEco Studio版本号（DevEco Studio 5.0.0 Release）及以上版本才可编译运行。
259
260### 下载
261
262如需单独下载本工程，执行如下命令：
263
264```shell
265git init
266git config core.sparsecheckout true
267echo code/UI/PullToRefresh/ > .git/info/sparse-checkout
268git remote add origin https://gitee.com/openharmony/applications_app_samples.git
269git pull origin master