项目中better-scroll的常用配置、插件介绍

介绍

• BetterScroll 是一款重点解决移动端（已支持 PC）各种滚动场景需求的插件。

• 它的核心是借鉴的 iscroll (opens new window)的实现，它的 API 设计基本兼容 iscroll，在 iscroll 的基础上又扩展了一些 feature 以及做了一些性能优化。

• BetterScroll 是使用纯 JavaScript 实现的，这意味着它是无依赖的。

最常见的应用场景是列表滚动

<div class="wrapper">
  <ul class="content">
    <li>...</li>
    <li>...</li>
    ...
  </ul>
  <!-- 这里可以放一些其它的 DOM，但不会影响滚动 -->
</div>

• 上面的代码中 BetterScroll 是作用在外层 wrapper 容器上的，滚动的部分是 content 元素。

• 注意：BetterScroll 默认处理容器（wrapper）的第一个子元素（content）的滚动，其它的元素都会被忽略。

滚动原理

• 浏览器的滚动条大家都会遇到，当页面内容的高度超过视口高度的时候，会出现纵向滚动条；

• 当页面内容的宽度超过视口宽度的时候，会出现横向滚动条。

• 也就是当我们的视口展示不下内容的时候，会通过滚动条的方式让用户滚动屏幕看到剩余的内容。

• BetterScroll 也是一样的原理，我们可以用一张图更直观的感受一下：

• 绿色部分为 wrapper，也就是父容器，它会有固定的高度。

• 黄色部分为 content，它是父容器的第一个子元素，它的高度会随着内容的大小而撑高。

• 那么，当 content 的高度不超过父容器的高度，是不能滚动的，而它一旦超过了父容器的高度，我们就可以滚动内容区了，这就是 BetterScroll 的滚动原理。

安装

全部安装

我们可以通过以下方式安装具备所有插件能力的 BetterScroll：

npm install better-scroll --save

如果你觉得一个个引入插件很费事，我们提供了一个拥有全部插件能力的 BetterScroll 包。

它的使用方式与 1.0 版本一模一样，但是体积会相对大很多，推荐按需引入。

按需安装（推荐）

• 如果你只需要一个拥有基础滚动能力的列表，只需要引入 core。
• 在 BetterScroll 2.0 的设计当中，我们抽象了核心滚动部分，它作为 BetterScroll 的最小使用单元，压缩体积比 1.0 小了将近三分之一，往往你可能只需要完成一个纯粹的滚动需求，那么你只需要引入这一个库，方式如下：

import BScroll from '@better-scroll/core'
let bs = new BScroll('.wrapper', {
    
    
  // ...... 详见配置项
})

• 如果你需要一些额外的 feature。比如 pull-up，你需要引入额外的插件，详情查看插件。

import BScroll from '@better-scroll/core'
import Pullup from '@better-scroll/pull-up'

// 注册插件
BScroll.use(Pullup)

let bs = new BScroll('.wrapper', {
    
    
  probeType: 3,
  pullUpLoad: true
})

插件

使用插件

通过全局方法 BScroll.use() 使用插件。它需要在你调用 new BScroll() 之前完成：

  import BScroll from '@better-scroll/core'
  import Plugin from 'somewhere'

  BScroll.use(Plugin)
  new BScroll('.wrapper', {
    
    
    pluginKey: {
    
    } // pluginKey 对应 Plugin 类上静态属性 pluginName 的值，否则插件无法实例化
  })

常用插件

pullUp

pullup 插件为 BetterScroll 扩展上拉加载的能力。

• 安装：

npm install @better-scroll/pull-up --save

• 使用：

  import BScroll from '@better-scroll/core'
  import Pullup from '@better-scroll/pull-up'

  BScroll.use(Pullup)

• 配置：

this.scroll = new BScroll('.bs-wrapper', {
    
    
    pullUpLoad: true
  })

• 事件：

• pullingUp

• 参数：无

• 触发时机：当距离滚动到底部小于 threshold 值时，触发一次 pullingUp 事件。

当 threshold 为正数，代表距离滚动边界 threshold 像素的时候触发 pullingUp，反之，代表越过滚动边界才会触发事件

警告：

监测到上拉刷新的动作之后，pullingUp 事件的消费机会只有一次，因此你需要调用 finishPullUp() 来告诉 BetterScroll 来提供下一次 pullingUp 事件的消费机会。

