BetterScroll 2.0

# mouse-wheel

mouseWheel extends the capabilities of the BetterScroll mouse wheel.

# Install

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

// or

yarn add @better-scroll/mouse-wheel

TIP

Currently supports mouse wheel: core, slide, wheel, pullup, pulldown plugins.

# Basic Usage

In order to enable the mouseWheel plugin, you need to first import it, register the plugin through the static method BScroll.use(), and finally pass in the correct mouseWheel option

  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
    }
  })
  • VerticalScroll Demo
<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>

  • HorizontalScroll Demo

# Advanced Usage

The mouseWheel plugin can also be used with other plugins to increase the operation of the mouse wheel.

  • mouseWheel & slide

    Operate slide with the mouse wheel.

    • HorizontalSlide Demo

    • VerticalSlide Demo

  • mouseWheel & pullup

    use mousewheel do pullup operation.

  • mouseWheel & pulldown

    use mousewheel do pulldown operation.

  • mouseWheel & wheel

    use mousewheel do wheel operation.

# mouseWheel options

# speed

  • Type: number
  • Default: 20

The speed at which the mouse wheel scrolls.

# invert

  • Type: boolean
  • Default: false

When the value is true, it means that the scrolling direction of the wheel is opposite to that of BetterScroll.

# easeTime

  • Type: number
  • Default: 300(ms)

The duration of the scroll animation.

# discreteTime

  • Type: number
  • Default: 400(ms)

Because the mouse wheel is a discrete movement, there is no event type of start, move, end, so as long as no scroll is detected within discreteTime, then one scroll wheel action ends.

WARNING

When integrated with pulldown plugin, easeTime and discreteTime will be internally modified to reasonable fixed value to trigger the pullingDown hook

# throttleTime

  • Type: number
  • Default: 0(ms)

Since the scroll wheel is a high-frequency action, the trigger frequency can be limited by throttleTime. MouseWheel will cache the scrolling distance, and calculate the cached distance and scroll every throttleTime.

Modifying throttleTime may cause discontinuous scrolling animation, please adjust it according to the actual scene.

# dampingFactor

  • Type: number
  • Default: 0.1

Damping factor, the value range is [0, 1]. When BetterScroll rolls out of the boundary, resistance needs to be applied to prevent the rolling range from being too large. The smaller the value, the greater the resistance.

TIP

When mouseWheel is configured as true, the plugin uses the default plugin option.

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

// equals

const bs = new BScroll('.wrapper', {
  mouseWheel: {
    speed: 20,
    invert: false,
    easeTime: 300,
    discreteTime: 400,
    throttleTime: 0,
    dampingFactor: 0.1
  }
})

# Events

# alterOptions

  • Arguments: MouseWheelConfig
      export interface MouseWheelConfig {
    speed: number
    invert: boolean
    easeTime: number
    discreteTime: number
    throttleTime: number,
    dampingFactor: number
  }
  • Triggered Timing: The mousewheel begins to scroll, allowing to modify options to control certain behaviors during scrolling.

# mousewheelStart

  • Arguments: none
  • Triggered Timing: The mousewheel starts.

# mousewheelMove

  • Arguments: { x, y }
  • { number } x: The current x of BetterScroll
  • { number } y: The current y of BetterScroll
  • Type: { x: number, y: number }
  • Triggered Timing: Mousewheel is scrolling

# mousewheelEnd

  • Arguments:delta
  • Type: WheelDelta
  interface WheelDelta {
    x: number
    y: number
    directionX: Direction
    directionY: Direction
  }
  • Triggered Timing: If the mousewheel hook has not been triggered after discreteTime, a mousewheel action will be settled.

Note

Due to the particularity of the mousewheel hook, the dispatch of mousewheelEnd does not mean the end of the scroll animation.

TIP

In most scenarios, if you want to know the current scroll position of BetterScroll accurately, please listen to the scroll and scrollEnd hooks instead of the mouseXXX hooks.

← observe-dom →