scroll-view

基础库 1.0.0 开始支持,低版本需做兼容处理

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

属性 类型 默认值 必填 说明 最低版本
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
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

Bug & Tip

  1. tip: 基础库 2.4.0以下不支持嵌套textareamapcanvasvideo 组件
  2. tip: scroll-into-view 的优先级高于 scroll-top
  3. tip: 在滚动 scroll-view 时会阻止页面回弹,所以在 scroll-view 中滚动,是无法触发 onPullDownRefresh
  4. tip: 若要使用下拉刷新,请使用页面的滚动,而不是 scroll-view ,这样也能通过点击顶部状态栏回到页面顶部
  5. tip: scroll-view 自定义下拉刷新可以结合 WXS 事件响应 开发交互动画

示例代码

scroll-view 自定义下拉刷新示例

在开发者工具中预览效果