• 一般用来完成上拉加载功能。

this.scroll.on('pullingUp', () => {
    
    
      ...
})

observe-dom

开启对 content 以及 content 子元素 DOM 改变的探测。当插件被使用后，当这些 DOM 元素发生变化时，将会触发 scroll 的 refresh 方法。 observe-dom 插件具有以下几个特性：

• 针对改变频繁的 CSS 属性，增加 debounce

• 如果改变发生在 scroll 动画过程中，则不会触发 refresh

• 安装：

npm install @better-scroll/observe-dom --save

• 使用：

import BScroll from '@better-scroll/core'
import ObserveDOM from '@better-scroll/observe-dom'
BScroll.use(ObserveDOM)

new BScroll('.bs-wrapper', {
    
    
  //...
  observeDOM: true // 开启 observe-dom 插件
})

• 注意：无法探测到 img 标签的是否加载完成，需要observe-image插件

observe-image

一般情况下，我们请求图片数据还没有到达，可滚动尺寸却被确定了，此时可滚动尺寸小于实际的高度，需要刷新可滚动尺寸，就需要用到该插件。（有防抖功能）

• 开启对 wrapper 子元素中图片元素的加载的探测。无论图片的加载成功与否，都会自动调用 BetterScroll 的 refresh 方法来重新计算可滚动的宽度或者高度，新增于 v2.1.0 版本。

• 提示：对于已经用 CSS 确定图片宽高的场景，不应该使用该插件，因为每次调用 refresh 对性能会有影响。只有在图片的宽度或者高度不确定的情况下，你才需要它。

• 安装：

npm install @better-scroll/observe-dom --save

• 使用：

import BScroll from '@better-scroll/core'
import ObserveDOM from '@better-scroll/observe-dom'
BScroll.use(ObserveDOM)

new BScroll('.bs-wrapper', {
    
    
  //...
  observeDOM: true // 开启 observe-dom 插件
})

• observeImage 选项对象：

• 提示：当 observeImage 配置为 true 的时候，插件内部使用的是默认的插件选项对象。

const bs = new BScroll('.wrapper', {
    
    
  observeImage: true
})

// 相当于

const bs = new BScroll('.wrapper', {
    
    
  observeImage: {
    
    
    debounceTime: 100 // ms
  }
})

• debounceTime

• 类型： number

• 默认值： 100

  探测到图片加载成功或者失败后，过 debounceTime 毫秒后才会调用 refresh 方法，重新计算可滚动的高度或者宽度，如果在 debounceTime 毫秒内有多张图片加载成功或者失败，只会调用一次 refresh。

  提示：当 debounceTime 为 0 的时候，会立马调用 refresh 方法，而不是使用 setTimeout。

常用配置项

click

• 类型：boolean

• 默认值：false

• 作用：BetterScroll 默认会阻止浏览器的原生 click 事件。当设置为 true，BetterScroll 会派发一个 click 事件，我们会给派发的 event 参数加一个私有属性 _constructed，值为 true。

• 一般我们需要将click设置为true。

probeType

• 类型：number
• 默认值：0
• 可选值：1|2|3
• 作用：决定是否派发 scroll 事件，对页面的性能有影响，尤其是在 useTransition 为 true 的模式下。

// 派发 scroll 的场景分为两种：
// 1. 手指作用在滚动区域（content DOM）上;
// 2. 调用 scrollTo 方法或者触发 momentum 滚动动画（其实底层还是调用 scrollTo 方法）

// 对于 v2.1.0 版本，对 probeType 做了一次统一

// 1. probeType 为 0，在任何时候都不派发 scroll 事件，
// 2. probeType 为 1，仅仅当手指按在滚动区域上，每隔 momentumLimitTime 毫秒派发一次 scroll 事件，
// 3. probeType 为 2，仅仅当手指按在滚动区域上，一直派发 scroll 事件，
// 4. probeType 为 3，任何时候都派发 scroll 事件，包括调用 scrollTo 或者触发 momentum 滚动动画

常用注意事项

在vue中使用建议用ref属性绑定scroll对象

• 如果在大型项目中有多处使用wrapper作为类名称，那么querySelecter会选择第一个。
• 但是使用ref属性可以精确定位到我们选择的element元素。