Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

huangjincq/vue-better-scroll

Open more actions menu

Repository files navigation

A vue plugins based on better-scroll

最近写移动端项目,下拉刷新、上拉加载的场景很常见,发现 mint-ui 的 Loadmore 组件效果体验不尽如人意, Vux 的 Scroller 组件作者不推荐使用也停止维护了,最后决定根据 better-scroll 封装成自己的 vue 组件,作者也提供了详细的教程。

Example

Demo Page

滚动原理

由于 better-scroll 的滚动原理为:在滚动方向上,第一个子元素的长度超过了容器的长度。

那么对于 Scroll 组件,其实就是内容元素 .list-content 在滚动方向上的长度必须大于容器元素 .wrapper。

任何时候如果出现无法滚动的情况,都应该首先查看内容元素 .list-content 的元素高度/宽度是否大于容器元素 .wrapper 的高度/宽度。这是内容能够滚动的前提条件。如果内容存在图片的情况,可能会出现 DOM 元素渲染时图片还未下载,因此内容元素的高度小于预期,出现滚动不正常的情况。此时你应该在图片加载完成后,比如 onload 事件回调中,手动调用 vue-better-scroll 组件的 refresh() 方法,它会重新计算滚动距离。

Use Setup

Install vue2-better-scroll

yarn add vue2-better-scroll
// or
npm install vue2-better-scroll -s

Vue mount

// import
import Vue from 'vue'
import VueBetterScroll from 'vue2-better-scroll'

// or require
var Vue = require('vue')
var VueBetterScroll = require('vue2-better-scroll')

// mount with global
Vue.use(VueBetterScroll)

// mount with component(can't work in Nuxt.js/SSR)
import { VueBetterScroll } from 'vue2-better-scroll'

export default {
  components: {
    VueBetterScroll,
  },
}

// 或者直接导入js文件
;<script src="./dist/vue-better-scroll.js"></script>

Use in SPA

<template>
  <div id="app">
    <header>vue-better-scroll demo</header>
    <main class="position-box">
      <!-- 需要一个创建一个父容器 组件高度默认等于父容器的高度 -->
      <vue-better-scroll
        class="wrapper"
        ref="scroll"
        :scrollbar="scrollbarObj"
        :pullDownRefresh="pullDownRefreshObj"
        :pullUpLoad="pullUpLoadObj"
        :startY="parseInt(startY)"
        @pulling-down="onPullingDown"
        @pulling-up="onPullingUp"
      >
        <ul class="list-content">
          <li class="list-item" v-for="item in items">{{item}}</li>
        </ul>
      </vue-better-scroll>
    </main>
    <button class="go-top" @click="scrollTo">返回顶部</button>
  </div>
</template>

<script>
  import VueBetterScroll from '../dist/vue-better-scroll'
  // import VueBetterScroll from './lib'

  let count = 1
  export default {
    name: 'app',
    components: { VueBetterScroll },
    data() {
      return {
        // 这个配置可以开启滚动条,默认为 false。当设置为 true 或者是一个 Object 的时候,都会开启滚动条,默认是会 fade 的
        scrollbarObj: {
          fade: true,
        },
        // 这个配置用于做下拉刷新功能,默认为 false。当设置为 true 或者是一个 Object 的时候,可以开启下拉刷新,可以配置顶部下拉的距离(threshold) 来决定刷新时机以及回弹停留的距离(stop)
        pullDownRefreshObj: {
          threshold: 90,
          stop: 40,
        },
        // 这个配置用于做上拉加载功能,默认为 false。当设置为 true 或者是一个 Object 的时候,可以开启上拉加载,可以配置离底部距离阈值(threshold)来决定开始加载的时机
        pullUpLoadObj: {
          threshold: 0,
          txt: {
            more: '加载更多',
            noMore: '没有更多数据了',
          },
        },
        startY: 0, // 纵轴方向初始化位置
        scrollToX: 0,
        scrollToY: 0,
        scrollToTime: 700,
        items: [],
      }
    },
    mounted() {
      this.onPullingDown()
    },
    methods: {
      // 滚动到页面顶部
      scrollTo() {
        this.$refs.scroll.scrollTo(this.scrollToX, this.scrollToY, this.scrollToTime)
      },
      // 模拟数据请求
      getData() {
        return new Promise((resolve) => {
          setTimeout(() => {
            const arr = []
            for (let i = 0; i < 10; i++) {
              arr.push(count++)
            }
            resolve(arr)
          }, 1000)
        })
      },
      onPullingDown() {
        // 模拟下拉刷新
        console.log('下拉刷新')
        count = 0
        this.getData().then((res) => {
          this.items = res
          this.$refs.scroll.forceUpdate(true)
        })
      },
      onPullingUp() {
        // 模拟上拉 加载更多数据
        console.log('上拉加载')
        this.getData().then((res) => {
          this.items = this.items.concat(res)
          if (count < 30) {
            this.$refs.scroll.forceUpdate(true)
          } else {
            this.$refs.scroll.forceUpdate(false)
          }
        })
      },
    },
  }
