# mouse-wheel

mouseWheel 扩展 BetterScroll 鼠标滚轮的能力。

# 安装

npm install @better-scroll/mouse-wheel --save

// or

yarn add @better-scroll/mouse-wheel

TIP

目前支持鼠标滚轮有:core、slide、wheel、pullup、pulldown

# 基础使用

为了开启鼠标滚动功能,你需要首先引入 mouseWheel 插件,通过静态方法 BScroll.use() 注册插件,最后传入正确的 mouseWheel 选项对象

  import BScroll from '@better-scroll/core'
  import MouseWheel from '@better-scroll/mouse-wheel'
  BScroll.use(MouseWheel)

  new BScroll('.bs-wrapper', {
    //...
    mouseWheel: {
      speed: 20,
      invert: false,
      easeTime: 300
    }
  })
  • 纵向普通滚动示例

    <template>
      <div class="mouse-wheel-vertical-scroll">
        <div class="mouse-wheel-wrapper" ref="scroll">
          <div class="mouse-wheel-content">
            <div class="mouse-wheel-item" v-for="n in 100" :key="n">{{n}}</div>
          </div>
        </div>
      </div>
    </template>
  • 横向普通滚动示例

# 进阶使用

mouseWheel 插件还可以搭配其他的插件,为其增加鼠标滚轮的操作。

  • mouseWheel & slide

    通过鼠标滚轮操作 slide

    • 横向 slide 示例

    • 纵向 slide 示例

  • mouseWheel & pullup

    通过鼠标触发上拉加载 pullup

  • mouseWheel & pulldown

    通过鼠标触发下拉加载 pulldown

  • mouseWheel & wheel

    通过鼠标触发 wheel

# mouseWheel 选项对象

# speed

  • 类型number
  • 默认值20

鼠标滚轮滚动的速度。

# invert

  • 类型boolean
  • 默认值false

当该值为 true 时,表示滚轮滚动和 BetterScroll 滚动的方向相反。

# easeTime

  • 类型number
  • 默认值300(ms)

滚动动画的缓动时长。

# discreteTime

  • 类型number
  • 默认值400(ms)

由于滚轮滚动是一种离散的运动,并没有 start、move、end 的事件类型,因此只要在 discreteTime 时间内没有探测到滚动,那么一次的滚轮动作就结束了。

注意

当搭配 pulldown 插件的时候,easeTimediscreteTime 会被内部修改成合理的固定值,以便触发 pullingDown 钩子

# throttleTime

  • 类型number
  • 默认值0(ms)

由于滚轮滚动是高频率的动作,因此可以通过 throttleTime 来限制触发频率,mouseWheel 内部会缓存滚动的距离,并且每隔 throttleTime 会计算缓存的距离并且滚动。

修改 throttleTime 可能会造成滚动动画不连贯,请根据实际场景进行调整。

# dampingFactor

  • 类型number
  • 默认值0.1

阻尼因子,值的范围是[0, 1],当 BetterScroll 滚出边界的时候,需要施加阻力,防止滚动幅度过大,值越小,阻力越大。

# 事件

# alterOptions

  • 参数MouseWheelConfig
    export interface MouseWheelConfig {
      speed: number
      invert: boolean
      easeTime: number
      discreteTime: number
      throttleTime: number,
      dampingFactor: number
    }
    
  • 触发时机:滚轮滚动开始

允许修改 options 来控制滚动中的某些行为。

# mousewheelStart

  • 参数:无
  • 触发时机:滚轮滚动开始。

# mousewheelMove

  • 参数{ x, y }
  • { number } x:当前 BetterScroll 的横向滚动位置
  • { number } y:当前 BetterScroll 的纵向滚动位置
  • 类型{ x: number, y: number }
  • 触发时机:滚轮滚动中

# mousewheelEnd

  • 参数delta
  • 类型WheelDelta
  interface WheelDelta {
    x: number
    y: number
    directionX: Direction
    directionY: Direction
  }
  • 触发时机:discreteTime 之后如果还没有触发 mousewheel 事件,那么便结算一次滚轮滚动行为。

警告

由于 mousewheel 事件的特殊性,mousewheelEnd 派发并不代表滚动动画结束。

提示

在绝大多数的场景下,如果你想要精确的知道当前 BetterScroll 的滚动位置,请监听 scroll、scrollEnd 钩子,而不是 mouseXXX 钩子。