@tanzhenxing/zx-scroll v1.0.10

ZX-Scroll 增强滚动组件

一个基于 uni-app scroll-view 的增强滚动组件，支持更多自定义功能和性能优化。

✨ 特性

• 🚀 高性能: 支持虚拟列表、节流防抖等性能优化
• 🎨 丰富功能: 下拉刷新、上拉加载、自动滚动、返回顶部
• 📱 跨平台: 支持 H5、小程序、App 等多端
• 🎯 易用性: Vue3 Composition API，支持 JavaScript 开发
• 🔧 可定制: 丰富的配置选项和插槽支持
• ♿ 无障碍: 支持深色模式、高对比度、减少动画等

📦 安装

将 zx-scroll 文件夹复制到你的项目组件目录中。

🚀 快速开始

基础用法

<template>
  <zx-scroll height="400rpx" :show-scrollbar="true">
    <view v-for="item in list" :key="item.id" class="item">
      {{ item.text }}
    </view>
  </zx-scroll>
</template>

<script setup>
import { ref } from 'vue'

const list = ref([
  { id: 1, text: '列表项 1' },
  { id: 2, text: '列表项 2' },
  // ...
])
</script>

水平滚动

<template>
  <zx-scroll direction="x" height="200rpx">
    <view v-for="item in list" :key="item.id" class="horizontal-item">
      {{ item.text }}
    </view>
  </zx-scroll>
</template>

下拉刷新

<template>
  <zx-scroll
    height="400rpx"
    :refresher-enabled="true"
    :refresher-triggered="refreshTriggered"
    @refresherrefresh="onRefresh"
  >
    <view v-for="item in list" :key="item.id" class="item">
      {{ item.text }}
    </view>
  </zx-scroll>
</template>

<script setup>
import { ref } from 'vue'

const refreshTriggered = ref(false)

const onRefresh = () => {
  refreshTriggered.value = true
  // 模拟刷新
  setTimeout(() => {
    refreshTriggered.value = false
  }, 1500)
}
</script>

加载更多

<template>
  <zx-scroll
    height="400rpx"
    :show-load-more="true"
    :is-loading="isLoading"
    :no-more="noMore"
    @loadMore="onLoadMore"
  >
    <view v-for="item in list" :key="item.id" class="item">
      {{ item.text }}
    </view>
  </zx-scroll>
</template>

<script setup>
import { ref } from 'vue'

const isLoading = ref(false)
const noMore = ref(false)

const onLoadMore = () => {
  if (isLoading.value || noMore.value) return
  
  isLoading.value = true
  // 模拟加载
  setTimeout(() => {
    // 加载数据...
    isLoading.value = false
  }, 1000)
}
</script>

虚拟列表

<template>
  <zx-scroll
    height="400rpx"
    :enable-virtual-list="true"
    :virtual-list-source="virtualData"
    :virtual-item-height="80"
    :virtual-buffer="5"
  >
    <template #virtual-item="{ item, index }">
      <view class="virtual-item">
        <text>{{ index }}: {{ item.title }}</text>
      </view>
    </template>
  </zx-scroll>
</template>

<script setup>
import { ref } from 'vue'

const virtualData = ref(
  Array.from({ length: 10000 }, (_, i) => ({
    id: i,
    title: `虚拟列表项 ${i}`
  }))
)
</script>

自动滚动

<template>
  <zx-scroll
    height="300rpx"
    :auto-scroll-interval="2000"
    :auto-scroll-speed="50"
  >
    <view v-for="item in list" :key="item.id" class="item">
      {{ item.text }}
    </view>
  </zx-scroll>
</template>

📚 API

Props

Events

Slots

Methods

🎨 主题定制

组件支持通过 CSS 变量进行主题定制：

.zx-scroll-outer {
  --zx-scroll-loading-color: #3498db;
  --zx-scroll-text-color: #666;
  --zx-scroll-background-color: #fff;
  --zx-scroll-border-radius: 8rpx;
}

🔧 高级用法

自定义下拉刷新

<template>
  <zx-scroll
    :refresher-enabled="true"
    :custom-refresher="true"
    :refresher-triggered="refreshTriggered"
    @refresherrefresh="onRefresh"
  >
    <template #refresher="{ triggered }">
      <view class="custom-refresher">
        <view v-if="triggered" class="refreshing">刷新中...</view>
        <view v-else class="pull-down">下拉刷新</view>
      </view>
    </template>
    
    <!-- 内容 -->
  </zx-scroll>
</template>

自定义加载更多

<template>
  <zx-scroll :show-load-more="true" @loadMore="onLoadMore">
    <!-- 内容 -->
    
    <template #loadMore="{ loading, noMore }">
      <view class="custom-load-more">
        <view v-if="loading" class="loading">
          <text>加载中...</text>
        </view>
        <view v-else-if="noMore" class="no-more">
          <text>没有更多了</text>
        </view>
      </view>
    </template>
  </zx-scroll>
</template>

性能优化

<template>
  <!-- 大量数据时使用虚拟列表 -->
  <zx-scroll
    v-if="list.length > 100"
    :enable-virtual-list="true"
    :virtual-list-source="list"
    :virtual-item-height="80"
  >
    <template #virtual-item="{ item, index }">
      <ListItem :data="item" :index="index" />
    </template>
  </zx-scroll>
  
  <!-- 频繁滚动时使用节流 -->
  <zx-scroll
    v-else
    :throttle="true"
    :throttle-time="16"
    @scroll="onScroll"
  >
    <!-- 内容 -->
  </zx-scroll>
</template>

⚠️ 注意事项

1. 虚拟列表: 启用虚拟列表时，必须设置固定的 virtualItemHeight 或 virtualItemWidth
2. 性能: 对于大量数据推荐使用虚拟列表，对于频繁滚动推荐启用节流
3. 平台差异: 某些功能在不同平台上可能有差异，请参考 uni-app scroll-view 文档
4. 内存管理: 虚拟列表会自动回收不可见的 DOM 节点，有效控制内存使用

🆕 更新日志

v2.1.1

• 🔄 转换为纯 JavaScript 版本
• ❌ 移除 TypeScript 类型定义
• 📝 更新文档和示例

v2.1.0

• ✨ 新增虚拟列表支持
• ✨ 新增节流和防抖模式
• ✨ 新增自动滚动功能
• ✨ 新增拖拽滚动支持
• 🎨 改进样式和动画效果
• 🐛 修复若干已知问题
• 📝 完善文档和示例

v2.0.0

• 🎉 重构为 Vue3 Composition API
• ✨ 新增 JavaScript 支持
• ✨ 新增更多自定义选项
• 🎨 优化 UI 和交互体验

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系

如有问题或建议，请通过以下方式联系：

• Issue: 项目 Issues
• Email: your-email@example.com