# scroll-view

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

微信 Windows 版：支持

微信 Mac 版：支持

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况：Skyline （使用最新 Nighly 工具调试）、WebView

# 功能描述

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

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

# 通用属性

# Skyline 特有属性

# WebView 特有属性

# Bug & Tip

1. tip: 基础库 2.4.0以下不支持嵌套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: [
      ...
    ]
  },
})

网格构造器示例代码: 在开发者工具中预览效果

# 示例代码

自定义下拉刷新示例代码: 在开发者工具中预览效果

在开发者工具中预览效果