scrollbar

Introduciton

The scrollbar plugin provides a nice scrollbar for BetterScroll.

TIP

For v2.2.0, users can provide custom scroll bars.

Install

npm install @better-scroll/scroll-bar --save

// or

yarn add @better-scroll/scroll-bar

Usage

First, install the plugin via the static method BScroll.use()

import BScroll from '@better-scroll/core'
import ScrollBar from '@better-scroll/scroll-bar'

BScroll.use(ScrollBar)

pass correct scrollbar options

new BScroll('.bs-wrapper', {
  scrollY: true,
  scrollbar: true
})

Demo

• Vertical Scrollbar

  <template>
    <div class="scrollbar">
      <div ref="wrapper" class="scrollbar-wrapper">
        <ul class="scrollbar-content">
          <li v-for="i of 40" :key="i" class="scrollbar-content-item">
            {{ `I am item ${i} `}}
          </li>
        </ul>
      </div>
    </div>
  </template>

  <script>
    import BScroll from '@better-scroll/core'
    import ScrollBar from '@better-scroll/scroll-bar'
  
    BScroll.use(ScrollBar)
  
    export default {
      mounted() {
        this.initBscroll()
      },
      methods: {
        initBscroll() {
          this.scroll = new BScroll(this.$refs.wrapper, {
            scrollY: true,
            scrollbar: true
          })
        }
      }
    }
  </script>

  <style lang="stylus">
  .scrollbar
    height: 100%
  .scrollbar-wrapper
    position: relative
    height: 100%
    padding: 0 10px
    border: 1px solid #ccc
    overflow: hidden
  .scrollbar-content-item
    padding: 10px 0
    list-style: none
    border-bottom: 1px solid #ccc
    text-align: left
  </style>

• Horizontal Scrollbar

  <template>
    <div class="horizontal-scrollbar-container">
      <div class="scroll-wrapper" ref="scroll">
        <div class="scroll-content">
          <div class="scroll-item" v-for="index in num" :key="index">{{index}}</div>
        </div>
      </div>
    </div>
  </template>

  <script type="text/ecmascript-6">
    import BScroll from '@better-scroll/core'
    import Scrollbar from '@better-scroll/scroll-bar'
  
    BScroll.use(Scrollbar)
  
    export default {
      data () {
        return {
          num: 12
        }
      },
      mounted() {
        this.init()
      },
      beforeDestroy() {
        this.scroll.destroy()
      },
      methods: {
        init() {
          this.scroll = new BScroll(this.$refs.scroll, {
            scrollX: true,
            scrollY: false,
            click: true,
            probeType: 1,
            scrollbar: {
              fade: false,
              interactive: true,
              scrollbarTrackClickable: true,
              scrollbarTrackOffsetType: 'clickedPoint' // can use 'step'
            }
          })
          this.scroll.on('scrollEnd', () => {
            console.log('scrollEnd')
          })
          this.scroll.on('scrollStart', () => {
            console.log('scrollStart')
          })
          this.scroll.on('scroll', () => {
            console.log('scroll')
          })
        }
      }
    }
  </script>

  <style lang="stylus" rel="stylesheet/stylus" scoped>
  
  .horizontal-scrollbar-container
    .scroll-wrapper
      position relative
      display flex
      align-content center
      width 90%
      height 100px
      margin 80px auto
      white-space nowrap
      border 3px solid rgba(30, 80, 255, 0.3)
      border-radius 5px
      overflow hidden
      .scroll-content
        display inline-block
        align-self center
      .scroll-item
        opacity  0.6
        color white
        box-sizing border-box
        height 50px
        width 50px
        line-height 50px
        border-radius 50%
        font-size 18px
        display inline-block
        text-align center
        padding 0 10px
        margin 0 10px
        &:nth-child(4n)
          background-color #06F
        &:nth-child(4n+1)
          background-color #0f9d00
        &:nth-child(4n+2)
          background-color #F00
        &:nth-child(4n+3)
          background-color #ffea00
  </style>

• Custom Scrollbar

  <template>
    <div class="custom-scrollbar-container">
      <div ref="wrapper" class="custom-scrollbar-wrapper">
        <img @load="onload" class="custom-scrollbar-content" :src="girlImageLink" alt="">
        <!-- custom-vertical-scrollbar-->
        <div class="custom-vertical-scrollbar" ref="vertical">
          <div class="custom-vertical-indicator"></div>
        </div>
        <!-- custom-horizontal-scrollbar-->
        <div class="custom-horizontal-scrollbar" ref="horizontal">
          <div class="custom-horizontal-indicator"></div>
        </div>
      </div>
    </div>
  </template>

  <script>
    import BScroll from '@better-scroll/core'
    import ScrollBar from '@better-scroll/scroll-bar'
    import girlImage from './girl.jpg'
  
    BScroll.use(ScrollBar)
  
    export default {
      data () {
        return {
          girlImageLink : girlImage
        }
      },
      methods: {
        initBscroll() {
          this.scroll = new BScroll(this.$refs.wrapper, {
            freeScroll: true,
            click: true,
            scrollbar: {
              customElements: [this.$refs.horizontal, this.$refs.vertical],
              fade: false,
              interactive: true,
              scrollbarTrackClickable: true
            }
          })
        },
        onload () {
          this.initBscroll()
        }
      }
    }
  </script>

  <style lang="stylus" scoped>
  .custom-scrollbar-container
    .custom-scrollbar-wrapper
      position relative
      width 280px
      height 280px
      overflow hidden
    .custom-scrollbar-content
      max-width none
    .custom-vertical-scrollbar
      position absolute
      top 50%
      right 10px
      height 100px
      width 7px
      border-radius 6px
      transform translateY(-50%) translateZ(0)
      background-color rgb(200, 200, 200, 0.3)
    .custom-vertical-indicator
      width 100%
      height 20px
      border-radius 6px
      background-color #db8090
    .custom-horizontal-scrollbar
      position absolute
      left 50%
      bottom 10px
      width 100px
      height 7px
      border-radius 6px
      transform translateX(-50%) translateZ(0)
      background-color rgb(200, 200, 200, 0.3)
    .custom-horizontal-indicator
      height 100%
      width 20px
      border-radius 6px
      background-color #db8090
  </style>

