更新记录

1.0.1（2025-07-10） 下载此版本

更新操作使用说明文档

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

uni滚动列表：支持自动加载、上拉加载、下拉刷新，高度可自定义，兼容多端。

平台兼容性

uni-app(4.45)

uni-app x(4.51)

其他

HuimayunScroll 组件使用文档

概述

HuimayunScroll 是一个功能强大的滚动组件，基于 mescroll 封装，支持下拉刷新、上拉加载、标签页切换、空状态显示等功能。

安装与引入

1. 组件引入

<script>
import HuimayunScroll from "@/uni_modules/huimayun-scroll/components/huimayun-scroll/huimayun-scroll.vue";

export default {
  components: {
    HuimayunScroll,
  },
};
</script>

2. 基础使用

<template>
  <huimayun-scroll @down="handleRefresh" @up="handleLoadmore">
    <view v-for="item in dataList" :key="item.id" class="list-item">
      {{ item.title }}
    </view>
  </huimayun-scroll>
</template>

属性配置

标签页相关

布局相关

功能配置

事件

使用示例

1. 基础滚动列表

<template>
  <huimayun-scroll @down="handleRefresh" @up="handleLoadmore">
    <view v-for="item in dataList" :key="item.id" class="list-item">
      <text>{{ item.title }}</text>
    </view>
  </huimayun-scroll>
</template>

<script>
export default {
  data() {
    return {
      dataList: [],
    };
  },
  methods: {
    // 下拉刷新
    handleRefresh(mescroll) {
      // 模拟网络请求
      setTimeout(() => {
        this.dataList = this.generateData(20);
        mescroll.endSuccess();
      }, 1000);
    },

    // 上拉加载
    handleLoadmore(mescroll) {
      // 模拟网络请求
      setTimeout(() => {
        const newData = this.generateData(10);
        this.dataList = this.dataList.concat(newData);
        mescroll.endSuccess(newData.length);
      }, 1000);
    },

    generateData(count) {
      const data = [];
      for (let i = 0; i < count; i++) {
        data.push({
          id: Date.now() + i,
          title: `数据项 ${i + 1}`,
        });
      }
      return data;
    },
  },
};
</script>

2. 带标签页的滚动列表

<template>
  <huimayun-scroll
    :tabs="tabs"
    :current-tab="currentTab"
    :show-tab-count="true"
    @down="handleRefresh"
    @up="handleLoadmore"
    @update:currentTab="handleTabChange"
  >
    <view v-for="item in filteredData" :key="item.id" class="list-item">
      <text>{{ item.title }}</text>
      <text class="status">{{ item.status }}</text>
    </view>
  </huimayun-scroll>
</template>

<script>
export default {
  data() {
    return {
      tabs: [
        { value: "all", label: "全部", count: 0 },
        { value: "active", label: "活跃", count: 0 },
        { value: "pending", label: "待处理", count: 0 },
        { value: "completed", label: "已完成", count: 0 },
      ],
      currentTab: "all",
      dataList: [],
    };
  },

  computed: {
    filteredData() {
      if (this.currentTab === "all") {
        return this.dataList;
      }
      return this.dataList.filter((item) => item.status === this.currentTab);
    },
  },

  methods: {
    handleTabChange(tab) {
      this.currentTab = tab;
      // 切换标签时重新加载数据
      this.loadData();
    },

    updateTabCounts() {
      const counts = {
        all: this.dataList.length,
        active: 0,
        pending: 0,
        completed: 0,
      };

      this.dataList.forEach((item) => {
        if (counts.hasOwnProperty(item.status)) {
          counts[item.status]++;
        }
      });

      this.tabs.forEach((tab) => {
        tab.count = counts[tab.value] || 0;
      });
    },
  },
};
</script>

3. 自定义配置

<template>
  <huimayun-scroll
    :down="downConfig"
    :up="upConfig"
    :empty="emptyConfig"
    :back-to-top="backToTopConfig"
    @down="handleRefresh"
    @up="handleLoadmore"
  >
    <view v-for="item in dataList" :key="item.id" class="list-item">
      {{ item.title }}
    </view>

    <!-- 自定义空状态 -->
    <template #empty>
      <view class="custom-empty">
        <image src="/static/empty.png" class="empty-icon"></image>
        <text class="empty-text">暂无数据</text>
      </view>
    </template>
  </huimayun-scroll>
</template>

<script>
export default {
  data() {
    return {
      dataList: [],

      // 下拉刷新配置
      downConfig: {
        use: true,
        auto: false,
        textInOffset: "下拉刷新",
        textOutOffset: "释放更新",
        textLoading: "加载中...",
        textSuccess: "刷新成功",
        bgColor: "#fff",
      },

      // 上拉加载配置
      upConfig: {
        use: true,
        auto: true,
        page: {
          num: 0,
          size: 10,
        },
        noMoreSize: 5,
        offset: 100,
        textLoading: "加载中...",
        textNoMore: "-- END --",
      },

      // 空状态配置
      emptyConfig: {
        title: "暂无数据",
        description: "当前没有可显示的内容",
        image: "/static/empty.png",
      },

      // 回到顶部配置
      backToTopConfig: {
        show: true,
        offset: 1000,
      },
    };
  },
};
</script>

方法调用

组件实例方法

<template>
  <huimayun-scroll ref="scrollRef">
    <!-- 内容 -->
  </huimayun-scroll>
</template>

<script>
export default {
  methods: {
    // 手动结束刷新
    endRefresh() {
      this.$refs.scrollRef.endSuccess();
    },

    // 手动结束加载
    endLoad(dataSize) {
      this.$refs.scrollRef.endSuccess(dataSize);
    },

    // 重置上拉加载
    resetLoad() {
      this.$refs.scrollRef.resetUpScroll();
    },

    // 滚动到顶部
    scrollToTop() {
      this.$refs.scrollRef.scrollToTop();
    },
  },
};
</script>

样式自定义

标签页样式

/* 自定义标签页样式 */
.huimayun-scroll ::v-deep .tab-menu {
  background: #f8f8f8;
  border-bottom: 1px solid #e0e0e0;
}

.huimayun-scroll ::v-deep .tab-item {
  padding: 15rpx 30rpx;
  font-size: 28rpx;
}

.huimayun-scroll ::v-deep .tab-item.active {
  color: #007aff;
  font-weight: 500;
}

.huimayun-scroll ::v-deep .tab-count {
  background: rgba(0, 122, 255, 0.1);
  color: #007aff;
}

空状态样式

.custom-empty {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 100rpx 40rpx;
}

.empty-icon {
  width: 200rpx;
  height: 200rpx;
  margin-bottom: 30rpx;
}

.empty-text {
  font-size: 28rpx;
  color: #999;
}

注意事项

1. 数据更新：在数据变化后记得调用 endSuccess() 或 endErr() 方法
2. 标签页数量：如果使用标签页功能，需要手动更新 count 字段
3. 内存优化：大量数据时建议启用虚拟滚动模式
4. 兼容性：组件基于 uni-app，支持多端运行
5. 防抖处理：组件内置防抖机制，避免频繁触发刷新和加载

常见问题

Q: 如何禁用下拉刷新？

A: 设置 :down="{ use: false }"

Q: 如何自定义加载文案？

A: 通过 down 和 up 配置对象的 textLoading 等属性

Q: 标签页数量不更新？

A: 需要手动更新 tabs 数组中每个对象的 count 属性

Q: 如何监听滚动位置？

A: 监听 @scroll 事件，通过 event.detail.scrollTop 获取位置