更新记录

1.0.0（2026-04-02） 下载此版本

初版

平台兼容性

uni-app(5.06)

ZaVirtualList 组件使用说明

ZaVirtualList 是一个基于 scroll-view 的虚拟滚动容器，用于高性能渲染长列表，避免一次性渲染大量节点。

功能概览

• 支持任意长度数据（data）
• 支持统一高度（itemHeight）或每行可变高度（itemHeightArray）
• 滚动时动态更新可见片段（sliceList）
• 支持外部控制：setStartIndex(index), scrollIntoView(id)
• @scroll 事件透传当前 startIndex

安装

组件位于 components/Za-VirtualList/Za-VirtualList.vue，直接按需引入。

示例代码

<template>
  <ZaVirtualList
    :data="items"
    :itemHeight="60"
    :itemHeightArray="itemHeightArray"
    @scroll=""
    ref="virtualListRef"
  >
    <template #default="{data, index}">
        <view class="list-item">第{{index + 1}}项：名字：{{data.name}} 年龄：{{data.age}}</view>
    </template>
  </ZaVirtualList>
</template>

<script>
import ZaVirtualList from '@/components/Za-VirtualList/Za-VirtualList.vue'

export default {
  components: { ZaVirtualList },
  data() {
    const items = Array.from({ length: 1000 }, (_, i) => ({
        name: `name${i}`,
        age: i
    }))
    return {
      items,
      // 如果每行高度固定，则不需要设置itemHeightArray
      itemHeightArray: [50, 70, 50, ...]
    }
  },
  methods: {
    (event, startIndex) {
      console.log('scroll', event, startIndex)
    },
    goTo(pos) {
      this.$refs.virtualListRef.setStartIndex(pos)
    },
    scrollTo(id) {
      this.$refs.virtualListRef.scrollIntoView(id)
    }
  }
}
</script>

Props

• itemHeight (Number, default 50)
  • 统一高度模式，itemHeightArray 为空时生效。
• itemHeightArray (Array, default [])
  • 逐项高度模式，优先于 itemHeight。
• data (Array, default [])
  • 原始数据源。

事件

• @scroll="handleScroll"
  • 参数：(event, startIndex)
  • event：scroll-view 滚动事件（含 detail.scrollTop）
  • startIndex：当前可见窗口起点下标

方法（组件实例）

• setStartIndex(index)
  • 设置窗口起点，避免底部空白
• scrollIntoView(id)
  • 设置 scrollIntoId，触发 scroll-view 跳转

注意事项

1. 推荐 itemHeightArray 与 data 长度一致。
2. data 更新时会重置 startIndex=0。
3. scrollIntoView 调用频繁可能导致滚动抖动。

适用场景

• 长列表性能优化
• 复杂行内容（图片、卡片）
• 需要平滑跳转到指定位置