mescroll的uni版本 1.3.8 文档 2023年03月27日
GitHubmescroll的uni版本, 是在 uni-app 运行的下拉刷新和上拉加载的组件
简单介绍 :
1. mescroll的uni版本, 是专门用在uni-app的下拉刷新和上拉加载的组件, 支持一套代码编译到iOS、Android、H5、小程序等多个平台
2. mescroll的uni版本, 继承了mescroll.js的实用功能: 自动处理分页, 自动控制无数据, 空布局提示, 回到顶部按钮 ..
3. mescroll的uni版本, 丰富的案例, 自由灵活的api, 超详细的注释, 可让您快速自定义真正属于自己的下拉上拉组件
4. mescroll的uni版本, 提供<mescroll-body>和<mescroll-uni>两个组件, 其中<mescroll-body>支持配置成系统自带的下拉组件
5. <mescroll-body>是1.2.1版本新增的组件, 用来填补<mescroll-uni>的不足 :
快速开始 :
1. 插件市场, 点击右侧的"使用HBuilderX导入插件"按钮 (如需 npm 安装,请查看 '注意事项6')
2. 下载示例, 找到合适的示例, 搬运代码(砖头), 比看下面的文档快多啦 ~O(∩_∩)O~
mescroll-body :
1. 无需配置pages.json (检查是否配置了多余的属性):
{
"path" : "pages/xxx/xxx", // 在具体的页面中, mescroll-body 无需像 mescroll-uni 那样需要配置 pages.json
"style" : {
"navigationBarTitleText" : "xxx",
"backgroundColorTop":"#FFFFFF", // iOS下拉bounce回弹区域的颜色 (与down.bgColor同步)
"backgroundColorBottom":"#FFFFFF", // iOS上拉bounce回弹区域的颜色 (与up.bgColor同步)
"disableScroll": false, //删除此项: mescroll-body必须允许原生页面滚动, 默认false
"enablePullDownRefresh" : false, //删除此项: 不开启系统自带的下拉刷新, 默认false
"app-plus" : {
"bounce" : "none" //可选: 是否禁止iOS回弹和Android触顶触底的弧形阴影, 默认允许 (可配在 'globalStyle')
},
"mp-alipay":{"allowsBounceVertical":"NO"} //可选: 取消支付宝和钉钉小程序的iOS回弹 (可配在 'globalStyle')
}
},
"globalStyle" : {
"backgroundColorTop":"#FFFFFF" // iOS APP真机bounce回弹区域默认灰色,建议统一重置为白色
}
2. 在具体页面中的示例 (vue2) :
<template>
<view>
<mescroll-body @init="mescrollInit" @down="downCallback" @up="upCallback" :down="downOption" :up="upOption">
// @init="mescrollInit" @down="downCallback" @up="upCallback"为固定值,不可删改(与mescroll-mixins保持一致)
// :down="downOption" :up="upOption" 绝大部分情况无需配置
// :top="顶部偏移量" :bottom="底部偏移量" :topbar="状态栏" :safearea="安全区" (常用)
// 此处支持写入原生组件
<view v-for="data in dataList"> 数据列表... </view>
</mescroll-body>
<view>fixed元素需写在mescroll-body的外面,否则下拉刷新时会降级为absolute <view>
</view>
</template>
<script>
// 引入mescroll-mixins.js
import MescrollMixin from "@/uni_modules/mescroll-uni/components/mescroll-uni/mescroll-mixins.js";
import MescrollMixin from "@/components/mescroll-uni/mescroll-mixins.js"; // 非uni_modules版本
import MescrollBody from "@/components/mescroll-uni/mescroll-body.vue"; // 非uni_modules版本
export default {
mixins: [MescrollMixin], // 使用mixin
components: {
MescrollBody
},
data() {
return {
mescroll: null, // mescroll实例对象 (此行可删,mixins已默认)
// 下拉刷新的配置(可选, 绝大部分情况无需配置)
downOption: {
...
},
// 上拉加载的配置(可选, 绝大部分情况无需配置)
upOption: {
page: {
size: 10 // 每页数据的数量,默认10
},
noMoreSize: 5, // 配置列表的总数量要大于等于5条才显示'-- END --'的提示
empty: {
tip: '暂无相关数据'
}
},
// 列表数据
dataList: []
}
},
methods: {
/*mescroll组件初始化的回调,可获取到mescroll对象 (此处可删,mixins已默认)*/
mescrollInit(mescroll) {
this.mescroll = mescroll;
},
/*下拉刷新的回调, 重置列表为第一页 (此处可删,mixins已默认)
downCallback(){
this.mescroll.resetUpScroll();
},
/*上拉加载的回调*/
upCallback(page) {
// 此处可以继续请求其他接口
// if(page.num == 1){
// // 请求其他接口...
// }
// 如果希望先请求其他接口,再触发upCallback,可参考以下写法
// if(!this.isInitxx){
// apiGetxx().then(res=>{
// this.isInitxx = true
// this.mescroll.resetUpScroll() // 重新触发upCallback
// }).catch(()=>{
// this.mescroll.endErr()
// })
// return // 此处return,先获取xx
// }
let pageNum = page.num; // 页码, 默认从1开始
let pageSize = page.size; // 页长, 默认每页10条
uni.request({
url: 'xxxx?pageNum='+pageNum+'&pageSize='+pageSize,
success: (data) => {
// 接口返回的当前页数据列表 (数组)
let curPageData = data.xxx;
// 接口返回的当前页数据长度 (如列表有26个数据,当前页返回8个,则curPageLen=8)
let curPageLen = curPageData.length;
// 接口返回的总页数 (如列表有26个数据,每页10条,共3页; 则totalPage=3)
let totalPage = data.xxx;
// 接口返回的总数据量(如列表有26个数据,每页10条,共3页; 则totalSize=26)
let totalSize = data.xxx;
// 接口返回的是否有下一页 (true/false)
let hasNext = data.xxx;
//设置列表数据
if(page.num == 1) this.dataList = []; //如果是第一页需手动置空列表
this.dataList = this.dataList.concat(curPageData); //追加新数据
// 请求成功,隐藏加载状态
//方法一(推荐): 后台接口有返回列表的总页数 totalPage
this.mescroll.endByPage(curPageLen, totalPage);
//方法二(推荐): 后台接口有返回列表的总数据量 totalSize
//this.mescroll.endBySize(curPageLen, totalSize);
//方法三(推荐): 您有其他方式知道是否有下一页 hasNext
//this.mescroll.endSuccess(curPageLen, hasNext);
//方法四 (不推荐),会存在一个小问题:比如列表共有20条数据,每页加载10条,共2页.
//如果只根据当前页的数据个数判断,则需翻到第三页才会知道无更多数据
//如果传了hasNext,则翻到第二页即可显示无更多数据.
//this.mescroll.endSuccess(curPageLen);
// 如果数据较复杂,可等到渲染完成之后再隐藏下拉加载状态: 如
// 建议使用setTimeout,因为this.$nextTick某些情况某些机型不触发
setTimeout(()=>{
this.mescroll.endSuccess(curPageLen)
},20)
// 上拉加载的 curPageLen 必传, 否则会一直显示'加载中...':
1. 使配置的noMoreSize 和 empty生效
2. 判断是否有下一页的首要依据:
当传的值小于page.size时(说明不满页了),则一定会认为无更多数据;
比传入的totalPage, totalSize, hasNext具有更高的判断优先级;
3. 当传的值等于page.size时(满页),才取totalPage, totalSize, hasNext判断是否有下一页
传totalPage, totalSize, hasNext目的是避免方法四描述的小问题
// 提示: 您无需额外维护页码和判断显示空布局,mescroll已自动处理好.
// 当您发现结果和预期不一样时, 建议再认真检查以上参数是否传正确
},
fail: () => {
// 请求失败,隐藏加载状态
this.mescroll.endErr()
}
})
},
/*若希望重新加载列表,只需调用此方法即可(内部会自动page.num=1,再主动触发up.callback)*/
reloadList(){
this.mescroll.resetUpScroll();
}
}
}
</script>
2. 在具体页面中的示例 (vue3) :
<template>
<mescroll-body @init="mescrollInit" @down="downCallback" @up="upCallback">
// mescroll的极简示例,大部分情况就是这么用
</mescroll-body>
</template>
<script setup>
import { ref } from 'vue';
import { onPageScroll, onReachBottom } from '@dcloudio/uni-app';
import useMescroll from "@/uni_modules/mescroll-uni/hooks/useMescroll.js";
import {apiGoods} from "@/api/mock.js"
// 数据列表
const goods = ref([])
// 调用mescroll的hook (注: mescroll-uni不用传onPageScroll,onReachBottom, 而mescroll-body必传)
const { mescrollInit, downCallback, getMescroll } = useMescroll(onPageScroll, onReachBottom)
// 上拉加载的回调: 其中num:当前页 从1开始, size:每页数据条数,默认10
const upCallback = (mescroll)=>{
apiGoods(mescroll.num, mescroll.size).then(res=>{
const curPageData = res.list || [] // 当前页数据
if(mescroll.num == 1) goods.value = []; // 第一页需手动制空列表
goods.value = goods.value.concat(curPageData); //追加新数据
//联网成功的回调,隐藏下拉刷新和上拉加载的状态;
//mescroll会根据传的参数,自动判断列表如果无任何数据,则提示空;列表无下一页数据,则提示无更多数据;
//方法一(推荐): 后台接口有返回列表的总页数 totalPage
//mescroll.endByPage(curPageData.length, totalPage); //必传参数(当前页的数据个数, 总页数)
//方法二(推荐): 后台接口有返回列表的总数据量 totalSize
//mescroll.endBySize(curPageData.length, totalSize); //必传参数(当前页的数据个数, 总数据量)
//方法三(推荐): 您有其他方式知道是否有下一页 hasNext
//mescroll.endSuccess(curPageData.length, hasNext); //必传参数(当前页的数据个数, 是否有下一页true/false)
//方法四 (不推荐),会存在一个小问题:比如列表共有20条数据,每页加载10条,共2页.如果只根据当前页的数据个数判断,则需翻到第三页才会知道无更多数据.
mescroll.endSuccess(curPageData.length); // 请求成功, 结束加载
}).catch(()=>{
mescroll.endErr(); // 请求失败, 结束加载
})
}
</script>
// 某些情况下手动重置列表的方法
// getMescroll().resetUpScroll()
mescroll-uni :
1. 需要配置 pages.json :
{
"path" : "pages/xxx/xxx", // 在具体的页面中, mescroll-uni 需要配置 pages.json, 而mescroll-body不需要
"style" : {
"navigationBarTitleText" : "xxx",
"enablePullDownRefresh" : false, // 删除此项: 不开启系统自带的下拉刷新, 默认false
"disableScroll": false, // 删除此项, 否则页面无法滚动
"app-plus" : {
"bounce" : "none" // 取消APP端iOS回弹,避免与下拉刷新冲突 (可统一配在 'globalStyle')
},
"mp-alipay":{"allowsBounceVertical":"NO"} // 取消支付宝和钉钉小程序的iOS回弹,避免与下拉刷新冲突 (可统一配在 'globalStyle')
}
}
2. 在具体页面中的示例 :
<template>
<view>
<mescroll-uni @init="mescrollInit" @down="downCallback" @up="upCallback" :down="downOption" :up="upOption" >
// 此处除了不能写原生组件,其他的与 mescroll-body 的一致>
</mescroll-uni>
<view>原生组件和fixed元素需写在mescroll-uni的外面,否则滚动列表时会抖动 <view>
<view>
</template>
<script>
// 与 mescroll-body 的一致>
</script>
mescroll-empty:
1.2.0版本开始独立出空布局组件<mescroll-empty>, 以便在不使用mescroll的界面也能统一管理空布局:
<template>
<view>
// 基本用法:
<mescroll-empty v-if="list.length==0"></mescroll-empty>
// 完整配置项 (option同up.empty的配置一致)
<mescroll-empty v-if="isShowEmpty" :option="optEmpty" @emptyclick="emptyClick"></mescroll-empty>
</view>
</template>
<script>
uni_modules版本的mescroll-empty 支持 easycom, 已无需手动注册组件
import MescrollEmpty from '@/components/mescroll-uni/components/mescroll-empty.vue';
export default {
components: {
MescrollEmpty
},
...
}
自定义mescroll :
快速的自定义是mescroll的优势, 您可以随心所欲的进行全局配置 和 在具体界面的自定义
1. 可以直接修改 /components/mescroll-uni/mescroll-uni-option.js 进行全局配置
2. 在具体的页面中,您可以配置downOption 和 upOption 实现具体界面的自定义, 建议参考mescroll-options.vue
3. 深度定制化, 请下载和参考mescroll的中高级案例
4. APP,H5,微信小程序使用的是wxs, 所以动画以wxs为准. 若要自定义动画还需修改 /components/mescroll-uni/wxs/wxs.wxs
5. 自定义loading动画推荐: https://loading.io 和 https://icons8.com/preloaders/
参数说明 :
常用方法 :
其他方法 :
下载案例:
所有vue2,vue3示例源码,点此获取 (含高级示例)>> (插件市场右上角的 "使用HBuilderX导入示例项目"或"下载示例项目ZIP")
注意事项 :
1. 请一定要记住一个经常经常会用到的方法: this.mescroll.resetUpScroll()
比如你想在onShow中刷新一下列表, 比如点击tab切换时重新加载列表, 比如搜索条件变化或状态更新时重置列表数据
那么你只需调用 this.mescroll.resetUpScroll() 方法即可 (内部会自动page.num=1,再主动触发up.callback)
2. 当详情页返回到列表页,想在列表页的onShow重新加载列表数据时, 可以通过配置down和up的auto为false, 然后在onShow中延时调用this.downCallback实现;
还有一个最简单的方式,完全不用配置auto为false, 只需在onShow加一个变量控制即可 (推荐):
// 详情返回列表,重新加载列表数据
onShow() {
this.canReset && this.mescroll.resetUpScroll() // 重置列表数据为第一页
this.canReset && this.mescroll.scrollTo(0,0) // 重置列表数据为第一页时,建议把滚动条也重置到顶部,避免无法再次翻页的问题
this.canReset = true // 过滤第一次的onShow事件,避免初始化界面时重复触发upCallback, 无需配置auto:false
// 注意: 子组件没有 onShow 的生命周期, 所以
// 对于 mescroll-more.vue 和 mescroll-swiper.vue 的返回刷新, 需更新 1.3.3 版本, 且参考对应示例的onShow写法
}
3. mescroll-body是原生界面的滚动,依赖于onPageScroll和onReachBottom的页面生命周期, 所以mescroll-body尽量不要写在页面的子组件里, 因为子组件无页面的这些生命周期;
如果非要写在子组件中,则需在页面给子组件传入onPageScroll,onReachBottom,否则无法正常滑动列表和触发上拉加载;
强烈推荐参考 mescroll-comp.vue 或 mescroll-more.vue 的案例, 通过mixins传入最简单. 进入插件市场下载案例>
(或改用 mescroll-uni , 无此限制, 无此问题 : <mescroll-uni height="100%" top="xx" ... )
4. 一个.vue文件只能存在一个mescroll组件, 如果要多mescroll组件, 需分别封装到子组件中
如: tab切换, 页面存在多个mescroll组件, 那么请严格参考 mescroll-more.vue 或 mescroll-swiper.vue 示例的写法
把每个mescroll组件分别封装在子组件中 ( 比如封装为 mescroll-more-item.vue )
5. down和up的配置项不是响应式的, 如果要动态修改配置, 可通过 this.mescroll.optDown 和 this.mescroll.optUp 动态修改
比如,可以动态设置 this.mescroll.optDown.isLock = false/true 来实现动态开关下拉刷新
比如,可以动态设置 this.mescroll.optUp.empty.icon = "xxx.png" 来动态设置空布局的图标
6. mescroll支持npm安装: npm install --save mescroll-uni
引入mescroll-body组件: import MescrollBody from "mescroll-uni/mescroll-body.vue";
引入mescroll-uni组件: import MescrollUni from "mescroll-uni/mescroll-uni.vue";
但不推荐npm安装, 因为设置mescroll为全局组件, 编译到APP可能会失效
这是HBuilderX编辑器的问题, 详见: https://ask.dcloud.net.cn/question/73950
也可能会使js中的条件编译失效, 详见: https://github.com/mescroll/mescroll/issues/351
7. Android小程序下拉时image和swiper脱离文档流的问题, 已在1.3.1版本修复
APP端下拉时video脱离文档流的问题, 已在1.3.3版本的 mescroll-options.vue 提供解决方案, 请下载查看
8. 其他: 点此查看常见问题>
Copyright © 2017-2025 mescroll.com All Rights Reserved 粤ICP备17076411号-1