跳到主要内容
版本：4.x

ScrollView

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

Tips: H5 中 ScrollView 组件是通过一个高度（或宽度）固定的容器内部滚动来实现的，因此务必正确的设置容器的高度。例如: 如果 ScrollView 的高度将 body 撑开，就会同时存在两个滚动条（body 下的滚动条，以及 ScrollView 的滚动条）。 微信小程序 中 ScrollView 组件如果设置 scrollX 横向滚动时，并且子元素为多个时（单个子元素时设置固定宽度则可以正常横向滚动），需要通过 WXSS 设置 white-space: nowrap 来保证元素不换行，并对 ScrollView 内部元素设置 display: inline-block 来使其能够横向滚动。

支持情况：

参考文档

类型​

ComponentType<ScrollViewProps>

示例代码​

export default class PageView extends Component {
  constructor() {
    super(...arguments)
  }

  onScrollToUpper() {}

  // or 使用箭头函数
  // onScrollToUpper = () => {}

  onScroll(e){
    console.log(e.detail)
  }

  render() {
    const scrollStyle = {
      height: '150px'
    }
    const scrollTop = 0
    const Threshold = 20
    const vStyleA = {
      height: '150px',
      'backgroundColor': 'rgb(26, 173, 25)'
    }
    const vStyleB = {
       height: '150px',
      'backgroundColor': 'rgb(39,130,215)'
    }
    const vStyleC = {
      height: '150px',
      'backgroundColor': 'rgb(241,241,241)',
      color: '#333'
    }
    return (
      <ScrollView
        className='scrollview'
        scrollY
        scrollWithAnimation
        scrollTop={scrollTop}
        style={scrollStyle}
        lowerThreshold={Threshold}
        upperThreshold={Threshold}
        onScrollToUpper={this.onScrollToUpper.bind(this)} // 使用箭头函数的时候 可以这样写 `onScrollToUpper={this.onScrollToUpper}`
        onScroll={this.onScroll}
      >
        <View style={vStyleA}>A</View>
        <View style={vStyleB}>B</View>
        <View style={vStyleC}>C</View>
      </ScrollView>
    )
  }
}

ScrollViewProps​

类型​

