BetterScroll 2.0

# wheel

# 介绍

wheel 插件，是实现类似 IOS Picker 组件的基石。

# 安装

npm install @better-scroll/wheel --save

// or

yarn add @better-scroll/wheel

# 使用

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

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

BScroll.use(Wheel)

接着在 options 传入正确的配置

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

TIP

wheel options 是 true 或者对象，否则插件功能失效，具体请参考 wheel options。

危险

BetterScroll 结合 wheel 插件只是实现 Picker 效果的 JS 逻辑部分，还有 DOM 模版是需要用户去实现，所幸，对于大多数的 Picker 场景，我们给出了相对应的示例。

  • 基本使用

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

    单列 Picker 是一个比较常见的效果。你可以通过 selectedIndex 来配置初始化时选中对应索引的 item，wheelDisabledItemClass 配置想要禁用的 item 项来模拟 Web Select 标签 disable 的效果。

  • 多项选择器

    示例是一个两列的选择器，JS 逻辑部分与单列选择器没有多大的区别，你会发现这个两列选择器之间是没有任何关联，因为它们是两个不同的 BetterScroll 实例。如果你想要实现省市联动的效果，那么得加上一部分代码，让这两个 BetterScroll 实例能够关联起来。请看下一个例子：

  • 城市联动选择器

    城市联动 Picker 的效果，必须通过 JS 部分逻辑将不同 BetterScroll 的实例联系起来，不管是省市，还是省市区的联动，亦是如此。

# wheel 选项对象

提示

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

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

// 相当于

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

# selectedIndex

  • 类型：number
  • 默认值：0

实例化 Wheel，默认选中第 selectedIndex 项，索引从 0 开始。

# rotate

  • 类型：number
  • 默认值：25

当滚动 wheel 时，wheel item 的弯曲程度。

# adjustTime

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

当点击某一项的时候，滚动过去的动画时长。

# wheelWrapperClass

  • 类型：string
  • 默认值：wheel-scroll

滚动元素的 className，这里的「滚动元素」 指的就是 BetterScroll 的 content 元素。

# wheelItemClass

  • 类型：string
  • 默认值：wheel-item

滚动元素的子元素的样式。

# wheelDisabledItemClass

  • 类型：string
  • 默认值：wheel-disabled-item

滚动元素中想要禁用的子元素，类似于 select 元素中禁用的 option 效果。wheel 插件的内部根据 wheelDisabledItemClass 配置来判断是否将该项指定为 disabled 状态。

# 实例方法

提示

以下方法皆已代理至 BetterScroll 实例，例如：

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

  • 返回值：当前选中项的 index，下标从 0 开始

获取当前选中项的索引。

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

  • 参数：
    • { number } index：选项索引
    • { number } time：动画时长
    • { number } ease<可选>：动画时长。缓动效果配置，参考 ease.ts (opens new window)，默认是 bounce 效果

滚动至对应索引的列表项。

# stop() 2.1.0

强制让滚动的 BetterScroll 停止下来，并且吸附至当前距离最近的 wheel-item 的位置。

# restorePosition() 2.1.0

强制让滚动的 BetterScroll 停止下来，并且恢复至滚动开始前的位置。

提示

以上两个方法只对处于滚动中的 BetterScroll 有效，并且 restorePosition 是与原生的 iOS picker 组件的效果一模一样，用户可以根据自己的需求选择对应的方法。

# 事件

# wheelIndexChanged 2.1.0

  • 参数：当前选中的 wheel-item 的索引。
  • 触发时机：当列表项发生改变的时候。
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 →