# pulldown

# Introduction

The pulldown plugin provides BetterScroll with the ability to monitor pulldown operation.

# Install

npm install @better-scroll/pull-down --save

// or

yarn add @better-scroll/pull-down

# Usage

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

import BScroll from '@better-scroll/core'
import PullDown from '@better-scroll/pull-down'

BScroll.use(PullDown)

pass in the correct configuration in options, for example:

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

# Demo

Basic Usage

<template>
  <div class="pulldown">
    <div
      class="pulldown-bswrapper"
      ref="bsWrapper"
    >
      <div class="pulldown-scroller">
        <div class="pulldown-wrapper">
          <div v-show="beforePullDown">
            <span>Pull Down and refresh</span>
          </div>
          <div v-show="!beforePullDown">
            <div v-show="isPullingDown">
              <span>Loading...</span>
            </div>
            <div v-show="!isPullingDown">
              <span>Refresh success</span>
            </div>
          </div>
        </div>
        <ul class="pulldown-list">
          <li
            :key="i"
            class="pulldown-list-item"
            v-for="i of dataList"
          >{{ `I am item ${i} ` }}</li>
        </ul>
      </div>
    </div>
  </div>
</template>

<script>
import BScroll from '@better-scroll/core'
import PullDown from '@better-scroll/pull-down'

BScroll.use(PullDown)

function generateData() {
  const BASE = 30
  const begin = BASE * STEP
  const end = BASE * (STEP + 1)
  let ret = []
  for (let i = end; i > begin; i--) {
    ret.push(i)
  }
  return ret
}

const TIME_BOUNCE = 800
const REQUEST_TIME = 1000
const THRESHOLD = 70
const STOP = 56
let STEP = 0

export default {
  data() {
    return {
      beforePullDown: true,
      isPullingDown: false,
      dataList: generateData()
    }
  },
  mounted() {
    this.initBscroll()
  },
  methods: {
    initBscroll() {
      this.bscroll = new BScroll(this.$refs.bsWrapper, {
        scrollY: true,
        bounceTime: TIME_BOUNCE,
        useTransition: false,
        pullDownRefresh: {
          threshold: THRESHOLD,
          stop: STOP
        }
      })

      this.bscroll.on('pullingDown', this.pullingDownHandler)
      this.bscroll.on('scroll', this.scrollHandler)
      this.bscroll.on('scrollEnd', e => {
        console.log('scrollEnd')
      })
    },
    scrollHandler(pos) {
      console.log(pos.y)
    },
    async pullingDownHandler() {
      console.log('trigger pullDown')
      this.beforePullDown = false
      this.isPullingDown = true
      STEP += 1

      await this.requestData()

      this.isPullingDown = false
      this.finishPullDown()
    },
    async finishPullDown() {
      this.bscroll.finishPullDown()
      setTimeout(() => {
        this.beforePullDown = true
        this.bscroll.refresh()
      }, TIME_BOUNCE + 100)
    },
    async requestData() {
      try {
        const newData = await this.ajaxGet(/* url */)
        this.dataList = newData.concat(this.dataList)
      } catch (err) {
        // handle err
        console.log(err)
      }
    },
    ajaxGet(/* url */) {
      return new Promise(resolve => {
        setTimeout(() => {
          const dataList = generateData()
          resolve(dataList)
        }, REQUEST_TIME)
      })
    }
  }
}
</script>

Sina-Weibo 2.4.0

<template>
  <div class="pulldown-sina">
    <div
      class="pulldown-bswrapper"
      ref="bsWrapper"
    >
      <div class="pulldown-scroller">
        <div class="pulldown-wrapper">
          <div v-html="tipText"></div>
        </div>
        <ul class="pulldown-list">
          <li
            :key="i"
            class="pulldown-list-item"
            v-for="i of dataList"
          >{{ `I am item ${i} ` }}</li>
        </ul>
      </div>
    </div>
  </div>
</template>

<script>
import BScroll from '@better-scroll/core'
import PullDown from '@better-scroll/pull-down'

BScroll.use(PullDown)

function generateData() {
  const BASE = 30
  const begin = BASE * STEP
  const end = BASE * (STEP + 1)
  let ret = []
  for (let i = end; i > begin; i--) {
    ret.push(i)
  }
  return ret
}

// pulldownRefresh state
const PHASE = {
  moving: {
    enter: 'enter',
    leave: 'leave'
  },
  fetching: 'fetching',
  succeed: 'succeed'
}
const TIME_BOUNCE = 800
const REQUEST_TIME = 2000
const THRESHOLD = 70
const STOP = 56
let STEP = 0
const ARROW_BOTTOM = '<svg width="16" height="16" viewBox="0 0 512 512"><path fill="currentColor" d="M367.997 338.75l-95.998 95.997V17.503h-32v417.242l-95.996-95.995l-22.627 22.627L256 496l134.624-134.623l-22.627-22.627z"></path></svg>'
const ARROW_UP = '<svg width="16" height="16" viewBox="0 0 512 512"><path fill="currentColor" d="M390.624 150.625L256 16L121.376 150.625l22.628 22.627l95.997-95.998v417.982h32V77.257l95.995 95.995l22.628-22.627z"></path></svg>'

