# scroll-view

基礎(chǔ)庫(kù) 1.0.0 開始支持，低版本需做兼容處理。

微信 Windows 版：支持

微信 Mac 版：支持

微信 鴻蒙 OS 版：支持

相關(guān)文檔: Skyline 渲染引擎、Skyline 遷移起步

渲染框架支持情況：Skyline （使用最新 Nightly 工具調(diào)試）、WebView

# 功能描述

可滾動(dòng)視圖區(qū)域。使用豎向滾動(dòng)時(shí)，需要給scroll-view一個(gè)固定高度，通過(guò) WXSS 設(shè)置 height。組件屬性的長(zhǎng)度單位默認(rèn)為px，2.4.0起支持傳入單位(rpx/px)。

1. 橫向滾動(dòng)需打開 enable-flex 以兼容 WebView，如 <scroll-view scroll-x enable-flex style="flex-direction: row;"/>
   
2. 滾動(dòng)條的長(zhǎng)度是預(yù)估的，若直接子節(jié)點(diǎn)的高度差別較大，則滾動(dòng)條長(zhǎng)度可能會(huì)不準(zhǔn)確
3. 使用 worklet 函數(shù)需要開啟開發(fā)者工具 "將 JS 編譯成 ES5" 或 "編譯 worklet 函數(shù)" 選項(xiàng)。

# 通用屬性

# Skyline 特有屬性

# WebView 特有屬性

# Bug & Tip

1. tip: 基礎(chǔ)庫(kù) 2.4.0以下不支持嵌套textarea、map、canvas、video 組件
2. tip: scroll-into-view 的優(yōu)先級(jí)高于 scroll-top
3. tip: 在滾動(dòng) scroll-view 時(shí)會(huì)阻止頁(yè)面回彈，所以在 scroll-view 中滾動(dòng)，是無(wú)法觸發(fā) onPullDownRefresh
4. tip: 若要使用下拉刷新，請(qǐng)使用頁(yè)面的滾動(dòng)，而不是 scroll-view ，這樣也能通過(guò)點(diǎn)擊頂部狀態(tài)欄回到頁(yè)面頂部
5. tip: scroll-view 自定義下拉刷新節(jié)點(diǎn)需要聲明為 slot="refresher"，可參考自定義下拉刷新示例
6. tip: scroll-view 自定義下拉刷新可以結(jié)合 WXS 事件響應(yīng) 開發(fā)交互動(dòng)畫

# bind:refresherstatuschange

返回值 evt.detail = { status, dy }，其中 status 的枚舉狀態(tài)如下

export enum RefreshStatus {
  // 空閑
  Idle,
  // 超過(guò)下拉刷新閾值，同 bind:refresherwillRefresh 觸發(fā)時(shí)機(jī)
  CanRefresh,
  // 下拉刷新，同 bind:refresherrefresh 觸發(fā)時(shí)機(jī)
  Refreshing,
  // 下拉刷新完成，同 bind:refresherrestore 觸發(fā)時(shí)機(jī)
  Completed,
  // 下拉刷新失敗
  Failed,
  // 超過(guò)下拉二級(jí)閾值
  CanTwoLevel,
  // 開始打開二級(jí)
  TwoLevelOpening,
  // 打開二級(jí)
  TwoLeveling,
  // 開始關(guān)閉二級(jí)
  TwoLevelClosing,
}

# 下拉二級(jí)

相關(guān)接口

• 觸發(fā)下拉刷新 ScrollViewContext.triggerRefresh
• 關(guān)閉下拉刷新 ScrollViewContext.closeRefresh
• 觸發(fā)下拉二級(jí) ScrollViewContext.triggerTwoLevel
• 關(guān)閉下拉二級(jí) ScrollViewContext.closeTwoLevel

下拉二級(jí)是下拉刷新的一部份，需同時(shí)開啟 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. 當(dāng)用戶下拉 scroll-view 至 refresher-threshold 時(shí)松手觸發(fā)下拉刷新
2. 繼續(xù)下拉至 refresher-two-level-threshold 松手觸發(fā)下拉二級(jí)
3. 開啟 refresher-two-level-scroll-enabled 后，二級(jí)頁(yè)面可以滑動(dòng)關(guān)閉，是否關(guān)閉的閾值由 refresher-two-level-close-threshold 指定
4. 下拉刷新和下拉二級(jí)的展示區(qū)域由 slot=refresher 定義，開發(fā)者可根據(jù) refresherstatuschange 判定當(dāng)前階段，展示不同內(nèi)容，例如

