支付宝小程序组件 可滚动视图区域·scroll-view

可滚动视图区域。scroll-view 滚动条无法隐藏，可以全局禁用滚动，但是无法禁用 scroll-view 中的滚动距离展示。

说明：

• 使用竖向滚动时，需要指定固定高度，可通过 acss 设置 height。
• scroll-into-view 的优先级高于 scroll-top。
• 在滚动 scroll-view 时会阻止页面回弹，所以在 scroll-view 中滚动，无法触发 onPullDownRefresh 下拉刷新功能。
• scroll-view 不支持 scroll-x=true 和 scroll-y=true 同时生效，只能用一个。可以使用 view 设置 disable-scroll 为 true 禁止滑动。
• scroll-view 满屏时，无法滑动页面，会导致导航栏滑动透明失效。可通过 my.setNavigationBar 设置导航栏样式：导航栏标题、导航栏背景色、导航栏底部边框颜色、导航栏左上角 logo 图片。
• 可以监听 ScrollView 父 view 的触摸事件控制 ScrollView 的滑动来达到取消惯性的效果。
• scroll-view 组件不支持自定义下拉刷新以及滚动条。

扫码体验

示例代码

// API-DEMO page/component/scroll-view.json
{
  "defaultTitle": "Scroll View"
}
<!-- API-DEMO page/component/scroll-view.axml -->
<view class="page">
  <view class="page-description">可滚动视图区域</view>
  <view class="page-section">
    <view class="page-section-title">vertical scroll</view>
    <view class="page-section-demo">
      <scroll-view scroll-y="{{true}}" style="height: 200px;" onScrollToUpper="upper" onScrollToLower="lower" onScroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}">
        <view id="blue" class="scroll-view-item bc_blue"></view>
        <view id="red"  class="scroll-view-item bc_red"></view>
        <view id="yellow" class="scroll-view-item bc_yellow"></view>
        <view id="green" class="scroll-view-item bc_green"></view>
      </scroll-view>
    </view>
    <view class="page-section-btns">
      <view onTap="tap">next</view>
      <view onTap="tapMove">move</view>
      <view onTap="scrollToTop">scrollToTop</view>
    </view>
  </view>


  <view class="page-section">
    <view class="page-section-title">horizontal scroll</view>
    <view class="page-section-demo">
      <scroll-view class="scroll-view_H" scroll-x="{{true}}" style="width: 100%" >
        <view id="blue2" class="scroll-view-item_H bc_blue"></view>
        <view id="red2"  class="scroll-view-item_H bc_red"></view>
        <view id="yellow2" class="scroll-view-item_H bc_yellow"></view>
        <view id="green2" class="scroll-view-item_H bc_green"></view>
      </scroll-view>
    </view>
  </view>
</view>
// API-DEMO page/component/scroll-view.js
const order = ['blue', 'red', 'green', 'yellow'];


Page({
  data: {
    toView: 'red',
    scrollTop: 100,
  },
  upper(e) {
    console.log(e);
  },
  lower(e) {
    console.log(e);
  },
  scroll(e) {
    this.setData({
      scrollTop: e.detail.scrollTop,
    });
  },
  scrollEnd() {


  },
  scrollToTop(e) {
    console.log(e);
    this.setData({
      scrollTop: 0,
    });
  },
  tap(e) {
    for (let i = 0; i < order.length; ++i) {
      if (order[i] === this.data.toView) {
        const next = (i + 1) % order.length;
        this.setData({
          toView: order[next],
          scrollTop: next * 200,
        });
        break;
      }
    }
  },
  tapMove() {
    this.setData({
      scrollTop: this.data.scrollTop + 10,
    });
  },
});
/* API-DEMO page/component/swiper-view.acss */
.scroll-view_H {
  white-space: nowrap;
  display:flex;
}
.scroll-view-item {
  height: 200px;
}
.scroll-view-item_H {
  flex-shrink:0;
  flex-grow:0;
  width: 300px;
  height: 200px;
}

属性

属性	类型	默认值	描述	最低版本
class	String	-	外部样式名。	-
style	String	-	内联样式名。	-
scroll-x	Boolean	false	允许横向滚动。	-
scroll-y	Boolean	false	允许纵向滚动。	-
upper-threshold	Number	50	距顶部/左边多远时（单位px），触发 scrolltoupper 事件。	-
lower-threshold	Number	50	距底部/右边多远时（单位px），触发 scrolltolower 事件。	-
scroll-top	Number	-	设置竖向滚动条位置。	-
scroll-left	Number	-	设置横向滚动条位置。	-
scroll-into-view	String	-	值应为某子元素 id，则滚动到该元素，元素顶部对齐滚动区域顶部。	-
scroll-with-animation	Boolean	false	在设置滚动条位置时使用动画过渡。	-
scroll-animation-duration	Number	-	当 scroll-with-animation 设置为 true 时，可以设置 scroll-animation-duration 来控制动画的执行时间，单位 ms。	1.9.0
enable-back-to-top	Boolean	false	当点击 iOS 顶部状态栏或者双击安卓标题栏时，滚动条返回顶部，只支持竖向。	1.11.0
trap-scroll	Boolean	false	纵向滚动时，当滚动到顶部或底部时，强制禁止触发页面滚动，仍然只触发 scroll-view 自身的滚动。	1.11.2
onScrollToUpper	EventHandle	-	滚动到顶部/左边，会触发 scrolltoupper 事件。	-
onScrollToLower	EventHandle	-	滚动到底部/右边，会触发 scrolltolower 事件。	-
onScroll	EventHandle	-	滚动时触发， event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth}。	-
onTouchStart	EventHandle	-	触摸动作开始。	1.15.0
onTouchMove	EventHandle	-	触摸后移动。	1.15.0
onTouchEnd	EventHandle	-	触摸动作结束。	1.15.0
onTouchCancel	EventHandle	-	触摸动作被打断，如来电提醒、弹窗。	1.15.0

常见问题

为何 scroll-view 在 popup 扩展组件中无法滑动？

popup 组件上加上 disableScroll={{false}} 属性才能滑动

为何使用 swiper 嵌套 scroll-view，scroll-view无法滑动？

swiper 和 scroll-view 均为滑动组件，如果必须使用，建议不做嵌套或者让 scroll-view 阻止 touch 事件冒泡即可：catchTouchStart、catchTouchMove。

如何监听 scroll-view 滚动到底部？

可以直接在 onScroll 方法中进行处理，使用 onScrollToLower 监听 scroll-view 的滚动高度来进行判断是否滑动到了底部。 scrollheight 是 scroll-view 里面所有 view 的高度和，scrollTop 是滚动的值； scrolltop 的值等于 scrollheight-scrollview 视图的高度。

为何在页面有蒙层的情况下，外层滑动到底部，会导致蒙层也能滑动？

在外层 scroll-view 添加属性 trap-scroll。