scroll-view

功能描述

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

1. 横向滚动需打开 enable-flex 以兼容 WebView，如 <scroll-view scroll-x enable-flex style="flex-direction: row;"/>
2. 滚动条的长度是预估的，若直接子节点的高度差别较大，则滚动条长度可能会不准确
3. 使用 worklet 函数需要开启开发者工具 "将 JS 编译成 ES5" 或 "编译 worklet 函数" 选项。

通用属性

| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 | | ----------------------- | ------------- | ------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------ | --- | | scroll-x | boolean | false | 否 | 允许横向滚动 | | | scroll-y | boolean | false | 否 | 允许纵向滚动 | | | upper-threshold | number/string | 50 | 否 | 距顶部/左边多远时，触发 scrolltoupper 事件 | | | lower-threshold | number/string | 50 | 否 | 距底部/右边多远时，触发 scrolltolower 事件 | | | scroll-top | number/string | | 否 | 设置竖向滚动条位置 | | | scroll-left | number/string | | 否 | 设置横向滚动条位置 | | | scroll-into-view | string | | 否 | 值应为某子元素 id（id 不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素 | | | scroll-into-view-offset | number | 0 | 否 | 跳转到 scroll-into-view 目标节点时的额外偏移。skyline 自 3.1.0 版本开始支持，webview 自 3.6.0 版本开始支持。 | | | scroll-with-animation | boolean | false | 否 | 在设置滚动条位置时使用动画过渡 | | | enable-back-to-top | boolean | false | 否 | iOS 点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向。自 2.27.3 版本开始，若非显式设置为 false，则在显示尺寸大于屏幕 90% 时自动开启。鸿蒙 OS 暂不支持 | | | enable-passive | boolean | false | 否 | 开启 passive 特性，能优化一定的滚动性能 | | | refresher-enabled | boolean | false | 否 | 开启自定义下拉刷新 | | | refresher-threshold | number | 45 | 否 | 设置自定义下拉刷新阈值 | | | refresher-default-style | string | "black" | 否 | 设置自定义下拉刷新默认样式，支持设置 black | white | none， none 表示不使用默认样式 | | | refresher-background | string | | 否 | 设置自定义下拉刷新区域背景颜色，默认为透明 | | | refresher-triggered | boolean | false | 否 | 设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发 | | | bounces | boolean | true | 否 | iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效) | | | show-scrollbar | boolean | true | 否 | 滚动条显隐控制 (同时开启 enhanced 属性后生效) | | | fast-deceleration | boolean | false | 否 | 滑动减速速率控制, 仅在 iOS 下生效 (同时开启 enhanced 属性后生效) | | | binddragstart | eventhandle | | 否 | 滑动开始事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft } | | | binddragging | eventhandle | | 否 | 滑动事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft } | | | binddragend | eventhandle | | 否 | 滑动结束事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft, velocity } | | | bindscrolltoupper | eventhandle | | 否 | 滚动到顶部/左边时触发 | | | bindscrolltolower | eventhandle | | 否 | 滚动到底部/右边时触发 | | | bindscroll | eventhandle | | 否 | 滚动时触发，event.detail = { scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY }。skyline 从 3.6.6 开始，额外具有 boundaryVelocity 字段：如果该次滚动会触碰到边界，从该次滚动触发起到下一个滚动事件发生或者当次滚动事件结束为止 boundaryVelocity 将被置为触碰边界时的速度，否则置为 NAN。 | | | bindrefresherpulling | eventhandle | | 否 | 自定义下拉刷新控件被下拉 | | | bindrefresherrefresh | eventhandle | | 否 | 自定义下拉刷新被触发 | | | bindrefresherrestore | eventhandle | | 否 | 自定义下拉刷新被复位 | | | bindrefresherabort | eventhandle | | 否 | 自定义下拉刷新被中止 | | | scroll-anchoring | boolean | false | 否 | 开启 scroll anchoring 特性，即控制滚动位置不随内容变化而抖动，可参考 CSSoverflow-anchor 属性。webview 仅在 iOS 下生效。skyline 自 3.6.2 版本开始支持，默认为 true 。 | |

Skyline 特有属性

WebView 特有属性

Bug & Tip

1. tip: 基础库 以下不支持嵌套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 自定义下拉刷新节点需要声明为 slot="refresher"，可参考自定义下拉刷新示例
6. tip: scroll-view 自定义下拉刷新可以结合 WXS 事件响应 开发交互动画

bind:refresherstatuschange

返回值 evt.detail = { status, dy }，其中 status 的枚举状态如下

export enum RefreshStatus {
  // 空闲
  Idle,
  // 超过下拉刷新阈值，同 bind:refresherwillRefresh 触发时机
  CanRefresh,
  // 下拉刷新，同 bind:refresherrefresh 触发时机
  Refreshing,
  // 下拉刷新完成，同 bind:refresherrestore 触发时机
  Completed,
  // 下拉刷新失败
  Failed,
  // 超过下拉二级阈值
  CanTwoLevel,
  // 开始打开二级
  TwoLevelOpening,
  // 打开二级
  TwoLeveling,
  // 开始关闭二级
  TwoLevelClosing,
}

下拉二级

相关接口

• 触发下拉刷新 ScrollViewContext.triggerRefresh
• 关闭下拉刷新 ScrollViewContext.closeRefresh
• 触发下拉二级 ScrollViewContext.triggerTwoLevel
• 关闭下拉二级 ScrollViewContext.closeTwoLevel

