WeChat Open Platform

Mini Programs Documentation

scroll-view

A scrollable view area

Attribute name Type Default value Description
scroll-x Boolean false Allows horizontal scrolling
scroll-y Boolean false Allows vertical scrolling
upper-threshold Number 50 A scrolltoupper event is triggered when far from the top/left (unit px)
lower-threshold Number 50 A scrolltolower event is triggered when far from the bottom/right (unit px)
scroll-top Number Sets vertical scroll bar position
scroll-left Number Sets horizontal scroll bar position
scroll-into-view String Value should be a child element id (id cannot begin with a number), then the top of the element is aligned at the top of the scroll area when this element is scrolled to, only supports vertical scrolling
scroll-with-animation Boolean false Uses animated transition when scroll bar position is set
enable-back-to-top Boolean false Scroll bar returns to top when the top status bar is tapped in iOS, or the title bar is tapped in Android, only supports vertical
bindscrolltoupper EventHandle Scrolling to the top/left will trigger a scrolltoupper event
bindscrolltolower EventHandle Scrolling to the bottom/right will trigger a scrolltolower event
bindscroll EventHandle Triggered when scrolling, event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

<scroll-view/> needs to be given a fixed height when using vertical scrolling. The height is set using WXSS.

Sample code:

<view class="section">
  <view class="section__title">vertical scroll</view>
  <scroll-view scroll-y="true" style="height: 200px;" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}">
    <view id="green" class="scroll-view-item bc_green"></view>
    <view id="red"  class="scroll-view-item bc_red"></view>
    <view id="yellow" class="scroll-view-item bc_yellow"></view>
    <view id="blue" class="scroll-view-item bc_blue"></view>
  </scroll-view>

  <view class="btn-area">
    <button size="mini" bindtap="tap">click me to scroll into view </button>
    <button size="mini" bindtap="tapMove">click me to scroll</button>
  </view>
</view>
<view class="section section_gap">
  <view class="section__title">horizontal scroll</view>
  <scroll-view class="scroll-view_H" scroll-x="true" style="width: 100%">
    <view id="green" class="scroll-view-item_H bc_green"></view>
    <view id="red"  class="scroll-view-item_H bc_red"></view>
    <view id="yellow" class="scroll-view-item_H bc_yellow"></view>
    <view id="blue" class="scroll-view-item_H bc_blue"></view>
  </scroll-view>
</view>
var order = ['red', 'yellow', 'blue', 'green', 'red']
Page({
  data: {
    toView: 'red',
    scrollTop: 100
  },
  upper: function(e) {
    console.log(e)
  },
  lower: function(e) {
    console.log(e)
  },
  scroll: function(e) {
    console.log(e)
  },
  tap: function(e) {
    for (var i = 0; i < order.length; ++i) {
      if (order[i] === this.data.toView) {
        this.setData({
          toView: order[i + 1]
        })
        break
      }
    }
  },
  tapMove: function(e) {
    this.setData({
      scrollTop: this.data.scrollTop + 10
    })
  }
})

scroll-view

Bugs & Tips

  1. tip: Please do not use the textarea, map, canvas, or video components in scroll-view.
  2. tip: scroll-into-view has higher priority than scroll-top.
  3. tip: The page will be prevented from bouncing when scrolling scroll-view, so onPullDownRefresh cannot be triggered when scrolling in scroll-view.
  4. tip: If you want to use pull down refresh, please use page scrolling instead of scroll-view. This way, you can also return to the top of the page by tapping the status bar at the top.