buildText(status: RefreshStatus) {
  switch (status) {
    case RefreshStatus.Idle:
      return '下拉刷新'
    case RefreshStatus.CanRefresh:
      return '松手刷新，下拉進(jìn)入二樓'
    case RefreshStatus.Refreshing:
      return '正在刷新'
    case RefreshStatus.Completed:
      return '刷新成功'
    case RefreshStatus.Failed:
      return '刷新失敗'
    case RefreshStatus.CanTwoLevel:
      return '松手進(jìn)入二樓'
    default:
      return ''
  }
},

下拉二級(jí)示例代碼: 在開發(fā)者工具中預(yù)覽效果

# 嵌套模式

skyline 渲染模式下，當(dāng)存在兩個(gè) scroll-view 相互嵌套的場(chǎng)景時(shí)，兩者的滾動(dòng)不能很絲滑的進(jìn)行銜接，故可將外層 scroll-view 改成嵌套模式，這樣可以讓兩個(gè) scroll-view 的滾動(dòng)銜接起來(lái)。

<!-- 外層 scroll-view -->
<scroll-view
  type="nested"
  scroll-y
  refresher-enabled="{{true}}"
>
  <view slot="refresher">自定義 refresher</view>
  <nested-scroll-header><view>外層 scroll-vew 的節(jié)點(diǎn) 1</view></nested-scroll-header>
  <nested-scroll-header><view>外層 scroll-vew 的節(jié)點(diǎn) 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 的節(jié)點(diǎn) 1</view>
          <view>里層 scroll-vew 的節(jié)點(diǎn) 2</view>
        </scroll-view>
      </swiper-item>
      <swiper-item></swiper-item>
      <swiper-item></swiper-item>
    </swiper>
  </nested-scroll-body>
</scroll-view>

1. 外層 scroll-view 的子節(jié)點(diǎn)只支持 nested-scroll-header 和 nested-scroll-body 和自定義 refresher
2. 外層 scroll-view 的子節(jié)點(diǎn)中只能有一個(gè) nested-scroll-body
3. nested-scroll-header 和 nested-scroll-body 只能有一個(gè)子節(jié)點(diǎn)
4. nested-scroll-header 只能渲染在 nested-scroll-body 上面
5. 嵌套滾動(dòng)策略：當(dāng)向下滾動(dòng)時(shí)，先滾動(dòng)外層 scroll-view 再滾動(dòng)里層 scroll-view；當(dāng)向上滾動(dòng)時(shí)，先滾動(dòng)里層 scroll-view 再滾動(dòng)外層 scroll-view

嵌套模式示例代碼: 在開發(fā)者工具中預(yù)覽效果

# 列表構(gòu)造器

skyline 渲染模式下，如果列表項(xiàng)特別多的場(chǎng)景可以考慮使用列表構(gòu)造器，可以實(shí)現(xiàn)可回收列表，回收的范圍取決于 cache-extent 配置。默認(rèn)情況下列表項(xiàng)進(jìn)入視口時(shí)會(huì)被創(chuàng)建，而離開視口外則會(huì)被回收，即在屏的列表項(xiàng)才會(huì)被真正創(chuàng)建出來(lái)。

<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 必須設(shè)置成 custom 模式
2. 列表項(xiàng)默認(rèn)為定高模式，需要通過(guò) child-height 指定，所有列表項(xiàng)必須等高
3. 不定高模式下因?yàn)闊o(wú)法知道未創(chuàng)建的列表項(xiàng)高度，會(huì)存在滾動(dòng)條跳動(dòng)問(wèn)題
4. 默認(rèn)情況下不在視口中的列表項(xiàng)不會(huì)被創(chuàng)建。在滾動(dòng)過(guò)程中，會(huì)根據(jù) child-count 判斷需不需要?jiǎng)?chuàng)建/回收列表項(xiàng)，如果需要?jiǎng)t會(huì)進(jìn)行列表項(xiàng)的創(chuàng)建/回收，同時(shí)觸發(fā)對(duì)應(yīng)事件
5. 目前只支持縱向滾動(dòng)列表
6. 不支持 scroll-into-view

列表構(gòu)造器示例代碼: 在開發(fā)者工具中預(yù)覽效果

# 網(wǎng)格構(gòu)造器

網(wǎng)格構(gòu)造器和列表構(gòu)造器的不定高模式類似，可參考列表構(gòu)造器的使用方法和注意事項(xiàng)。

<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: [
      ...
    ]
  },
})

網(wǎng)格構(gòu)造器示例代碼: 在開發(fā)者工具中預(yù)覽效果

# 示例代碼

自定義下拉刷新示例代碼: 在開發(fā)者工具中預(yù)覽效果

在開發(fā)者工具中預(yù)覽效果