scrollbar

介绍

scrollbar 插件为 BetterScroll 提供了样式美观的滚动条。

提示

从 v2.2.0 开始，用户可以提供自定义的滚动条。

安装

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

// or

yarn add @better-scroll/scroll-bar

使用

首先引入 scrollbar 插件，并通过静态方法 BScroll.use() 注册插件

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

  BScroll.use(ScrollBar)

接着在 options 传入正确的配置。

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

示例

• 竖向滚动条

  <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>

• 横向滚动条

  <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>

• 用户定制化滚动条

  <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>

• 搭配鼠标滚轮

  <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 选项对象

fade

• 类型：boolean
• 默认值：true

当滚动停止的时候，滚动条渐隐。

interactive

• 类型：boolean
• 默认值：false

滚动条是否可以交互。

customElements 2.2.0

• 类型：HTMLElement[]
• 默认值：[]

用户提供自定义的滚动条。

// 横向滚动条
const horizontalEl = document.getElementById('用户自定义的滚动条')
new BScroll('.bs-wrapper', {
  scrollY: true,
  scrollbar: {
    customElements: [horizontalEl]
  }
})
// 竖向滚动条
const verticalEl = document.getElementById('用户自定义的滚动条')
new BScroll('.bs-wrapper', {
  scrollY: false,
  scrollX: true,
  scrollbar: {
    customElements: [verticalEl]
  }
})
// 双向滚动条
const horizontalEl = document.getElementById('用户自定义的滚动条')
const verticalEl = document.getElementById('用户自定义的滚动条')
new BScroll('.bs-wrapper', {
  freeScroll: true,
  scrollbar: {
    // 当滚动条是 2 个的时候，数组第一个元素是横向滚动条
    customElements: [horizontalEl, verticalEl]
  }
})

minSize 2.2.0

• 类型：number
• 默认值：8

滚动条的最小尺寸，当用户提供了自定义的滚动条，该配置无效。

scrollbarTrackClickable 2.2.0

• 类型：boolean
• 默认值：false

滚动条轨道是否允许点击。

注意：当开启该配置的时候，请保证 BetterScroll Options 的 click 为 true，否则无法触发点击事件。详细原因在这

new BScroll('.bs-wrapper', {
  scrollY: true,
  click: true // 必不可少
  scrollbar: {
    scrollbarTrackClickable: true
  }
})

scrollbarTrackOffsetType 2.2.0

• 类型：string
• 默认值：'step'

滚动条轨道被点击之后，滚动距离的计算方式，默认与浏览器的表现形式一样，可以配置为 'clickedPoint'，代表滚动条滚动至点击的位置。

fadeInTime 2.4.0

• 类型：number
• 默认值：250

滚动条渐显的动画时长。

fadeOutTime 2.4.0

• 类型：number
• 默认值：500

滚动条渐隐的动画时长。

提示

当 scrollbar 配置为 true 的时候，插件内部使用的是默认的插件选项对象。

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

// 相当于

const bs = new BScroll('.wrapper', {
  scrollbar: {
    fade: true,
    interactive: false,
    // 以下配置项 v2.2.0 才支持
    customElements: [],
    minSize: 8,
    scrollbarTrackClickable: false,
    scrollbarTrackOffsetType: 'step',
    scrollbarTrackOffsetTime: 300,
    // 以下配置项 v2.4.0 才支持
    fadeInTime: 250,
    fadeOutTime: 500
  }
})