coolui-scroller

Appearance

当前文档uni-app 版coolui-scroller-uni 改用 原生微信小程序版 →

Scroller 滚动容器 ​

<coolui-scroller> 是列表能力的底座：下拉刷新 / 上拉加载 / 空列表 / 回到顶部都通过它的插槽接入。

对应原生微信小程序版：Scroller 滚动组件；写法差异见与原生微信小程序版的差异。

代码演示 ​

vue
<template>
  <coolui-scroller
    :isEmpty="isEmpty"
    background="#f2f2f2"
    @refresh="refresh"
    @loadmore="loadmore"
  >
    <!-- 下拉刷新 -->
    <template #refresh>
      <coolui-scroller-refresh type="default" :config="refreshSetting" />
    </template>

    <!-- 列表内容 -->
    <coolui-scroller-item v-for="(item, index) in list" :key="index">
      <view class="item">{{ item.title }}</view>
    </coolui-scroller-item>

    <!-- 空列表 -->
    <template #empty>
      <coolui-scroller-empty emptyImg="/static/empty.png" emptyText="暂无内容" />
    </template>

    <!-- 加载更多 -->
    <template #loadmore>
      <coolui-scroller-loadmore :status="status" />
    </template>
  </coolui-scroller>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const isEmpty = ref(false)
const list = ref<{ title: string }[]>([])
const status = ref('more')
const refreshSetting = ref({
  height: 50,
  background: { color: '#f2f2f2', height: 120 },
})

let page = 1

// @refresh / @loadmore 需要返回 promise，返回前不要 resolve，否则动画会提前收起
function getList(p: number) {
  page = p
  return new Promise<void>((resolve) => {
    // 请求数据，更新 list / isEmpty / status 之后再 resolve()
    resolve()
  })
}

function refresh() {
  return getList(1)
}

function loadmore() {
  return getList(page + 1)
}
</script>
vue
<template>
  <coolui-scroller
    :isEmpty="isEmpty"
    background="#f2f2f2"
    @refresh="refresh"
    @loadmore="loadmore"
  >
    <!-- 下拉刷新 -->
    <template #refresh>
      <coolui-scroller-refresh type="default" :config="refreshSetting" />
    </template>

    <!-- 列表内容 -->
    <coolui-scroller-item v-for="(item, index) in list" :key="index">
      <view class="item">{{ item.title }}</view>
    </coolui-scroller-item>

    <!-- 空列表 -->
    <template #empty>
      <coolui-scroller-empty emptyImg="/static/empty.png" emptyText="暂无内容" />
    </template>

    <!-- 加载更多 -->
    <template #loadmore>
      <coolui-scroller-loadmore :status="status" />
    </template>
  </coolui-scroller>
</template>

<script>
export default {
  data() {
    return {
      isEmpty: false,
      list: [],
      status: 'more',
      page: 1,
      refreshSetting: { height: 50, background: { color: '#f2f2f2', height: 120 } },
    }
  },
  methods: {
    // @refresh / @loadmore 需要返回 promise，返回前不要 resolve，否则动画会提前收起
    getList(page) {
      this.page = page
      return new Promise((resolve) => {
        // 请求数据，更新 list / isEmpty / status 之后再 resolve()
        resolve()
      })
    },
    refresh() {
      return this.getList(1)
    },
    loadmore() {
      return this.getList(this.page + 1)
    },
  },
}
</script>

属性 ​

属性说明类型默认值
isEmpty数据为空态，渲染 empty 插槽Booleanfalse
background背景色（保留字段，组件内部未使用，与原生一致）String#f2f2f2
isBackBtn兼容字段，回到顶部按钮的显隐实际由 back-to-top 组件注册决定Booleanfalse
enableFlex透传给 scroll-view 的 enable-flexBooleanfalse
toView滚动到指定元素 id（scroll-into-view）String''
top滚动位置，支持 v-model:topNumber0
animation滚动是否带过渡动画Booleantrue

事件 ​

事件说明参数
refresh下拉刷新触发—
loadmore上拉触底触发—
restore刷新流程结束（回弹完成）—
contentHeight内容高度变化height: number
update:top滚动位置变化（配 v-model:top）top: number
scroll滚动中，常用于长列表event（原始滚动事件对象）

插槽 ​

插槽说明
header列表顶部（不参与滚动区域）
refresh下拉刷新组件位置
默认列表内容
empty空列表内容，isEmpty 为 true 时显示
loadmore加载更多位置
backToTop回到顶部按钮位置

与原生版的差异 ​

  • 组件通信由原生 relations 改为 provide/inject，父子层级不要打乱；
  • 新增 v-model:top（update:top 事件），原生没有；
  • scroll 事件透传原始滚动事件对象，原生只透出 { scrollTop }。

相关 ​