更新记录

1.0.3（2026-09-15） 下载此版本

1. 【文档完善】新增 uni-app-x 兼容性说明文档：
   • 新增 UNIVERSAL_APP_X.md：详细说明 uni-app-x 兼容性
   • 明确说明 uni-app-x 的编译差异和已知限制
   • 提供 uni-app-x 专用配置建议
   • 包含性能测试数据和常见问题解答
   • 说明测试清单和反馈渠道
2. 【文档完善】新增完整示例页面：
   • 新增 example/VirtualListDemo.vue：包含完整的虚拟列表示例
   • 展示不同数据量（1千/1万/10万/50万）的性能测试
   • 提供数据配置、行高调整、缓冲区设置等功能
   • 包含性能指标实时监控
   • 展示快速操作（滚动到指定位置、刷新列表）
   • 美观的 UI 设计和详细的注释说明
3. 【代码优化】增强组件注释：
   • 在组件顶部添加详细的 uni-app-x 兼容性说明注释
   • 明确说明推荐做法和注意事项
   • 强调 height 和 itemHeight 的重要性
   • 提供兼容性问题解决方案

1.0.2（2026-09-14） 下载此版本

1. 新增对外方法 scrollToIndex(index) 和 refresh()，方便外部调用滚动定位或重测
2. 修复 itemHeight 为 0/负数/非数字 时整列总高度、translateY 计算异常的问题（统一 Number() 转换 + 边界兜底）
3. 修复 buffer 传入字符串时取不到正确缓冲数量的问题（统一 Number() 转换）
4. 修复 startIndex/endIndex 在值未变化时仍触发响应式更新的问题（仅在变化时赋值）
5. measureContainerHeight 增加 uni 不存在的容错，避免非 uni 环境报错
6. scroll-view 增加 :scroll-top="scrollTopSync" 与 :throttle="false"，解决部分平台抖动与节流导致的回滚跳变
7. 每个 item 增加 data-index 属性，便于调试与 e2e 自动化
8. 完善 keywords（补充 harmony/android/ios/uni-app/uni-app-x/virtual-list 等）

1.0.1（2026-03-24） 下载此版本

-新增：示例项目

平台兼容性

uni-app(4.45)

uni-app x(4.45)

zy-virtual-list（长列表虚拟滚动）

解决了什么问题

• 解决列表卡顿：10万+数据不再一次性渲染，滚动更流畅
• 内存占用显著下降：只渲染可视区域 + 缓冲区，常见场景内存占用可降低90%+
• 跨端通用：uni-app / uni-app x，适配鸿蒙Next + Android + iOS（同时兼容H5/小程序）

说明：虚拟列表的核心前提是 item高度固定（或可稳定估算）。如果你的 item 高度完全不固定，请先改成固定行高/卡片高度，或使用“分页/分组”的方式降低一次性渲染量。

安装

将插件导入项目后，会生成目录：uni_modules/zy-virtual-list/

组件使用：

• uni_modules/zy-virtual-list/components/zy-virtual-list/zy-virtual-list.vue

示例工程：

• uni_modules/zy-virtual-list/example/（可直接运行）

快速使用

<template>
  <zy-virtual-list
    :list="list"
    :item-height="itemHeight"
    :height="listHeight"
    :buffer="8"
    :lower-threshold="200"
    refresher-enabled
    @refresherrefresh="onRefresh"
    @loadmore="onLoadMore"
  >
    <template #default="{ item, index }">
      <view class="row">
        <text class="idx">{{ index }}</text>
        <text class="txt">{{ item.title }}</text>
      </view>
    </template>
  </zy-virtual-list>
</template>

<script>
export default {
  data() {
    return {
      list: [],
      itemHeight: 88, // px（建议固定）
      listHeight: 600 // px（建议明确给定，或用uni.getSystemInfoSync计算）
    }
  },
  methods: {
    async onRefresh() {
      // 下拉刷新：你可以重置数据
      // this.list = await fetchFirstPage()
      this.$refs?.vlist?.finishRefresh?.()
    },
    async onLoadMore() {
      // 上拉加载：你可以追加数据
      // this.list.push(...await fetchNextPage())
    }
  }
}
</script>

Props

• list: Array 数据源
• itemHeight: Number 单个item高度（px，必填，必须为正数）
• height: Number|String 容器高度（px 或 xxxpx，建议必填）
• buffer: Number 上下缓冲渲染条数（默认 6）
• lowerThreshold: Number 触底阈值（默认 80，单位px）
• refresherEnabled: Boolean 是否开启下拉刷新（默认 false）
• refresherTriggered: Boolean 外部控制刷新状态（可选）
• itemKey: String|Function item 唯一 key；字符串时按 item[itemKey] 取值，函数时 fn(item, index)

Events

• scroll: (e) => void 原始滚动事件
• refresherrefresh: 下拉刷新触发
• loadmore: 触底触发（上拉加载）
• itemclick: 点击 item 触发，回调 ({ item, index })

Methods（通过 ref 调用）

• scrollToIndex(index): 滚动到指定 index（自动边界裁剪）
• refresh(): 重新测量容器高度 + 重算可视范围（容器尺寸变化后调用）
• finishRefresh(): 当 refresherTriggered 未由外部控制时，主动结束刷新动效

使用示例：this.$refs.vlist.scrollToIndex(50)

性能建议（很关键）

• item高度固定：强烈建议固定 itemHeight
• 减少item内部复杂度：避免每条item里大量图片/阴影/复杂布局
• 把重逻辑放到数据层：不要在渲染时做复杂计算
• 合理设置buffer：一般 6~12 即可，过大反而增内存

License

MIT（见 license.md）