更新记录

1.0.0（2025-09-26） 下载此版本

新增功能

• ✨ 核心功能: 实现虚拟滚动技术，支持万级数据流畅滚动
• ✨ 索引列表: 添加字母索引导航，支持快速定位
• ✨ 下拉刷新: 实现自定义下拉刷新动画和逻辑
• ✨ 上拉加载: 添加自动检测底部加载更多功能
• ✨ 滚动指示器: 可视化显示滚动进度和位置
• ✨ 回到顶部: 智能显示/隐藏回到顶部按钮
• ✨ 多端兼容: 支持 Vue2、Vue3、nvue 全平台
• ✨ TypeScript: 提供完整的类型定义支持

平台兼容性

uni-app(3.6.5)

uni-app x(3.6.5)

其他

hy-scroll-plus

hy-scroll-plus 是一个功能强大的滚动容器组件，专为 uni-app 应用设计。它集成了虚拟滚动、索引列表、下拉刷新、上拉加载等先进特性，能够高效处理海量数据，提供流畅的用户体验。

✨ 特性

• 🚀 高性能虚拟滚动 - 万级数据流畅滚动不卡顿
• 🔍 智能索引导航 - 支持字母索引快速定位
• 🔄 下拉刷新/上拉加载 - 自定义动画和回调逻辑
• 📊 滚动指示器 - 可视化显示滚动进度
• ⬆️ 回到顶部 - 智能显示隐藏动画
• 🎯 多端兼容 - 完美支持 Vue2、Vue3、nvue
• 📱 原生体验 - 针对移动端深度优化
• 🔧 高度可定制 - 丰富的配置选项和插槽

import HyScrollPlus from '@/uni_modules/hy-scroll-plus/components/hy-scroll-plus/hy-scroll-plus.vue';

export default {
  components: {
    HyScrollPlus
  }
}

🔧 API 文档

Props 属性

属性名             类型      默认值     说明
data                Array   []          列表数据源
height              String  '100%'      容器高度
virtualScroll       Boolean true        是否开启虚拟滚动
pullToRefresh       Boolean true        是否开启下拉刷新
loadMore            Boolean true        是否开启上拉加载
showBackTop         Boolean true        是否显示回到顶部按钮
showIndexList       Boolean false       是否显示索引列表
showScrollIndicator Boolean true        是否显示滚动指示器
emptyText           String  '暂无数据'  空状态提示文本

Events 事件

事件名     参数                       说明
refresh     callback: Function      下拉刷新事件
loadMore    callback: Function      上拉加载更多事件
scroll      { scrollTop: Number }   滚动事件
itemClick   (item, index)           列表项点击事件
indexChange (char: String)          索引变化事件

Methods 方法

通过 ref 调用组件方法：

// 滚动到指定位置
this.$refs.scrollRef.scrollTo(0, 300);

// 开始刷新
this.$refs.scrollRef.startRefresh();

// 结束刷新
this.$refs.scrollRef.finishRefresh();

// 滚动到指定元素
this.$refs.scrollRef.scrollToElement('.item-100', 50);

Slots 插槽

插槽名 作用域              说明
item    { item, index }     自定义列表项渲染
refresh { progress, state } 自定义下拉刷新动画
empty   -                   自定义空状态显示

🎯 高级用法

自定义下拉刷新动画

<template>
  <hy-scroll-plus
    :data="listData"
    @refresh="onRefresh"
  >
    <template #refresh="{ progress, state }">
      <view class="custom-refresh">
        <view class="progress-circle" :style="{ transform: `rotate(${progress * 360}deg)` }">
          🔄
        </view>
        <text>{{ getRefreshText(state) }}</text>
      </view>
    </template>
  </hy-scroll-plus>
</template>

使用 SDK 工具函数

import hyScrollPlusSDK from '@/uni_modules/hy-scroll-plus/js_sdk/index.js';

// 生成索引数据
const indexData = hyScrollPlusSDK.generateIndexData(contactList, 'name');

// 使用防抖函数
const debouncedSearch = hyScrollPlusSDK.debounce(this.search, 300);

// 平滑滚动
hyScrollPlusSDK.scrollTo(this.$refs.scrollView, 500, 1000, 'easeOutCubic');