vue-slim-better-scroll

开箱即用的/渐进式的 vue移动端滚动组件/插件,基于better-scroll

✨ 特性

  • 极简使用
    • 零配置/渐进式配置
    • 自动刷新滚动高度
  • 更优性能
    • 使用 transform 替代 position ,下拉刷新不再掉帧
  • 更好体验
    • 滚动内容小于滚动视口时,也可以滚动/回弹/下拉刷新/上拉加载
    • 多次下拉刷新节流
    • 多处细节改进
  • 更小体积
    • v1.5.0+ 使用 dio 构建,仅 25k (旧版本为 webpack 构建,体积 47k)
    • v1.6.0+ 抛弃 gif,使用 css 重构 Loading。体积近一步减小,仅 21k

🐠 示例

Demo

Demo 源码

Demo2: 结合 vue-router

Demo2 源码

🚀 快速开始

  1. 安装
yarn add vue-slim-better-scroll # 或 npm i -S vue-slim-better-scroll
  1. 引入
  • 插件形式全局引入
// 入口文件 main.js 中
import Scroll from 'vue-slim-better-scroll'
Vue.use(Scroll)
  • 组件形式引入
// *.vue 中
import Scroll from 'vue-slim-better-scroll'
export default {
  /* ... */
  components: {
    Scroll,
  }
  /* ... */
}
  1. 使用它,请参考Demo 源码
<!-- 简单场景 -->
<Scroll
  ref="scroll"
  :autoUpdate="true"
  @pullingDown="loadRefresh"
  @pullingUp="loadMore">
    <!-- 滚动的内容 -->
</Scroll>

<!-- 复杂场景 -->
<Scroll
  ref="scroll"
  :updateData="[data]"
  :refreshData="[]"
  @pullingDown="loadRefresh"
  @pullingUp="loadMore">
    <!-- 滚动的内容 -->
</Scroll>

🔌 API文档

Props

参数说明类型默认值
probeType派发scroll事件的条件Number1
listenScroll是否监听滚动,开启后才能派发scroll事件Booleanfalse
listenBeforeScrollStart是否监听滚动之前,开启后才能派发beforeScrollStart事件Booleanfalse
scrollX开启X轴滚动Booleanfalse
scrollY开启Y轴滚动Booleantrue
scrollbar开启滚动条Boolean or Objectfalse
pullDown启用下拉刷新Booleantrue
pullDownConfig下拉刷新配置Object{
threshold: 90, // 触发 pullingDown 的距离
stop: 40, // pullingDown 正在刷新 hold 时的距离
txt: '刷新成功',
}
pullUp启用上拉加载Booleantrue
pullUpConfig上拉加载配置Object{
threshold: 100, // 提前触发 pullingUp 的距离
txt: { more: '上拉加载', noMore: '— 我是有底线的 —'
}
startY纵轴方向初始化位置Number0
bounce回弹效果Booleantrue
bounceTime回弹时间Number600
preventDefaultException不阻止默认行为Object{
tagName: /^(INPUT|TEXTAREA|BUTTON|SELECT)$/
}
mouseWheelv1.6.2+,启用 PC 鼠标滚轮Booleanfalse
betterScrollOptionsv1.7.0+,任何的 better-scroll 配置项,将合并在初始化 better-scroll 的配置中。注意:与 props 冲突的配置项将被 props 覆盖Objectnull
autoUpdate自动更新高度。深监视 this.$parent.$data 自动调用 update(),适用于简单场景。复杂场景请使用updateData/refreshData 或手动调用 update()/refresh()Booleanfalse
updateData引起更新上拉/下拉加载状态的数据(下拉刷新/上拉加载相关的数据)。设置此项时,autoUpdate 应设置为 false。当观测到该数据变化时,将自动调用 update()Arraynull
refreshData引起刷新高度的数据(不包含 updateData 内的数据)。当观测到该数据变化时,将自动调用 refresh() 刷新滚动高度Arraynull

Methods

方法名说明参数
initScroll初始化scroll组件
disable禁用 better-scroll,DOM 事件(如 touchstart、touchmove、touchend)的回调函数不再响应
enable启用 better-scroll, 默认 开启
scrollTo滚动到指定的位置(x:Number, y:Number, time:Number)
1.x横轴坐标(px),默认值0
2.y 纵轴坐标(px),默认值0
3.滚动动画执行的时长(ms),默认值=$props.bounceTime=600
scrollToElement滚动到指定的目标元素(el, time, offsetX , offsetY )接收4个参数 详情请查看: scrollToElement
scrollToTopv1.4.0+,滚动到顶部
scrollToBottomv1.4.0+,滚动到底部
autoPullDownRefreshv1.5.0+,手动触发下拉刷新
destroy销毁 better-scroll,解绑事件
refresh刷新滚动高度(当页面无法滚动时,可尝试调用此方法)
update更新加载状态,下拉/上拉成功后使用。当上拉加载到最后一页/需要触发停止上拉加载时,需要手动调用它(pullUpFinally:Boolean) 声明 pullUp 上拉加载是否到了最底部。下拉刷新成功后该值会自动 false。也可传入 false 手动声明不是最后一页

Events

事件名说明回调参数
scroll触发时机:滚动过程中,具体时机取决于选项中的 probeType (触发事件在参数中需要开启 listenScroll,该参数默认为 false )(pos:Object) 滚动的实时坐标
beforeScrollStart触发时机:滚动开始之前 (触发事件在参数中需要开启 listenBeforeScrollStart,该参数默认为 false )
pullingDown触发时机:在一次下拉刷新的动作后,这个时机一般用来去后端刷新数据。(触发事件在参数中需要开启 pullDown,该参数默认为 true )
pullingUp触发时机:在一次上拉加载的动作后,这个时机一般用来去后端请求数据。(触发事件在参数中需要开启 pullUp,该参数默认为 true )

Slots

名称说明
default滚动的主体内容区域
pulldown下拉刷新的内容
pullup上拉加载的内容

⚠️ 常见问题

为什么无法滚动?

父容器需要指定一个高度。

如果想要高度自适应,父容器的高度可采用 100%vhcalc()flex(1) 等多种自适应方案。

原因可参考 better-scroll 滚动原理


😉😘 如果它对你有所帮助,可以点一下 ⭐️Star ~

🌟 Star me !