coolui-scroller

Appearance

快速跳转

Scroller 滚动组件 ​

介绍 ​

Scroller 为 coolui-scroller 的地基。所以要使用 coolui-scroller 必须引入该组件。该组件将列表页面查分成如下各个区域:

示例图一
示例图二
示例图三

每个区域都提供了相应的组件或支持自定义。 如开启回到顶部按钮。该按钮默认执行 refresh 下拉的方法。

引入 ​

在app.json或index.json中引入组件

json
"usingComponents": {
  "scroller": "coolui-scroller/scroller/index"
}

代码演示 ​

html
<scroller
  background="{{background}}"
  isBackBtn="{{isBackBtn}}"
  isEmpty="{{isEmpty}}"
  bind:loadmore="loadmore"
  bind:refresh="refresh"
>
  <view slot="header">
    <!-- 头部区域，可增加搜索，分类切换等功能 -->
  </view>
  <!-- 下拉刷新组件，如果调用则开启下拉，不调用则不开启下拉，下拉配置详见下拉组件 -->
  <refresh slot="refresh" type="base" config="" />

  <!-- 中间列表内容区域，可使用长列表分页组件、列表项组件或自定义 -->
  <item wx:for="{{list}}">
    <!-- 我是列表项 -->
  </item>
  <view slot="loadmore">
    <!-- 加载更多区域，可使用加载更多组件或自定义 -->
  </view>
  <view slot="empty">
    <!-- 空列表区域，数据为空，将isEmpty设置为true时显示，可使用空组件或自定义 -->
  </view>
</scroller>
js
Page({
  data: {
    background: '#f2f2f2',
    isBackBtn: true, // 设置是否显示回到顶部按钮
    isEmpty: false, // 设置是否为空数据
    list: [], // 列表数据
  },
  loadmore() {
    // 上拉到底部，加载更多时执行，请实现分页+1，新数据加载的操作
  },
  refresh() {
    // 下拉到顶部，下拉刷新时执行，请实现清除列表数据，还原分页为初始值的操作
  },
})

如果不想使用里面子组件，像自定义里面内容可使用contentHeight来获取高度

html
<scroller
  background="{{background}}"
  isBackBtn="{{isBackBtn}}"
  isEmpty="{{isEmpty}}"
  bind:contentHeight="getHeight"
>
  <view slot="header">
    <!-- 头部区域，可增加搜索，分类切换等功能 -->
  </view>
  <!-- 下拉刷新组件，如果调用则开启下拉，不调用则不开启下拉，下拉配置详见下拉组件 -->
  <refresh slot="refresh" type="base" config="" />
  <view style="height: {{height}}px">
    <!-- 自定义的内容, 设置高度是方便里面flex布局等高度撑开计算等 -->
  </view
</scroller>
js
Page({
  data: {
    height: 0,
    background: '#f2f2f2',
    isBackBtn: true, // 设置是否显示回到顶部按钮
  },
  getHeight: function (res) {
    this.setData({
      height: res.detail,
    })
  },
})

配置 ​

参数说明类型默认值版本
type下拉样式类型,默认样式或插槽自定义，可设置 default 、base、 diy。default为小程序原版下拉样式。base为组件提供的基础样式。diy为开启完全自定义Stringdefault3.0.0
background自定义下拉背景颜色(如：#f2f2f2)，该设置本应该在下拉刷新组件中设置，但是小程序 scroll-view 动态设置 refresher-background 会出现下拉区域下沉 bug 所以在这里设置背景颜色。(3.1.0 废弃)String#f2f2f23.0.0~3.0.9
isBackBtn设置是否显示返回到顶部按钮，可设置true或false， true为开启Booleanfalse3.0.0~3.3.3
isEmpty设置是否显示空数据内容，可设置true或false， true为开启。如在空列表插槽中设置了内容则会显示出来Booleanfalse3.0.0
enableFlex设置是否开启 scroll-view 的 flex 模式，可设置true或false， true为开启。Booleanfalse3.0.9
top设置滚动到指定位置Number03.2.8
animation在设置滚动条位置时使用动画过渡 （同 scroll-with-animation）Booleantrue3.3.0

插槽 ​

名称说明可用组件版本
header头部插槽区域nav、search、sort3.x
refresh下拉刷新插槽位置，使用 refresh 组件时开启refresh3.x
loadmore加载更多插槽位置loadmore
empty空列表插槽位置，isEmpty 为 true 时显示empty3.x
backToTop回到顶部插槽backToTop3.3.4

事件 ​

名称用法说明返回参数版本
loadmorebindloadmore或bind:loadmore执行加载更多后触发，可执行更新列表无3.x
refreshbindrefresh或bind:refresh执行下拉刷新后触发，可执行更新列表无3.x
contentHeightbindcontentHeight或bind:contentHeight获取 scroller 中间内容区高度，不包括 header 部分,方便不使用 page、item 等组件需要自定义内容的时候使用返回 res,可用 res.detail 获取高度，单位 px3.2.7

方法 ​

名称用法说明返回参数版本
settriggered先获取组件实例：
const scroller = this.selectComponent('.elm-scroller');, 然后调用方法：
scroller.settriggered(false)		在 refresh 方法中执行，当刷新组件设置不自动回弹时，设置手动回弹，可增加 setTimeout 设置回弹时机。详见非自动回弹promise3.0.4

注意 ​

下拉刷新(除下拉二楼组件)与页面级的滚动下拉刷新效果会有冲突，建议关闭页面级的滚动，页面设置中需增加"disableScroll": true。

json
{
  "usingComponents": {
    "scroller": "coolui-scroller/scroller/index",
    "refresh": "coolui-scroller/refresh/index"
  },
  "disableScroll": true
}