typeof ScrollViewProps
参数类型默认值必填说明
scrollXbooleanfalse否允许横向滚动
scrollYbooleanfalse否允许纵向滚动
upperThresholdnumber50否距顶部/左边多远时（单位px），触发 scrolltoupper 事件
lowerThresholdnumber50否距底部/右边多远时（单位px），触发 scrolltolower 事件
scrollTopnumber否设置竖向滚动条位置
scrollLeftnumber否设置横向滚动条位置
scrollIntoViewstring否值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素
scrollWithAnimationbooleanfalse否在设置滚动条位置时使用动画过渡
enableBackToTopbooleanfalse否iOS 点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向
enableFlexbooleanfalse否启用 flexbox 布局。开启后，当前节点声明了 display: flex 就会成为 flex container，并作用于其孩子节点。
scrollAnchoringbooleanfalse否开启 scroll anchoring 特性，即控制滚动位置不随内容变化而抖动，仅在 iOS 下生效，安卓下可参考 CSS overflow-anchor 属性。
refresherEnabledbooleanfalse否开启自定义下拉刷新
refresherThresholdnumber45否设置自定义下拉刷新阈值
refresherDefaultStylestring'black'否设置自定义下拉刷新默认样式，支持设置 black or white or none， none 表示不使用默认样式
refresherBackgroundstring'#FFF'否设置自定义下拉刷新区域背景颜色
refresherTriggeredbooleanfalse否设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发
enhancedbooleanfalse否启用 scroll-view 增强特性
usingStickybooleanfalse否使 scroll-view 下的 position sticky 特性生效，否则滚动一屏后 sticky 元素会被隐藏
bouncesbooleantrue否iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效)
showScrollbarbooleantrue否滚动条显隐控制 (同时开启 enhanced 属性后生效)
pagingEnabledbooleanfalse否分页滑动效果 (同时开启 enhanced 属性后生效)
fastDecelerationbooleanfalse否boolean false 滑动减速速率控制 (同时开启 enhanced 属性后生效)
scrollAnimationDurationstring否当 scroll-with-animation设置为 true 时，可以设置 scroll-animation-duration 来控制动画的执行时间，单位 ms。
trapScrollstringfalse否纵向滚动时，当滚动到顶部或底部时，强制禁止触发页面滚动，仍然只触发 scroll-view 自身的滚动。
disableLowerScrollstring否发生滚动前，对滚动方向进行判断，当方向是顶部/左边时，如果值为 always 将始终禁止滚动，如果值为 out-of-bounds 且当前已经滚动到顶部/左边，禁止滚动。
disableUpperScrollstring否发生滚动前，对滚动方向进行判断，当方向是底部/右边时，如果值为 always 将始终禁止滚动，如果值为 out-of-bounds 且当前已经滚动到底部/右边，禁止滚动。
ariaLabelstring否无障碍访问，（属性）元素的额外描述
enablePassivebooleanfalse否开启 passive 特性，能优化一定的滚动性能
type"list" or "custom" or "nested"'list'否渲染模式
list - 列表模式。只会渲染在屏节点，会根据直接子节点是否在屏来按需渲染，若只有一个直接子节点则性能会退化
custom - 自定义模式。只会渲染在屏节点，子节点可以是 sticky-section list-view grid-view 等组件
nested - 嵌套模式。用于处理父子 scroll-view 间的嵌套滚动，子节点可以是 nested-scroll-header nested-scroll-body 组件或自定义 refresher
associativeContainer"draggable-sheet" or "nested-scroll-view" or "pop-gesture"''否关联的滚动容器
draggable-sheet - 关联 draggable-sheet 组件 3.2.0
nested-scroll-view - 关联 type=nested 嵌套模式 3.2.0
pop-gesture - 关联 页面手势返回 3.4.0
reversebooleanfalse否是否反向滚动。一般初始滚动位置是在顶部，反向滚动则是在底部。
clipbooleantrue否是否对溢出进行裁剪，默认开启
cacheExtentnumber否指定视口外渲染区域的距离，默认情况下视口外节点不渲染。指定 cache-extent 可优化滚动体验和加载速度，但会提高内存占用且影响首屏速度，可按需启用。
minDragDistancenumber18否指定 scroll-view 触发滚动的最小拖动距离。仅在 scroll-view 和其他组件存在手势冲突时使用，可通过调整该属性使得滚动更加灵敏。
padding[number, number, number, number][0,0,0,0]否长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距
scrollIntoViewWithinExtentbooleanfalse否只 scroll-into-view 到 cacheExtent 以内的目标节点，性能更佳
scrollIntoViewAlignment"start" or "center" or "end" or "nearest"'start'否指定 scroll-into-view 目标节点在视口内的位置。
start - 目标节点显示在视口开始处
center - 目标节点显示在视口中间
end - 目标节点显示在视口结束处
nearest - 目标节点在就近的视口边缘显示，若节点已在视口内则不触发滚动
refresherTwoLevelEnabledbooleanfalse否开启下拉二级能力
refresherTwoLevelTriggeredbooleanfalse否设置打开/关闭二级
refresherTwoLevelThresholdnumber150否下拉二级阈值
refresherTwoLevelCloseThresholdnumber80否滑动返回时关闭二级的阈值
refresherTwoLevelScrollEnabledbooleanfalse否处于二级状态时是否可滑动
refresherBallisticRefreshEnabledbooleanfalse否惯性滚动是否触发下拉刷新
refresherTwoLevelPinnedbooleanfalse否即将打开二级时否定住
onScrollToUpperCommonEventFunction否滚动到顶部/左边，会触发 scrolltoupper 事件
onScrollToLowerCommonEventFunction否滚动到底部/右边，会触发 scrolltolower 事件
onScrollBaseEventOrigFunction<onScrollDetail>否滚动时触发
onScrollStartBaseEventOrigFunction<onScrollDetail>否滚动开始事件
onScrollEndBaseEventOrigFunction<onScrollDetail>否滚动结束事件
onRefresherPullingCommonEventFunction否自定义下拉刷新控件被下拉
onRefresherRefreshCommonEventFunction否自定义下拉刷新被触发
onRefresherRestoreCommonEventFunction否自定义下拉刷新被复位
onRefresherAbortCommonEventFunction否自定义下拉刷新被中止
onRefresherWillRefreshCommonEventFunction否自定义下拉刷新即将触发刷新（拖动超过 refresher-threshold 时）的事件
onRefresherStatusChangeCommonEventFunction<RefresherStatusChange>否下拉刷新状态回调
onDragStartCommonEventFunction<onDragDetail>否滑动开始事件 (同时开启 enhanced 属性后生效)
onDraggingCommonEventFunction<onDragDetail>否滑动事件 (同时开启 enhanced 属性后生效)
onDragEndCommonEventFunction<onDragDetail>否滑动结束事件 (同时开启 enhanced 属性后生效)
onTouchStartCommonEventFunction否触摸动作开始。
onTouchMoveCommonEventFunction否触摸后移动。
onTouchEndCommonEventFunction否触摸动作结束。
onTouchCancelCommonEventFunction否触摸动作被打断，如来电提醒、弹窗。
onScrollStartWorkletstring否同 bindscrollstart，但仅支持 worklet 作为回调
onScrollUpdateWorkletstring否同 bindscroll ，但仅支持 worklet 作为回调
onScrollEndWorkletstring否同 bindscrollend，但仅支持 worklet 作为回调
adjustDecelerationVelocityWorkletstring否指定手指抬起时做惯性滚动的初速度。(velocity: number) => number