export default {
  data() {
    return {
      tipText: '',
      isPullingDown: false,
      dataList: generateData()
    }
  },
  mounted() {
    this.initBscroll()
  },
  methods: {
    initBscroll() {
      this.bscroll = new BScroll(this.$refs.bsWrapper, {
        scrollY: true,
        bounceTime: TIME_BOUNCE,
        useTransition: false,
        pullDownRefresh: {
          threshold: THRESHOLD,
          stop: STOP
        }
      })

      this.bscroll.on('pullingDown', this.pullingDownHandler)
      this.bscroll.on('scrollEnd', e => {
        console.log('scrollEnd')
      })
      // v2.4.0 supported
      this.bscroll.on('enterThreshold', () => {
        this.setTipText(PHASE.moving.enter)
      })
      this.bscroll.on('leaveThreshold', () => {
        this.setTipText(PHASE.moving.leave)
      })
    },
    async pullingDownHandler() {
      this.setTipText(PHASE.fetching)
      STEP += 1
      await this.getData()

      this.setTipText(PHASE.succeed)
      // tell BetterScroll to finish pull down
      this.bscroll.finishPullDown()
      // waiting for BetterScroll's bounceAnimation then refresh size
      setTimeout(() => {
        this.bscroll.refresh()
      }, TIME_BOUNCE + 50)
    },
    async getData() {
      const newData = await this.mockFetchData()
      this.dataList = newData.concat(this.dataList)
    },
    mockFetchData() {
      return new Promise(resolve => {
        setTimeout(() => {
          const dataList = generateData()
          resolve(dataList)
        }, REQUEST_TIME)
      })
    },
    setTipText(phase = PHASE.default) {
      const TEXTS_MAP = {
        'enter': `${ARROW_BOTTOM} Pull down`,
        'leave': `${ARROW_UP} Release`,
        'fetching': 'Loading...',
        'succeed': 'Refresh succeed'
      }
      this.tipText = TEXTS_MAP[phase]
    }
  }
}
</script>

In order to match the effects of App, in version v2.4.0, pulldown has made some changes and is compatible with previous versions. During a pulldown procedure, there are three internal circulation states, and the states are irreversible. They are as follows:

default

The initial state.

moving

Moving state, this state represents that the user's finger is manipulating BetterScroll, and the finger is keeping in touch. In this state, BetterScroll will dispatch two events.

enterThreshold

Dispatched when BetterScroll scrolls into the pulldown threshold area. Inside this event, you can do the logic of texts initialization, such as prompting the user to "pull down to refresh"
leaveThreshold

Dispatched when BetterScroll scrolls out of the pulldown threshold area. You can prompt the user to "Release finger"

fetching

Once the finger went away, the pullingDown event is triggered to execute the logic of fetching data

The state change can only be default -> moving -> fetching or default -> moving. The latter means that at the moment the user's finger is released, the conditions for triggering the pullingDown event are not met.

# pullDownRefresh Options

# threshold

Type: number
Default: 90

Configure the top pull-down distance to determine dispatching pullingDown hooks.

# stop

Type: number
Default: 40

Rebound distance. After BetterScroll dispatches the pullingDown hook, it will immediately execute the rebound animation.

TIP

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

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

// equals

const bs = new BScroll('.wrapper', {
  pullDownRefresh: {
    threshold: 90,
    stop: 40
  }
})

# Instance Methods

TIP

All methods are proxied to BetterScroll instance, for example:

import BScroll from '@better-scroll/core'
import PullDown from '@better-scroll/pull-down'

BScroll.use(PullDown)

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

bs.finishPullDown()
bs.openPullDown({})
bs.autoPullDownRefresh()

# `finishPullDown()`

Details: End the pull-down refresh behavior.

WARNING

Every time the pullingDown hook is triggered, you should actively call finishPullDown() to tell BetterScroll to be ready for the next pullingDown hook.

# `openPullDown(config: PullDownRefreshOptions = {})`

Details: Turn on the pull-down refresh dynamically.

Arguments:

{ PullDownRefreshOptions } config: Modify the option of the pulldown plugin
PullDownRefreshOptions:

export type PullDownRefreshOptions = Partial<PullDownRefreshConfig> | true

export interface PullDownRefreshConfig {
  threshold: number
  stop: number
}

WARNING

The openPullDown method should be used with closePullDown, because in the process of generating the pulldown plugin, the pull-down refresh action has been automatically monitored.

# `closePullDown()`

Details: Turn off the pull-down refresh dynamically.

# Events

# `pullingDown`

Arguments: None
Trigger: A pullingDown event is fired when the top pull-down distance is greater than the threshold value after touchend.

Note

After the pull-down refresh action is detected, the consumption opportunity of the pullingDown hook is only once, so you need to call finishPullDown() to tell BetterScroll to provide the next consumption opportunity of the pullingDown event.

# `enterThreshold` 2.4.0

Arguments: None
Trigger: when pulldown is in the moving state and enters threshold area.

# `leaveThreshold` 2.4.0

Arguments: None
Trigger: when pulldown is in the moving state and leaves threshold area.

← observe-image pullup →