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

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

原文链接地址：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	不支持，默认 flex
scroll-anchoring	暂未支持
enhanced	不支持，默认开启
paging-enabled	不支持，可用 Skyline 手势系统实现

Bug & Tip

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

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

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

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;

}