pullRefreshLoop

来自于:开发者立即使用

setCustomRefreshHeaderInfo refreshHeaderLoading refreshHeaderLoadDone

论坛示例

为帮助用户更好更快的使用模块,论坛维护了一个示例,示例中包含示例代码、知识点讲解、注意事项等,供您参考。

概述

本模块可实现的下拉刷新示例图如下:

图片说明

随着用户对 App 使用体验的要求不断提升,传统的下拉刷新动画和模式已经无法满足用户挑剔的视觉体验。为满足广大开发者对下拉刷新功能的需求,我们推出了最新最炫的下拉刷新模块助您提升 App 逼格。

从用户体验考虑,下拉刷新的实现不能简单粗暴的用一张 GIF 图片来完成,我们需要遵照原生动画理念,使用关键帧(即多张具有微小差别的图片)来完成完整的动画过程。

下拉刷新简介

下拉刷新是指在一个可上下拖动查看内容的支持弹动功能的窗体(frame、window)中,用户通过下拉触发刷新数据事件从而加载数据刷新页面的过程。

此过程可拆分为四个组成部分:

  • 一,下拉过程
  • 二,下拉高度达到一定阈值后触发加载事件
  • 三,加载状态
  • 四,数据加载完成后刷新页面并停止加载状态(恢复常态)

模块概述

pullRefreshLoop 模块对引擎新推出的下拉刷新接口进行了一层封装,App 可以通过此模块来实现带炫酷动画效果的下拉刷新功能。使用此模块,在用户下拉时本模块会随用户下拉高度而显示出下拉出的提示图标;当下拉高度到一定阈值后出发加载事件,与此同时,下拉提示图标会改变为一直旋转状态,将下拉刷新事件回发给前端。下拉图标及背景图是通过 api.setCustomRefreshHeaderInfo 接口传给模块的。前端得到下拉刷新事件后开始加载数据;数据加载完毕,调用接口 api.refreshHeaderLoadDone 以停止加载状态;

模块使用攻略

对于 APICloud 平台上的普通模块,在相应接口调用前需要先 require 该模块,但由于本模块是基于引擎下拉刷新功能扩展的模块,所以本模块使用方法比较特殊。可以不必 require 模块,改为在 config.xml 文件内配置模块。

config.xml 文件配置示例如下:

  1. <preference name="customRefreshHeader" value="pullRefreshLoop"/>

config.xml 配置后,则本模块为全局对象,可以在任意可弹动的窗体(frame、window)中调用 api.setCustomRefreshHeaderInfo 接口设置该下拉刷新样式,以及开始、停止刷新加载状态(api.refreshHeaderLoading、api.refreshHeaderLoadDone)。

若想在不同的 window 或 frame 使用不同的下拉刷新模块,开发者可以在 window 或 frame 打开时传入参数 customRefreshHeader:’下拉刷新模的块名’,以指定该窗体的下拉刷新模块。如:

  1. {
  2. api.openFrame({
  3. name: 'pullRefreshLoop-con',
  4. url: './pullRefreshLoop-con.html',
  5. customRefreshHeader: '下拉刷新模块名',
  6. bounces: true,
  7. rect: {
  8. x: offset.l,
  9. y: offset.t + offset.h,
  10. w: offset.w,
  11. h: bodyHeight - offset.h
  12. }
  13. });
  14. }

注意:本模块无接口,模块的所有功能都通过 api 对象的相应接口实现

实例widget下载

功能接口

setCustomRefreshHeaderInfo

配置下拉刷新样式

api.setCustomRefreshHeaderInfo({params}, callback())

params

  • 类型:JSON 对象类型
  • 描述:启用下拉刷新及其样式的配置
  • 内部字段:
  1. {
  2. refreshStyle: 'render' // (可选项) 字符串类型;下拉刷新的样式;默认值:'pull'(Android仅支持pull)
  3. // 取值范围:
  4. // 'render' :边下拉边渲染样式
  5. // 'pull' : 下拉样式
  6. bgColor: '#C0C0C0', //(可选项)字符串类型;下拉刷新的背景设置,支持 rgb、rgba、#,该背景大小同当前 window 或 frame 的宽高;默认:#C0C0C0
  7. image: { //JSON 对象类型;下拉刷新相关图片设置
  8. icon: 'fs://res/miao.png', //(可选项)字符串类型;下拉过程中的背景图片,图片规格为正方形,如50*50、100*100,为适配高清屏幕建议开发者传大小合适的图片,若不传则显示默认图标
  9. borderColor: '#f00', //字符串类型;下拉刷新的边线颜色
  10. gapColor: '#fff', //(可选项)字符串类型:下拉刷新边线的间隙颜色,支持 rgb、rgba、#;默认:同bgColor
  11. },
  12. animationRate:1 //(可选项)字符串类型;动画速率;默认值为1
  13. }

callback()

当用户下拉的高度达到阈值(本下拉模块的阈值为64)后抬起拖动手指才可触发刷新事件,此时模块才会将该事件回调给前端。

示例代码

  1. api.setCustomRefreshHeaderInfo({
  2. bgColor: '#C0C0C0',
  3. image: {
  4. icon: 'widget://image/refresh/miao.png',
  5. borderColor: '#f00'
  6. },
  7. animationRate:1
  8. }, function() {
  9. alert('下拉刷新事件触发了,摇动手机关闭下拉状态');
  10. api.addEventListener({
  11. name: 'shake'
  12. }, function(ret, err) {
  13. api.refreshHeaderLoadDone()
  14. });
  15. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

refreshHeaderLoading

手动开始下拉刷新的加载状态,下拉刷新状态亦可通过用户下拉到阈值自动触发

api.refreshHeaderLoading()

示例代码

  1. api.refreshHeaderLoading();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

refreshHeaderLoadDone

手动停止下拉刷新的加载状态

api.refreshHeaderLoadDone()

示例代码

  1. api.refreshHeaderLoadDone();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本