更新记录

2.0.1（2025-11-26）

更新

• uni-app x 全面支持: 核心代码使用 UTS 重构，完美支持 Android/iOS/Web 平台
• 性能飞跃: 基于原生渲染，支持万级数据流畅滚动，内存占用更低
• 原生体验: 针对移动端深度优化的惯性滚动和回弹效果

新增特性

• 虚拟列表: 内置高性能虚拟滚动引擎，轻松应对海量数据
• 索引导航: 支持字母索引快速定位（iOS/Web 支持滚动高亮，Android 支持点击跳转）
• 高度定制: 支持插槽自定义列表项、加载动画、空状态等
• 类型安全: 提供完整的 TypeScript 类型定义，开发体验更佳

优化修复

• 修复了 Android 平台下的部分兼容性问题
• 优化了滚动条和回到顶部按钮的交互体验
• 更新了详细的使用文档和最佳实践指南

2.0.0（2025-11-26）

重大更新

1.1.0（2025-10-24）

• ✅ 修复了所有 uvue 文件的兼容性问题
• ✅ 移除不支持的 validator 验证器
• ✅ 优化 props 修改机制
• ✅ 替换 loading-indicator 为跨平台兼容方案
• ✅ 添加完整的 uni-app x 使用文档

平台兼容性

uni-app(3.6.14)

uni-app x(3.6.14)

其他

hy-scroll-plus

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

✨ 特性

• 🚀 高性能虚拟滚动 - 万级数据流畅滚动不卡顿
• 🔍 智能索引导航 - 支持字母索引快速定位
• 🔄 下拉刷新/上拉加载 - 自定义动画和回调逻辑
• 📊 滚动指示器 - 可视化显示滚动进度
• ⬆️ 回到顶部 - 智能显示隐藏动画
• ✨ UTS: 提供完整的 UTS 类型定义支持 Vue2、Vue3、nvue、uni-app x
• 📱 原生体验 - 针对移动端深度优化
• ⚡ uni-app x - 完全兼容 uni-app x,支持 .uvue 语法
• 🔧 高度可定制 - 丰富的配置选项和插槽
• ⚠️ 注意 - Android 平台暂不支持索引高亮功能（不影响点击跳转）

// Vue2/Vue3 项目
import HyScrollPlus from '@/uni_modules/hy-scroll-plus/components/hy-scroll-plus/hy-scroll-plus.vue';

// uni-app x 项目
import HyScrollPlus from '@/uni_modules/hy-scroll-plus/components/hy-scroll-plus/hy-scroll-plus.uvue';

export default {
  components: {
    HyScrollPlus
  }
}

📦 快速开始

基础用法

<template>
  <hy-scroll-plus 
    :data="listData"
    height="100vh"
    @refresh="handleRefresh"
    @loadMore="handleLoadMore"
    @itemClick="handleItemClick"
  >
    <template #item="{ item, index }">
      <view class="list-item">
        <text>{{ item.name }}</text>
      </view>
    </template>
  </hy-scroll-plus>
</template>

<script>
export default {
  data() {
    return {
      listData: []
    }
  },
  methods: {
    handleRefresh(callback) {
      // 模拟刷新
      setTimeout(() => {
        this.listData = [...newData];
        callback(); // 调用回调结束刷新
      }, 1000);
    },
    handleLoadMore(callback) {
      // 加载更多数据
      setTimeout(() => {
        this.listData.push(...moreData);
        callback(); // 调用回调结束加载
      }, 1000);
    },
    handleItemClick(item, index) {
      console.log('点击了:', item, index);
    }
  }
}
</script>

📚 完整文档

• API 文档 - 完整的 API 参考
• 最佳实践指南 - 性能优化和使用技巧
• UTS 类型定义 - UTS 类型支持
• 更新日志 - 版本更新记录

🔧 API 文档

Props 属性

Events 事件

Methods 方法

通过 ref 调用组件方法:

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

// 滚动到顶部
this.$refs.scrollRef.scrollToTop();

// 滚动到底部
this.$refs.scrollRef.scrollToBottom();

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

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

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

// 获取当前滚动位置
const scrollTop = this.$refs.scrollRef.getScrollTop();