API 支持度​

API微信小程序百度小程序支付宝小程序抖音小程序QQ 小程序京东小程序H5React NativeHarmonyHarmony hybrid
ScrollViewProps.scrollX✔️✔️✔️✔️✔️✔️✔️✔️(二选一)✔️✔️
ScrollViewProps.scrollY✔️✔️✔️✔️✔️✔️✔️✔️(二选一)✔️✔️
ScrollViewProps.upperThreshold✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.lowerThreshold✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.scrollTop✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.scrollLeft✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.scrollIntoView✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.scrollWithAnimation✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.enableBackToTop✔️✔️✔️✔️✔️✔️
ScrollViewProps.enableFlex✔️✔️
ScrollViewProps.scrollAnchoring✔️
ScrollViewProps.refresherEnabled✔️
ScrollViewProps.refresherThreshold✔️
ScrollViewProps.refresherDefaultStyle✔️
ScrollViewProps.refresherBackground✔️
ScrollViewProps.refresherTriggered✔️
ScrollViewProps.enhanced✔️✔️
ScrollViewProps.usingSticky✔️
ScrollViewProps.bounces✔️✔️
ScrollViewProps.showScrollbar✔️✔️
ScrollViewProps.pagingEnabled✔️
ScrollViewProps.fastDeceleration✔️
ScrollViewProps.scrollAnimationDuration✔️
ScrollViewProps.trapScroll✔️
ScrollViewProps.disableLowerScroll✔️
ScrollViewProps.disableUpperScroll✔️
ScrollViewProps.ariaLabel✔️
ScrollViewProps.enablePassive✔️
ScrollViewProps.type✔️✔️
ScrollViewProps.associativeContainer✔️
ScrollViewProps.reverse✔️
ScrollViewProps.clip✔️
ScrollViewProps.cacheExtent✔️
ScrollViewProps.minDragDistance✔️
ScrollViewProps.padding✔️
ScrollViewProps.scrollIntoViewWithinExtent✔️
ScrollViewProps.scrollIntoViewAlignment✔️✔️✔️
ScrollViewProps.refresherTwoLevelEnabled✔️
ScrollViewProps.refresherTwoLevelTriggered✔️
ScrollViewProps.refresherTwoLevelThreshold✔️
ScrollViewProps.refresherTwoLevelCloseThreshold✔️
ScrollViewProps.refresherTwoLevelScrollEnabled✔️
ScrollViewProps.refresherBallisticRefreshEnabled✔️
ScrollViewProps.refresherTwoLevelPinned✔️
ScrollViewProps.onScrollToUpper✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.onScrollToLower✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.onScroll✔️✔️✔️✔️✔️✔️✔️✔️✔️✔️
ScrollViewProps.onScrollStart✔️
ScrollViewProps.onScrollEnd✔️
ScrollViewProps.onRefresherPulling✔️
ScrollViewProps.onRefresherRefresh✔️
ScrollViewProps.onRefresherRestore✔️
ScrollViewProps.onRefresherAbort✔️
ScrollViewProps.onRefresherWillRefresh✔️
ScrollViewProps.onRefresherStatusChange✔️
ScrollViewProps.onDragStart✔️
ScrollViewProps.onDragging✔️
ScrollViewProps.onDragEnd✔️
ScrollViewProps.onTouchStart✔️
ScrollViewProps.onTouchMove✔️
ScrollViewProps.onTouchEnd✔️
ScrollViewProps.onTouchCancel✔️
ScrollViewProps.onScrollStartWorklet✔️
ScrollViewProps.onScrollUpdateWorklet✔️
ScrollViewProps.onScrollEndWorklet✔️
ScrollViewProps.adjustDecelerationVelocityWorklet✔️
参数类型
RefreshStatustypeof RefreshStatus

onScrollDetail​

参数类型必填说明
scrollLeftnumber是横向滚动条位置
scrollTopnumber是竖向滚动条位置
scrollHeightnumber是滚动条高度
scrollWidthnumber是滚动条宽度
deltaXnumber是
deltaYnumber是
isDragboolean否

onDragDetail​

参数类型说明
scrollLeftnumber横向滚动条位置
scrollTopnumber竖向滚动条位置
velocitynumber滚动速度

RefresherStatusChange​

参数类型
statusRefreshStatus
dynumber