抖音开放平台Logo
开发者文档
小程序
控制台
  • 组件概述
  • 基础内容
  • 视图容器
  • view 视图容器
  • scroll-view 可滚动视图区域
  • swiper 滑块视图容器
  • swiper-item
  • movable-view 可移动视图容器
  • movable-area 可移动视图区域
  • mask 蒙层
  • 表单
  • 导航
  • 媒体
  • 画布
  • 地图
  • 开放能力
  • 行业开放
  • 原生组件

    • scroll-view 可滚动视图区域
    收藏
    我的收藏

    基础库 1.0.0 开始支持本组件。
    可滚动视图区域，可实现横向滚动和竖向滚动。使用竖向滚动时，需要给定一个固定高度，可以通过 ttss 来设置 height。组件属性的长度单位支持 px 和 rpx。
    如需在 <scroll-view> 中嵌套原生组件，请避免使用 vh/vw 单位设置<scroll-view> 宽高，否则部分 Android 机在该组件滚动时可能出现原生组件不跟随等异常，可用百分比为单位避免该问题。

    属性说明

    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    scroll-x
    boolean
    false
    否
    允许横向滚动。
    1.0.0
    scroll-y
    boolean
    false
    否
    允许竖向滚动。
    1.0.0
    scroll-with-animation
    boolean
    false
    否
    在设置滚动条位置时使用动画过渡。
    1.0.0
    upper-threshold
    number
    50
    否
    距顶部/左边多远时（单位 px），触发 scrolltoupper 事件。
    1.0.0
    lower-threshold
    number
    50
    否
    距底部/右边多远时（单位 px），触发 scrolltolower 事件。
    1.0.0
    scroll-top
    number
    ​
    否
    设置内容垂直滚动的像素数。
    1.0.0
    scroll-left
    number
    ​
    否
    设置内容水平滚动的像素数。
    1.0.0
    scroll-into-view
    string
    ​
    否
    值应为某子元素 id（id 不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素。
    1.0.0
    refresher-enabled
    boolean
    false
    否
    开启自定义下拉刷新。
    2.90.0
    refresher-default-style
    string
    "black"
    否
    设置自定义下拉刷新默认样式，可选值：'black' / 'white' / 'none' 。
    2.90.0
    refresher-background
    string
    "#FFF"
    否
    设置自定义下拉刷新区域背景颜色。
    2.90.0
    refresher-threshold
    number
    55
    否
    设置自定义下拉刷新阈值 (同时设置 refresher-default-style 属性为 "none" 后生效)。
    2.90.0
    refresher-triggered
    boolean
    false
    否
    设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发。
    2.90.0
    enhanced
    boolean
    false
    否
    启用 scroll-view 增强特性。
    2.90.0
    bounces
    boolean
    true
    否
    iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效)。
    2.90.0
    bindscroll
    EventHandle
    ​
    否
    滚动时触发。
    1.0.0
    bindscrolltoupper
    EventHandle
    ​
    否
    滚动到顶部/左边。
    1.0.0
    bindscrolltolower
    EventHandle
    ​
    否
    滚动到底部/右边。
    1.0.0
    bindrefresherpulling
    EventHandle
    ​
    否
    自定义下拉刷新控件被下拉。
    2.90.0
    bindrefresherrefresh
    EventHandle
    ​
    否
    自定义下拉刷新被触发。
    2.90.0
    bindrefresherrestore
    EventHandle
    ​
    否
    自定义下拉刷新被复位。
    2.90.0
    bindrefresherabort
    EventHandle
    ​
    否
    自定义下拉刷新被中止。
    2.90.0

    扫码体验

    代码示例

    Bug & Tip

      •Tip：在控制scroll-view 边界回弹时，请避免使用自定义下拉刷新。开启自定义下拉刷新后，会阻止 scroll-view 边界回弹。
      •Tip：scroll-view 是半受控组件，即该组件表现由用户行为和 data 两方共同决定。scroll-view 可以通过设置 refresher-triggered 属性来触发下拉刷新或取消下拉刷新对应的效果，但由用户行为导致的下拉/复原动作，并不会同步更新 data，因此不能根据 data 判断组件当前的下拉状态。使用 refresher-triggered 触发动画时，建议在setData的回调中设置refresher-triggered 为预期值，在setData中设置refresher-triggered为其相反值 。
      •Tip：scroll-view组件上使用 css 子选择器后会选中scroll-view组件内部实现节点，导致设置样式失效，使用后代选择器可以避免该问题。
      •Tip：在 iOS 13.1 中，使用 bindscrolltolower 事件向 scroll-view组件中添加子元素时，该组件会回到 scrollTop 为 0 的位置。将 scroll-view组件的全部子元素包裹一层 <view> 可避免该问题。
      •Tip：在使用scroll-into-view的时候，请避免在 srcoll-x 为 true 的情况下，同时设置 scroll-top ，或者在 srcoll-y 为 true 的情况下，同时设置 scroll-left ，否则容易出现滑动位置偏差的问题。
    ​