• With Mousewheel

  <template>
    <div class="mousewheel-scrollbar-container">
      <div ref="wrapper" class="custom-scrollbar-wrapper">
        <div class="custom-scrollbar-content">
          <img @load="onload" :src="girlImageLink" alt="">
        </div>
        <!-- custom-horizontal-scrollbar-->
        <div class="custom-horizontal-scrollbar" ref="horizontal">
          <div class="custom-horizontal-indicator"></div>
        </div>
      </div>
      <div class="tip">please use your mouse-wheel</div>
    </div>
  </template>

  <script>
    import BScroll from '@better-scroll/core'
    import ScrollBar from '@better-scroll/scroll-bar'
    import MouseWheel from '@better-scroll/mouse-wheel'
    import girlImage from './sad-girl.jpg'
  
    BScroll.use(ScrollBar)
    BScroll.use(MouseWheel)
  
    export default {
      data () {
        return {
          girlImageLink : girlImage
        }
      },
      methods: {
        initBscroll() {
          this.scroll = new BScroll(this.$refs.wrapper, {
            scrollX: true,
            scrollY: false,
            click: true,
            mouseWheel: true,
            scrollbar: {
              customElements: [this.$refs.horizontal],
              fade: true,
              interactive: true,
              scrollbarTrackClickable: true
            }
          })
        },
        onload () {
          this.initBscroll()
        }
      }
    }
  </script>

  <style lang="stylus" scoped>
  .mousewheel-scrollbar-container
    .custom-scrollbar-wrapper
      position relative
      width 280px
      height 280px
      overflow hidden
    .custom-scrollbar-content
      display inline-block
      height 280px
      > img
        max-width none
    .custom-horizontal-scrollbar
      position absolute
      left 50%
      bottom 10px
      width 100px
      height 7px
      border-radius 6px
      transform translateX(-50%) translateZ(0)
      background-color rgb(200, 200, 200, 0.3)
    .custom-horizontal-indicator
      height 100%
      width 20px
      border-radius 6px
      background-color #db8090
    .tip
      text-align center
      margin-top 10px
  </style>

scrollbar options

fade

• Type: boolean
• Default: true

When the scroll stops, the scrollbar fades out.

interactive

• Type: boolean
• Default: false

Whether scrollbar can interacted with.

customElements 2.2.0

• Type: HTMLElement[]
• Default: []

The user provides a custom scroll bar.

// horizontal
const horizontalEl = document.getElementById('User-defined scrollbar')
new BScroll('.bs-wrapper', {
  scrollY: true,
  scrollbar: {
    customElements: [horizontalEl]
  }
})
// vertical
const verticalEl = document.getElementById('User-defined scrollbar')
new BScroll('.bs-wrapper', {
  scrollY: false,
  scrollX: true,
  scrollbar: {
    customElements: [verticalEl]
  }
})
// freeScroll
const horizontalEl = document.getElementById('User-defined scrollbar')
const verticalEl = document.getElementById('User-defined scrollbar')
new BScroll('.bs-wrapper', {
  freeScroll: true,
  scrollbar: {
    // When there are two scrollbars
    // the first element of the array is the horizontal
    customElements: [horizontalEl, verticalEl]
  }
})

minSize 2.2.0

• Type: number
• Default: 8

The minimum size of the scrollbar. When the user provides a custom scrollbar, this configuration is invalid.

scrollbarTrackClickable 2.2.0

• Type: boolean
• Default: false

Whether the scrollbar track allows clicking.

Note：When enabling this configuration, please ensure that the click of BetterScroll Options is true, otherwise the click event cannot be triggered. The reason is here.

new BScroll('.bs-wrapper', {
  scrollY: true,
  click: true // essential
  scrollbar: {
    scrollbarTrackClickable: true
  }
})

scrollbarTrackOffsetType 2.2.0

• Type: string
• Default: 'step'

After the scroll bar track is clicked, the calculation method of the scroll distance is the same as the browser's performance by default. It can be configured as 'clickedPoint', which means the scroll bar is scrolled to the clicked position.

scrollbarTrackOffsetTime 2.2.0

• Type: number
• Default: 300

the scroll time after the scrollbar track is clicked.

fadeInTime 2.4.0

• Type: number
• Default: 250

The duration of the animation when the scrollbar fades in.

fadeOutTime 2.4.0

• Type: number
• Default: 500

The duration of the animation when the scrollbar fades out.

TIP

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

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

// equals

const bs = new BScroll('.wrapper', {
  scrollbar: {
    fade: true,
    interactive: false,
    // supported in v2.2.0
    customElements: [],
    minSize: 8,
    scrollbarTrackClickable: false,
    scrollbarTrackOffsetType: 'step',
    scrollbarTrackOffsetTime: 300,
    // supported in v2.4.0
    fadeInTime: 250,
    fadeOutTime: 500
  }
})