refreshable_view_miniprogram

Refreshable View通过简单的方式实现了scroll-view的下拉刷新以及滚动加载，并且提供了便利的自定义机制，方便用户替换不同的刷新/加载方式与动画。

• 特点
• 要求
• 安装说明
• 使用说明
  • 参数说明
  • RefresherType类型说明
  • LottieLoadings类型说明
  • 组件事件说明
  • 使用案例
• 使用许可

特点

• [x] 下拉刷新/加载
• [x] 滚动刷新/加载
• [x] 基于 lottie 的加载动画
• [x] 自定义 lottie 动画
• [x] 兼容刷新/加载打断
• [x] 加载动画时长控制
• [ ] 完全自定义的加载动画（未测试）
• [ ] 兼容横向刷新/加载
• [ ] 加载结果提示

效果展示

• 组件效果

下拉刷新	上拉加载

• 预设动画

lava-preloader	heart-fill	circle	holographic-radar

loading-down-fall	cycle-man	airplane

在整个基于 lottie 的动画处理中，都是直接传递 lottiefiles.com 中的 lottie json 文件地址来实现的，你也选择任何你喜爱的动画（不过貌似微信小程序的 canvas 绘制表现会有某些不兼容)，在这里感谢以上这些动画的作者。

要求

平台	最低基础库版本	安装说明	状态
WeChat	2.8.3	npm	未全部实机测试

安装说明

npm

npm 是 JavaScript 世界的包管理工具,并且是 Node.js 平台的默认包管理工具。通过 npm 可以安装、共享、分发代码,管理项目依赖关系。

1. 安装 npm 包

首先在小程序根目录下(如果根目录中已经存在package.json文件则直接添加依赖):

npm init

生成npm的package.json配置文件，并且添加依赖:

{
  "dependencies": {
      "refreshable_view_miniprogram": "^0.1.2"
    }
}

在小程序根目录中执行命令安装 npm 包:

npm install

也可以跳过对package.json文件对配置，直接进行安装:

npm install --save refreshable-view-miniprogram

2. 构建 npm

点击微信开发者工具中的菜单栏：工具--->构建 npm :

3. 使用 npm 模块

点击微信开发工具：详情--->本地设置--->使用 npm 模块:

4. 使用 npm 包

• js文件中引入:

import {LottieLoadings} from 'refreshable-view-miniprogram/utilies/lotte-loadings';
import {RefresherType} from "refreshable-view-miniprogram/index";

• 组件引入:

{
  "usingComponents": {
    "refreshable-view": "refreshable-view-miniprogram/index"
  }
}

其他微信小程序 npm 使用问题可以参考说明

使用说明

组件参数说明

参数	数值类型	默认	说明
enableLeadingRefresh	Boolean	true	控制是否可以进行 Leading 刷新/加载操作
enableTrailingRefresh	Boolean	true	控制是否可以进行 Trailing 刷新/加载操作
leadingRefresherType	RefresherType	参见下文	控制 Leading Refresher 的表现
trailingRefresherType	RefresherType	参见下文	控制 Trailing Refresher 的表现
leadingPullingThreshold	Number	50	控制激活 Leading Refresh 的阈值
trailingPullingThreshold	Number	50	控制激活 Trailing Refresh 的阈值
minimumRefreshDuration	Number	1200	控制刷新动画时长 ｜

RefresherType类型说明

// 默认RefresherType 数据
RefresherType({
  type: 'lottie-loading',
  height: 50,
  data: LottieLoadings.circle()
})

• type 参数:

• 'lottie-loading' ，基于 pull to refresh 机制进行刷新/加载，使用 lottie 动画实现刷新/加载的用户反馈
• 'custom-loading' ，基于 pull to refresh 机制进行刷新/加载，使用用户自定义动画实现刷新/加载的用户反馈
• 'sentinel-loading' ，基于 scroll to load 机制进行刷新/加载
• 'none' ，关闭刷新/加载

• height 参数:

在 type 参数为 'lottie-loading' 和 'custom-loading' 时有效，用于控制 Refresher 的高度。

• data 参数:

在 type 参数为 'lottie-loading' 时有效，用于控制 Refresher 的动画表现

LottieLoadings类型说明

LottieLoadings({
  path: 'https://assets6.lottiefiles.com/packages/lf20_mniampqn.json',
  speed: 2
})

• path 参数:

lottie 动画的 url 地址，默认数据来源于lottiefiles.com

• speed 参数：

控制 lottie 动画的播放速度

在这里预设了七个不同的加载动画，你也可以自己生成其他 LottieLoadings 对象来自定义加载动画

组件事件说明

• onLeadingPulling 与 onTrailingPulling 事件

所有Refresher Type 都会触发此类事件，并且回返回以下数据信息：

{
  instance,                     // 当前组件的实例对象 
  offset,                       // 下拉刷新的偏移值
  percentage                    // 下拉刷新的偏移值与下拉刷新的阈值的比值
}

• onLeadingRefreshing 与 onTrailingRefreshing 事件

当对应 RefresherType 的类型不为 'none' 时都会触发此类事件，并且返回以下数据信息：

{
  instance,                    // 当前组件的实例对象
  success(completion),         // 刷新成功的回调函数，在数据刷新结束后调用 success 方法并且将页面刷新代码传入 completion 回调 
  fial                         // 暂未实现
}

组件内容布局说明

为了保证统一性，组件的 container-view 默认对其子内容（即用户添加的滚动内容）使用 flex 布局。关于 flex 布局可以参考

使用案例

该案例中有以下几点需要注意：

1. 为了滚动手势的正确性，在 index.json 中设置 disableScroll: true 。
2. 模拟器上测试时需在微信开发者工具中关闭域名校验，实机测试请开启调试模式。
3. 模拟数据的 API 来自于 Random Data API ，头像 API 来自于 DiceBear Avatars ，在这里表示感谢，其次国内访问他们 API 貌似会有卡顿，可尝试科学上网。

具体参看 Demo 。 本项目基于 小程序自定义组件开发模版 开发，具体测试操作参见该模板说明。

使用许可

refreshable-view-miniprogram is released under the MIT license. 查看详情