</script>

<style>
  .position-box {
    position: fixed;
    top: 40px;
    left: 0;
    right: 0;
    bottom: 0;
  }
</style>

Attributes:

参数 说明 类型 可选值 默认值
probeType 派发 scroll 事件的条件 Number 1、2、3 1
click better-scroll 会派发一个 click 事件 Boolean true
listenScroll 是否监听滚动,开启后才能派发 scroll 事件 Boolean false
listenBeforeScroll 是否监听滚动之前,开启后才能派发 before-scroll-start 事件 Boolean false
scrollbar 这个配置可以开启滚动条。当设置为 true 或者是一个 Object 的时候,都会开启滚动条,默认是会 fade 的 Boolean or Object {fade: true}, false
pullDownRefresh 这个配置用于做下拉刷新功能。当设置为 true 或者是一个 Object 的时候,可以开启下拉刷新,可以配置顶部下拉的距离(threshold) 来决定刷新时机以及回弹停留的距离(stop) Boolean or Object {threshold: 90,stop: 40}, false
pullUpLoad 这个配置用于做上拉加载功能。当设置为 true 或者是一个 Object 的时候,可以开启上拉加载,可以配置离底部距离阈值(threshold)来决定开始加载的时机 Boolean or Object { threshold: 0, txt: { more: '加载更多',noMore:'没有更多数据了'} } false
startY 纵轴方向初始化位置 Number 0
freeScroll 有些场景我们需要支持横向和纵向同时滚动,而不仅限制在某个方向,这个时候我们只要设置 freeScroll 为 true 即可 Boolean false
options 可自行根据 better-scroll 官方文档 扩展参数 例::options="{stopPropagation:true}" Object 官方文档的所有参数(注:props 传入的相同的属性会覆盖 options 传入的) {}

Slots:

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

Methods:

方法名 说明 参数
initScroll 初始化 scroll 组件
disable 禁用 better-scroll,DOM 事件(如 touchstart、touchmove、touchend)的回调函数不再响应
enable 启用 better-scroll, 默认 开启
refresh 重新计算 better-scroll,当 DOM 结构发生变化的时候务必要调用确保滚动的效果正常(当页面无法滚动时,可尝试调用此方法)
scrollTo 滚动到指定的位置 (scrollToX, scrollToY, scrollToTime, easing)接收 4 个参数,1.x 横轴坐标(px) 2.y 纵轴坐标(px) 3.滚动动画执行的时长(ms) 4.easing 缓动函数,一般不建议修改
scrollToElement 滚动到指定的目标元素 (el, time, offsetX , offsetY )接收 4 个参数 详情请查看: scrollToElement
destroy 销毁 better-scroll,解绑事件
forceUpdate 数据跟新后强制更新页面 (dirty)接收 1 个 boolean 类型的参数,如果参数为 true,说明还可以触发下拉或者上拉事件,若参数为 false 表示之后不可拉动,一般用于数据加载全部了

Events:

事件名称 说明 回调参数
scroll 触发时机:滚动过程中,具体时机取决于选项中的 probeType (触发事件在参数中需要开启 listenScroll ) 共 1 个参数,类型 Object, {x, y} 滚动的实时坐标
before-scroll-start 触发时机:滚动开始之前 (触发事件在参数中需要开启 listenBeforeScroll )
pulling-down 触发时机:在一次下拉刷新的动作后,这个时机一般用来去后端请求数据。(触发事件在参数中需要开启 pullDownRefresh 相关配置 )
pulling-up 触发时机:在一次上拉加载的动作后,这个时机一般用来去后端请求数据。(触发事件在参数中需要开启 pullingUp 相关配置 )

目前只提供了以上常用方法、Api,如有额外需要请 issue

More detailed settings, please visit

better-scroll document

Author Blog

Gold_Gold

About

A vue plugins based on better-scroll

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Morty Proxy This is a proxified and sanitized view of the page, visit original site.