版权声明： 本站所有内容均由互联网收集整理、上传，如涉及版权问题，请联系我们第一时间处理。

原文链接地址：​​https://developers.weixin.qq.com/miniprogram/dev/component/scroll-view.html​​


以下将展示小程序官方组件能力，组件样式仅供参考，开发者可根据自身需求定义组件样式，具体属性参数详见小程序开发文档。

功能描述：

可滚动视图区域。使用竖向滚动时，需要给scroll-view一个固定高度，通过 WXSS 设置 height。组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

属性说明：

WebView

属性

类型

默认值

必填

说明

最低版本

scroll-x

boolean

FALSE

否

允许横向滚动

1.0.0

scroll-y

boolean

FALSE

否

允许纵向滚动

1.0.0

upper-threshold

number/string

50

否

距顶部/左边多远时，触发 scrolltoupper 事件

1.0.0

lower-threshold

number/string

50

否

距底部/右边多远时，触发 scrolltolower 事件

1.0.0

scroll-top

number/string


否

设置竖向滚动条位置

1.0.0

scroll-left

number/string


否

设置横向滚动条位置

1.0.0

scroll-into-view

string


否

值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素

1.0.0

scroll-with-animation

boolean

FALSE

否

在设置滚动条位置时使用动画过渡

1.0.0

enable-back-to-top

boolean

FALSE

否

iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向

1.0.0

enable-flex

boolean

FALSE

否

启用 flexbox 布局。开启后，当前节点声明了 `display: flex` 就会成为 flex container，并作用于其孩子节点。

2.7.3

scroll-anchoring

boolean

FALSE

否

开启 scroll anchoring 特性，即控制滚动位置不随内容变化而抖动，仅在 iOS 下生效，安卓下可参考 CSS `overflow-anchor` 属性。

2.8.2

refresher-enabled

boolean

FALSE

否

开启自定义下拉刷新

2.10.1

refresher-threshold

number

45

否

设置自定义下拉刷新阈值

2.10.1

refresher-default-style

string

"black"

否

设置自定义下拉刷新默认样式，支持设置 `black | white | none`， none 表示不使用默认样式

2.10.1

refresher-background

string

"#FFF"

否

设置自定义下拉刷新区域背景颜色

2.10.1

refresher-triggered

boolean

FALSE

否

设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发

2.10.1

enhanced

boolean

FALSE

否

​​启用 scroll-view 增强特性，启用后可通过 ScrollViewContext 操作 scroll-view​​​

2.12.0

bounces

boolean

TRUE

否

iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效)

2.12.0

show-scrollbar

boolean

TRUE

否

滚动条显隐控制 (同时开启 enhanced 属性后生效)

2.12.0

paging-enabled

boolean

FALSE

否

分页滑动效果 (同时开启 enhanced 属性后生效)

2.12.0

fast-deceleration

boolean

FALSE

否

滑动减速速率控制 (同时开启 enhanced 属性后生效)

2.12.0

binddragstart

eventhandle


否

滑动开始事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft }

2.12.0

binddragging

eventhandle


否

滑动事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft }

2.12.0

binddragend

eventhandle


否

滑动结束事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft, velocity }

2.12.0

bindscrolltoupper

eventhandle


否

滚动到顶部/左边时触发

1.0.0

bindscrolltolower

eventhandle


否

滚动到底部/右边时触发

1.0.0

bindscroll

eventhandle


否

滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

1.0.0

bindrefresherpulling

eventhandle


否

自定义下拉刷新控件被下拉

2.10.1

bindrefresherrefresh

eventhandle


否

自定义下拉刷新被触发

2.10.1

bindrefresherrestore

eventhandle


否

自定义下拉刷新被复位

2.10.1

bindrefresherabort

eventhandle


否

自定义下拉刷新被中止

2.10.1

Skyline

组件差异

1. 默认只会渲染在屏节点，会根据直接子节点是否在屏来按需渲染，若只有一个直接子节点则性能会退化

2. 横向滚动需打开 enable-flex 以兼容 WebView，如<scroll-view scroll-x enable-flex style="flex-direction: row;"/>

3. 滚动条的长度是预估的，若直接子节点的高度差别较大，则滚动条长度可能会不准确

属性

说明

type

新增必填属性且目前只有 list 选项；后续计划提供 type=custom 等更多列表特性

enable-back-to-top

暂未支持

enable-flex

不支持，默认

scroll-anchoring

暂未支持

enhanced

不支持，默认开启

paging-enabled

不支持，可用 Skyline 手势系统实现

Bug & Tip

1. tip: 基础库 2.4.0以下不支持嵌套textarea、map、canvas、video 组件

2. tip: scroll-into-view 的优先级高于

3. tip: 在滚动 scroll-view 时会阻止页面回弹，所以在 scroll-view 中滚动，是无法触发

4. tip: 若要使用下拉刷新，请使用页面的滚动，而不是 scroll-view ，这样也能通过点击顶部状态栏回到页面顶部

5. tip: scroll-view 自定义下拉刷新可以结合 WXS 事件响应 开发交互动画

示例代码：

JAVASCRIPT：

const order = ['demo1', 'demo2', 'demo3']

Page({
  onShareAppMessage() {
    return {
      title: 'scroll-view',
      path: 'page/component/pages/scroll-view/scroll-view'
    }
  },

  data: {
    toView: 'green'
  },

  upper(e) {
    console.log(e)
  },

  lower(e) {
    console.log(e)
  },

  scroll(e) {
    console.log(e)
  },

  scrollToTop() {
    this.setAction({
      scrollTop: 0
    })
  },

  tap() {
    for (let i = 0; i < order.length; ++i) {
      if (order[i] === this.data.toView) {
        this.setData({
          toView: order[i + 1],
          scrollTop: (i + 1) * 200
        })
        break
      }
    }
  },

  tapMove() {
    this.setData({
      scrollTop: this.data.scrollTop + 10
    })
  }
})

WXML：

<view class="container">
  <view class="page-body">
    <view class="page-section">
      <view class="page-section-title">
        <text>Vertical Scroll\n纵向滚动</text>
      </view>
      <view class="page-section-spacing">
        <scroll-view scroll-y="true" style="height: 300rpx;" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}">
          <view id="demo1" class="scroll-view-item demo-text-1"></view>
          <view id="demo2"  class="scroll-view-item demo-text-2"></view>
          <view id="demo3" class="scroll-view-item demo-text-3"></view>
        </scroll-view>
      </view>
    </view>
    <view class="page-section">
      <view class="page-section-title">
        <text>Horizontal Scroll\n横向滚动</text>
      </view>
      <view class="page-section-spacing">
        <scroll-view class="scroll-view_H" scroll-x="true" bindscroll="scroll" style="width: 100%">
          <view id="demo1" class="scroll-view-item_H demo-text-1"></view>
          <view id="demo2"  class="scroll-view-item_H demo-text-2"></view>
          <view id="demo3" class="scroll-view-item_H demo-text-3"></view>
        </scroll-view>
      </view>
    </view>
  </view>
</view>

WXSS：

.page-section-spacing{
  margin-top: 60rpx;
}
.scroll-view_H{
  white-space: nowrap;
}
.scroll-view-item{
  height: 300rpx;
}
.scroll-view-item_H{
  display: inline-block;
  width: 100%;
  height: 300rpx;
}

微信小程序官方组件展示之视图容器scroll-view_微信小程序