更新记录

1.0.0（2025-10-29） 下载此版本

Features

• 支持下拉刷新和上拉加载
• 自定义下拉刷新器，内置美观的 loading 动画
• 支持自定义刷新器插槽
• 支持虚拟滚动，处理大数据量场景
• 支持瀑布流布局
• 内置骨架屏，优化首屏体验
• 提供空态和错误态组件
• 数据完全由外部控制，灵活易用
• 全平台兼容（H5/App/小程序）

Performance

• 优化瀑布流布局算法，时间复杂度从 O(n×m) 降低到 O(n)，大幅提升性能
• 优化虚拟滚动计算，缓存 itemHeight 避免重复计算
• 优化 visibleItems 计算，减少对象展开和内存分配
• 添加滚动事件节流（16ms），优化滚动性能
• 优化 list watcher，避免不必要的瀑布流重新计算
• 为骨架屏动画添加 will-change 提示，优化动画性能
• 添加 beforeDestroy 钩子清理定时器，防止内存泄漏

平台兼容性

uni-app(3.6.12)

neo-zlist-pro

高性能长列表组件，支持下拉刷新、上拉加载、虚拟滚动、瀑布流布局等功能。

特性

• 下拉刷新 + 上拉加载
• 虚拟滚动（处理大数据量）
• 瀑布流布局
• 内置骨架屏
• 空态和错误态管理
• 数据完全由外部控制
• 样式灵活可定制
• 全平台兼容

兼容性

安装

在 HBuilderX 中右键 uni_modules 目录，选择 从插件市场导入，搜索 neo-zlist-pro 安装。

或者直接复制 neo-zlist-pro 目录到项目的 uni_modules 目录下。

快速开始

基础用法

<template>
  <neo-zlist-pro
    :list="list"
    :loading="loading"
    :finished="finished"
    @refresh="handleRefresh"
    @load-more="handleLoadMore"
  >
    <template #default="{ item }">
      <view class="item">{{ item.title }}</view>
    </template>
  </neo-zlist-pro>
</template>

<script>
export default {
  data() {
    return {
      list: [],
      loading: false,
      finished: false,
      page: 1
    }
  },
  mounted() {
    this.loadData()
  },
  methods: {
    async loadData(isRefresh = false) {
      if (isRefresh) {
        this.page = 1
        this.list = []
        this.finished = false
      }

      this.loading = true

      try {
        const res = await api.getList({ page: this.page, size: 20 })
        this.list = isRefresh ? res.data : [...this.list, ...res.data]
        this.page++

        // 判断是否已加载全部数据（在 page++ 之后）
        if (this.list.length >= res.total) {
          this.finished = true
        }
      } finally {
        this.loading = false
      }
    },
    handleRefresh() {
      this.loadData(true)
    },
    handleLoadMore() {
      if (!this.loading && !this.finished) {
        this.loadData()
      }
    }
  }
}
</script>

虚拟滚动

用于处理大量数据，只渲染可见区域的列表项。

<neo-zlist-pro
  :list="list"
  :virtual="true"
  :item-height="100"
  @load-more="handleLoadMore"
>
  <template #default="{ item }">
    <view class="item" style="height: 100rpx;">
      {{ item.title }}
    </view>
  </template>
</neo-zlist-pro>

注意：

• 必须设置 item-height（单位 rpx）
• 列表项必须固定高度

瀑布流布局

适用于图片流、商品列表等场景。

<neo-zlist-pro
  :list="list"
  :waterfall="true"
  :columns="2"
  :gap="20"
  @load-more="handleLoadMore"
>
  <template #default="{ item }">
    <view class="item">
      <image :src="item.image" mode="widthFix" />
      <text>{{ item.title }}</text>
    </view>
  </template>
</neo-zlist-pro>

空态、错误态和加载完成

使用内置组件或自定义插槽。

<neo-zlist-pro :list="list" :finished="finished" :error="error">
  <template #default="{ item }">
    <view>{{ item }}</view>
  </template>

  <!-- 自定义空态 -->
  <template #empty>
    <neo-empty-state type="search" title="搜索无结果" />
  </template>

  <!-- 自定义错误态 -->
  <template #error>
    <neo-error-state @retry="handleRetry" />
  </template>

  <!-- 自定义"没有更多了" -->
  <template #finished>
    <view class="custom-finished">
      <text>✓ 已加载全部内容</text>
    </view>
  </template>

  <!-- 自定义"加载中" -->
  <template #loading>
    <view class="custom-loading">
      <text>正在加载...</text>
    </view>
  </template>
</neo-zlist-pro>

自定义下拉刷新

组件内置了美观的下拉刷新动画，你也可以自定义。

<!-- 使用内置刷新动画（默认） -->
<neo-zlist-pro :list="list" @refresh="handleRefresh">
  <template #default="{ item }">
    <view>{{ item }}</view>
  </template>
</neo-zlist-pro>

<!-- 自定义刷新器 -->
<neo-zlist-pro :list="list" @refresh="handleRefresh">
  <template #default="{ item }">
    <view>{{ item }}</view>
  </template>

  <template #refresher="{ refreshing }">
    <view v-if="refreshing" class="my-refresher">
      <text>加载中...</text>
    </view>
  </template>
</neo-zlist-pro>

<!-- 使用原生刷新器 -->
<neo-zlist-pro 
  :list="list" 
  :use-custom-refresher="false"
  refresher-default-style="black"
  @refresh="handleRefresh"
>
  <template #default="{ item }">
    <view>{{ item }}</view>
  </template>
</neo-zlist-pro>

API

neo-zlist-pro Props

neo-zlist-pro Events

neo-zlist-pro Slots

neo-zlist-pro Methods

neo-empty-state Props

neo-error-state Props

neo-error-state Events

使用建议

1. 数据管理：组件不处理数据请求，你需要在父组件中管理数据和状态
2. 加载状态：首次加载（list 为空）显示骨架屏，后续加载（list 有数据）显示"加载中"提示
3. finished 设置时机：⚠️ 重要！在数据加载完成后、loading=false 之前设置 finished，确保最后一页也能显示"加载中"
4. 虚拟滚动：适用于 1000+ 条数据的场景，列表项必须固定高度
5. 瀑布流：适用于图片流、商品列表，布局会自动优化
6. 自定义刷新器：建议使用 v-if="refreshing" 只在刷新时显示内容，避免遮挡列表
7. 样式定制：列表项样式完全由插槽控制，可灵活定制

常见问题

1. 下拉刷新没反应？

确保正确处理 @refresh 事件，并在数据加载完成后更新 loading 和 list。

2. 虚拟滚动列表项高度不一致？

虚拟滚动要求列表项高度固定，如果高度不一致请使用普通模式。

3. 瀑布流图片显示不全？

使用 mode="widthFix" 让图片自适应宽度。

4. 如何自定义空态样式？

使用 #empty 插槽自定义空态内容。

许可

MIT License

更新日志

见 changelog.md