coolui-scroller

Appearance

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

Longlist 长列表窗口化（推荐） ​

<coolui-scroller-longlist> 是 uni-app 版新增的长列表容器（原生侧没有同名组件）：窗口外的内容折叠为上下占位块，渲染的节点数与总页数无关，数据量大时比整页占位更稳。

新项目建议用它；旧方案见 Page 长列表分页。

代码演示 ​

vue
<template>
  <coolui-scroller
    :isEmpty="isEmpty"
    background="#f2f2f2"
    @refresh="refresh"
    @loadmore="loadmore"
    @scroll="onScroll"
  >
    <template #refresh>
      <coolui-scroller-refresh type="default" :config="refreshSetting" />
    </template>

    <coolui-scroller-longlist :pages="list" :scroll-top="scrollTop">
      <template #page="{ items, pageIndex }">
        <coolui-scroller-item v-for="(item, index) in items" :key="index">
          <view class="item">{{ pageIndex }} - {{ item.title }}</view>
        </coolui-scroller-item>
      </template>
    </coolui-scroller-longlist>
  </coolui-scroller>
</template>

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

const isEmpty = ref(false)
// 二维数组：list[pageIndex] 是该页的 item 数组
const list = ref<{ title: string }[][]>([])
const scrollTop = ref(0)
const refreshSetting = ref({
  height: 50,
  background: { color: '#f2f2f2', height: 120 },
})

// 把 scroller 的滚动距离透传进来，组件据此判断窗口位置
function onScroll(e: { detail: { scrollTop: number } }) {
  scrollTop.value = e.detail.scrollTop
}

function refresh() {
  return Promise.resolve()
}

function loadmore() {
  return Promise.resolve()
}
</script>
vue
<template>
  <coolui-scroller
    :isEmpty="isEmpty"
    background="#f2f2f2"
    @refresh="refresh"
    @loadmore="loadmore"
    @scroll="onScroll"
  >
    <template #refresh>
      <coolui-scroller-refresh type="default" :config="refreshSetting" />
    </template>

    <coolui-scroller-longlist :pages="list" :scroll-top="scrollTop">
      <template #page="{ items, pageIndex }">
        <coolui-scroller-item v-for="(item, index) in items" :key="index">
          <view class="item">{{ pageIndex }} - {{ item.title }}</view>
        </coolui-scroller-item>
      </template>
    </coolui-scroller-longlist>
  </coolui-scroller>
</template>

<script>
export default {
  data() {
    return {
      isEmpty: false,
      list: [],      // 二维数组：pages[pageIndex] 是该页的 item 数组
      scrollTop: 0,
      refreshSetting: { height: 50, background: { color: '#f2f2f2', height: 120 } },
    }
  },
  methods: {
    // 把 scroller 的滚动距离透传进来，组件据此判断窗口位置
    onScroll(e) {
      this.scrollTop = e.detail.scrollTop
    },
    refresh() {
      return Promise.resolve()
    },
    loadmore() {
      return Promise.resolve()
    },
  },
}
</script>

属性 ​

属性说明类型默认值
pages分页数据，pages[pageIndex] 为该页的 item 数组Array[]
heights初始页高缓存（已测量过的页高，避免首次渲染跳动）Array[]
scrollTop当前滚动距离，由 scroller 的 @scroll 透传Number0
overscan窗口前后各多渲染几页Number1
estimateHeight未测量页的估算高度（0 时取已测量页的均值，兜底 300）Number0

插槽 ​

插槽说明
page作用域插槽，参数 { items, pageIndex }，渲染单页内容

使用要点 ​

  1. pages 是二维数组（页 → items），不是扁平列表；
  2. 必须把 coolui-scroller 的 @scroll 传给 scroll-top，否则无法判断窗口；
  3. 每页内容高度尽量一致，estimateHeight 与实际差得越多，滚动条长度就越不准；
  4. 与滚动容器嵌套层级保持不变即可，组件之间通过 provide/inject 通信。

相关 ​