下拉二级是下拉刷新的一部份，需同时开启 refresher-enabled 和 refresher-two-level-enabled。

<scroll-view
  type="list"
  scroll-y
  refresher-enabled="{{true}}"
  refresher-two-level-enabled="{{true}}"
  refresher-two-level-scroll-enabled="{{true}}"
  <view slot="refresher"></view>
</scroll-view>

1. 当用户下拉 scroll-view 至 refresher-threshold 时松手触发下拉刷新
2. 继续下拉至 refresher-two-level-threshold 松手触发下拉二级
3. 开启 refresher-two-level-scroll-enabled 后，二级页面可以滑动关闭，是否关闭的阈值由 refresher-two-level-close-threshold 指定
4. 下拉刷新和下拉二级的展示区域由 slot=refresher 定义，开发者可根据 refresherstatuschange 判定当前阶段，展示不同内容，例如

buildText(status: RefreshStatus) {
  switch (status) {
    case RefreshStatus.Idle:
      return '下拉刷新'
    case RefreshStatus.CanRefresh:
      return '松手刷新，下拉进入二楼'
    case RefreshStatus.Refreshing:
      return '正在刷新'
    case RefreshStatus.Completed:
      return '刷新成功'
    case RefreshStatus.Failed:
      return '刷新失败'
    case RefreshStatus.CanTwoLevel:
      return '松手进入二楼'
    default:
      return ''
  }
},

下拉二级示例代码:

嵌套模式

skyline 渲染模式下，当存在两个 scroll-view 相互嵌套的场景时，两者的滚动不能很丝滑的进行衔接，故可将外层 scroll-view 改成嵌套模式，这样可以让两个 scroll-view 的滚动衔接起来。

<!-- 外层 scroll-view -->
<scroll-view
  type="nested"
  scroll-y
  refresher-enabled="{{true}}"
  <view slot="refresher">自定义 refresher</view>
  <nested-scroll-header><view>外层 scroll-vew 的节点 1</view></nested-scroll-header>
  <nested-scroll-header><view>外层 scroll-vew 的节点 2</view></nested-scroll-header>
  <nested-scroll-body>
    <swiper>
      <swiper-item>
        <!-- 里层 scroll-view -->
        <scroll-view type="list" associative-container="nested-scroll-view">
          <view>里层 scroll-vew 的节点 1</view>
          <view>里层 scroll-vew 的节点 2</view>
        </scroll-view>
      </swiper-item>
      <swiper-item></swiper-item>
      <swiper-item></swiper-item>
    </swiper>
  </nested-scroll-body>
</scroll-view>

1. 外层 scroll-view 的子节点只支持 nested-scroll-header 和 nested-scroll-body 和自定义 refresher
2. 外层 scroll-view 的子节点中只能有一个 nested-scroll-body
3. nested-scroll-header 和 nested-scroll-body 只能有一个子节点
4. nested-scroll-header 只能渲染在 nested-scroll-body 上面
5. 嵌套滚动策略：当向下滚动时，先滚动外层 scroll-view 再滚动里层 scroll-view；当向上滚动时，先滚动里层 scroll-view 再滚动外层 scroll-view

嵌套模式示例代码:

列表构造器

skyline 渲染模式下，如果列表项特别多的场景可以考虑使用列表构造器，可以实现可回收列表，回收的范围取决于 cache-extent 配置。默认情况下列表项进入视口时会被创建，而离开视口外则会被回收，即在屏的列表项才会被真正创建出来。

<scroll-view
  type="custom"
  scroll-y
   <list-builder
    list="{{list}}"
    child-count="{{list.length}}"
    child-height="200"
    bind:itembuild="onItemBuild"
    bind:itemdispose="onItemDispose"
    <view slot:item slot:index style="height: 200px;">
      <view>{{index}}</view>
    </view>
  </list-builder>
</scroll-view>

Component({
  data: {
    list: [
      ...
    ]
  },

  methods: {
    onItemBuild(evt) {
      console.log('build', evt.detail.index)
    },

    onItemDispose(evt) {
      console.log('dispose', evt.detail.index)
    },
  },
})

1. scroll-view 必须设置成 custom 模式
2. 列表项默认为定高模式，需要通过 child-height 指定，所有列表项必须等高
3. 不定高模式下因为无法知道未创建的列表项高度，会存在滚动条跳动问题
4. 默认情况下不在视口中的列表项不会被创建。在滚动过程中，会根据 child-count 判断需不需要创建/回收列表项，如果需要则会进行列表项的创建/回收，同时触发对应事件
5. 目前只支持纵向滚动列表
6. 不支持 scroll-into-view

列表构造器示例代码:

网格构造器

网格构造器和列表构造器的不定高模式类似，可参考列表构造器的使用方法和注意事项。

<scroll-view
  type="custom"
  scroll-y
   <grid-builder
    list="{{list}}"
    child-count="{{list.length}}"
    cross-axis-count="4"
        cross-axis-gap="8"
        main-axis-gap="8"
    <view slot:item slot:index style="height: 200px;">
      <view>{{index}}</view>
    </view>
  </grid-builder>
</scroll-view>

Component({
  data: {
    list: [
      ...
    ]
  },
})

网格构造器示例代码:

示例代码

自定义下拉刷新示例代码: