BetterScroll 2.0

# wheel

# Introduction

The wheel plugin is the cornerstone for implementing similar iOS Picker components.

# Install

npm install @better-scroll/wheel --save

// or

yarn add @better-scroll/wheel

# Usage

import wheel, then call BScroll.use().

import BScroll from '@better-scroll/core'
import Wheel from '@better-scroll/wheel'

BScroll.use(Wheel)

pass in the correct configuration in options, for example:

  let bs = new BScroll('.bs-wrapper', {
    wheel: true // wheel options
  })

TIP

Wheel options is true or object, otherwise the plugin is invalid, please refer to wheel options.

WARNING

BetterScroll combined with the Wheel plugin is just the JS logic part of the Picker effect, and the DOM template is user-implemented. Fortunately, for most Picker scenarios, we have corresponding examples.

  • Basic usage

    <template>
  <div class="container">
    <ul class="example-list">
      <li class="example-item" @click="show">
          <span class="open">{{selectedText}}</span>
      </li>
    </ul>
    <transition name="picker-fade">
      <div class="picker" v-show="state===1" @touchmove.prevent @click="_cancel">
        <transition name="picker-move">
          <div class="picker-panel" v-show="state===1" @click.stop>
            <div class="picker-choose border-bottom-1px">
              <span class="cancel" @click="_cancel">Cancel</span>
              <span class="confirm" @click="_confirm">Confirm</span>
              <h1 class="picker-title">Title</h1>
            </div>
            <div class="picker-content">
              <div class="mask-top border-bottom-1px"></div>
              <div class="mask-bottom border-top-1px"></div>
              <div class="wheel-wrapper" ref="wheelWrapper">
                <div class="wheel">
                  <ul class="wheel-scroll">
                    <li
                      v-for="(item, index) in pickerData" :key="index"
                      :class="{'wheel-disabled-item':item.disabled}"
                      class="wheel-item">{{item.text}}</li>
                  </ul>
                </div>
              </div>
            </div>
            <div class="picker-footer"></div>
          </div>
        </transition>
      </div>
    </transition>
  </div>
</template>

    Single-column Picker is a more common effect. You can use selectedIndex to configure the item that initializes the corresponding index. wheelDisabledItemClass configures the item you want to disable to simulate the Web Select tag's disable option.

  • Double-column Picker

    The JS logic part is not much different from the single-column selector. You will find that there is no correlation between the two column selectors because they are two different BetterScroll instances. If you want to achieve the effect of the provincial and city linkage, then add a part of the code to make the two BetterScroll instances can be associated. Please see the next example:

  • Linkage Picker

    The effect of the city linkage Picker must be linked through the JS part of the logic to the different instances of BetterScroll.

# wheel options

TIP

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

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

// equals

const bs = new BScroll('.wrapper', {
  wheel: {
    wheelWrapperClass: 'wheel-scroll',
    wheelItemClass: 'wheel-item',
    rotate: 25,
    adjustTime: 400,
    selectedIndex: 0,
    wheelDisabledItemClass: 'wheel-disabled-item'
  }
})

# selectedIndex

  • Type: number
  • Default：0

Instantiate the Wheel, the selectedIndex item is selected by default, and the index starts from 0.

# rotate

  • Type: number
  • Default: 25

When rolling the wheel, the degree of bending of the wheel item.

# adjustTime

  • Type: number
  • Default: 400(ms)

When an item is clicked, the duration of scroll.

# wheelWrapperClass

  • Type: string
  • Default: wheel-scroll

The className of the scroll element, where "scroll element" refers to the content element of BetterScroll.

# wheelItemClass

  • Type: string
  • Default: wheel-item

The style of the child elements of the scroll element.

# wheelDisabledItemClass

  • Type: string
  • Default: wheel-disabled-item

The child element that you want to disable in the scroll element is similar to the effect of the disabled option in the select element. The wheel plugin judges whether the item is designated as disabled according to the wheelDisabledItemClass configuration.

# Instance Methods

TIP

All methods are proxied to BetterScroll instance, for example:

import BScroll from '@better-scroll/core'
import Wheel from '@better-scroll/wheel'

BScroll.use(Wheel)

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

bs.getSelectedIndex()
bs.wheelTo(1, 300)

# getSelectedIndex()

  • Returns: The index of the currently selected item, the subscript starts from 0

Get the index of the currently selected item.

# wheelTo(index = 0, time = 0, [ease])

  • Arguments:
    • { number } index
    • { number } time: Animation duration
    • { number } ease<Optional>: Ease effect configuration, refer to ease.ts (opens new window), the default is bounce effect
    interface EaseItem {
  style: string
  fn(t: number): number
}

Scroll to the list item corresponding to the index.

# stop() 2.1.0

Force the scrolling BetterScroll to stop and snap to the position of the wheel-item closest to the current one.

# restorePosition() 2.1.0

Force the scrolling BetterScroll to stop and return to the position before the scrolling started.

TIP

The above two methods are only valid for the scrolling BetterScroll, and restorePosition is exactly the same as the original iOS Picker component. Users can choose the corresponding method according to their needs.

# Events

# wheelIndexChanged 2.1.0

  • Arguments: The index of the current selected wheel-item.
  • Trigger timing: When the selected wheel-item changes.
import BScroll from '@better-scroll/core'
import Wheel from '@better-scroll/wheel'

BScroll.use(Wheel)

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

bs.on('wheelIndexChanged', (index) => {
  console.log(index)
})

← zoom →