Slots 插槽

🎯 高级用法

1. 虚拟滚动大数据列表

<hy-scroll-plus
  :data="bigData"
  height="100vh"
  :virtual-scroll="true"
  :item-height="80"
  :buffer-size="10"
/>

2. 自定义下拉刷新动画

<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>

3. 索引导航通讯录

<hy-scroll-plus
  :data="contacts"
  :show-index-list="true"
  @indexChange="handleIndexChange"
>
  <template #item="{ item }">
    <view class="contact-item">
      <image :src="item.avatar" />
      <text>{{ item.name }}</text>
    </view>
  </template>
</hy-scroll-plus>

4. 使用 SDK 工具函数

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

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

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

// 平滑滚动
await hyScrollPlusSDK.scrollTo(
  this.$refs.scrollView, 
  500,              // 目标位置
  300,              // 动画时长
  'easeOutCubic'    // 缓动函数
);

// 数据优化工具
import { DataOptimizer } from '@/uni_modules/hy-scroll-plus/js_sdk/modules/performance.uts';

// 数据去重
const uniqueData = DataOptimizer.deduplicate(data, 'id');

// 数据搜索
const results = DataOptimizer.search(data, 'keyword', ['name', 'title']);

// 数据分页
const pageData = DataOptimizer.paginate(data, 1, 20);

5. 性能监控

import { PerformanceMonitor } from '@/uni_modules/hy-scroll-plus/js_sdk/modules/performance.uts';

const monitor = new PerformanceMonitor();

monitor.addObserver((metrics) => {
  console.log('性能指标:', metrics);

  if (metrics.performance < 60) {
    const suggestions = monitor.getSuggestions();
    console.log('优化建议:', suggestions);
  }
});

💪 核心优势

1. 极致性能

• ⚡ 虚拟滚动技术,万级数据流畅滚动
• 🚀 首屏渲染速度提升 16.7倍
• 💾 内存占用降低 80%
• 📈 滚动帧率稳定在 55-60 FPS

2. 功能完整

• ✅ 下拉刷新 + 上拉加载
• ✅ 索引导航通讯录
• ✅ 滚动进度指示器
• ✅ 回到顶部按钮
• ✅ 自定义插槽
• ✅ 完整的事件回调

3. 开发友好

• 📝 完整的 UTS 类型定义
• 📚 详细的 API 文档和最佳实践指南
• 🛠️ 丰富的 SDK 工具函数
• 🎯 开箱即用,零配置

4. 多端兼容

• ✅ uni-app Vue2/Vue3
• ✅ uni-app x (Android/iOS/Web)
• ✅ nvue (兼容性支持)
• ✅ H5

🎨 使用场景

• 📱 商品列表 - 电商应用的商品展示
• 👥 通讯录 - 带索引导航的联系人列表
• 💬 聊天消息 - 支持历史记录加载
• 📰 新闻资讯 - 无限滚动加载
• 📋 表单列表 - 数据填报和审批
• 🎵 音乐列表 - 歌曲播放列表
• 📚 图书馆 - 书籍检索和浏览

🔥 性能对比

测试环境

• 设备: iPhone 12 Pro
• 数据量: 10000 条
• 列表项高度: 80px

测试结果

❓ 常见问题

Q: 如何选择是否开启虚拟滚动?

A: 数据量 > 100条时建议开启。虚拟滚动会显著提升性能,但要求列表项高度一致。

Q: uni-app x 完全支持吗?

A: 是的!已经全面适配 uni-app x,使用 .uvue 文件即可。

Q: 支持动态高度的列表项吗?

A: 虚拟滚动模式要求固定高度。如需动态高度,可关闭虚拟滚动(virtual-scroll="false")。

Q: 如何实现下拉刷新?

A: 监听 @refresh 事件,数据加载完成后调用 callback() 即可。

Q: 性能不理想怎么办?

A:

1. 确认已开启虚拟滚动
2. 简化列表项 DOM 结构
3. 启用图片懒加载
4. 使用 PerformanceMonitor 查看性能指标和优化建议

📞 联系方式

• 插件市场: hy-scroll-plus
• 问题反馈: 通过插件市场留言或者uni-im