在 UniApp 中实现虚拟列表（Virtual List）需要结合小程序和 H5 的特性进行特殊处理，因为 UniApp 的跨平台特性导致部分 API 和行为与纯 Web 环境不同。以下是详细实现方法和注意事项：

---

一、UniApp 实现虚拟列表的核心步骤

1. 固定高度虚拟列表（推荐）

适用于列表项高度相同的场景（如商品列表）。

实现代码（基于 scroll-view）

<template>
  <scroll-view
    scroll-y
    :style="{ height: viewportHeight + 'px' }"
    @scroll="handleScroll"
    :scroll-top="scrollTop"
  >
    <!-- 占位元素，撑开滚动条 -->
    <view :style="{ height: totalHeight + 'px' }"></view>

    <!-- 实际渲染的列表项 -->
    <view
      class="visible-items"
      :style="{ transform: `translateY(${offsetY}px)` }"
    >
      <view
        v-for="item in visibleItems"
        :key="item.id"
        class="list-item"
        :style="{ height: itemHeight + 'px' }"
      >
        {{ item.name }}
      </view>
    </view>
  </scroll-view>
</template>

<script>
export default {
  data() {
    return {
      data: [], // 原始数据（需提前初始化）
      itemHeight: 80, // 每项固定高度
      viewportHeight: 500, // 可视区域高度
      scrollTop: 0, // 滚动位置
    };
  },
  computed: {
    // 计算总高度
    totalHeight() {
      return this.data.length * this.itemHeight;
    },
    // 计算起始索引
    startIndex() {
      return Math.floor(this.scrollTop / this.itemHeight);
    },
    // 计算可见项数量
    visibleCount() {
      return Math.ceil(this.viewportHeight / this.itemHeight);
    },
    // 获取可见数据
    visibleItems() {
      return this.data.slice(
        this.startIndex,
        this.startIndex + this.visibleCount + 5 // 加5项缓冲
      );
    },
    // 计算偏移量
    offsetY() {
      return this.startIndex * this.itemHeight;
    },
  },
  methods: {
    handleScroll(e) {
      this.scrollTop = e.detail.scrollTop;
    },
  },
  onLoad() {
    // 模拟数据
    this.data = Array.from({ length: 1000 }, (_, i) => ({
      id: i,
      name: `Item ${i + 1}`,
    }));
  },
};
</script>

<style>
.visible-items {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
.list-item {
  padding: 10px;
  border-bottom: 1px solid #eee;
}
</style>

2、动态高度虚拟列表

适用于列表项高度不固定的场景（如朋友圈动态）。
关键处理

1. 维护位置缓存：在 onReady 中初始化预估高度，渲染后通过 uni.createSelectorQuery() 获取实际高度并更新缓存。
2. 动态计算范围：使用二分查找确定 startIndex。

代码片段（动态高度测量）

// 在 onReady 中初始化位置缓存
initPositions() {
  this.positions = this.data.map((_, index) => ({
    index,
    height: 60, // 预估高度
    top: index * 60,
    bottom: (index + 1) * 60,
  }));
},

// 测量实际高度并更新缓存
measureItemHeights() {
  const queries = [];
  this.visibleItems.forEach(item => {
    queries.push(new Promise(resolve => {
      uni.createSelectorQuery()
        .select(`#item-${item.id}`)
        .boundingClientRect(rect => {
          if (rect) {
            const index = item.id;
            this.positions[index].height = rect.height;
            this.positions[index].bottom = this.positions[index].top + rect.height;
            resolve();
          }
        }).exec();
    }));
  });
  Promise.all(queries).then(() => this.updateSubsequentPositions());
},

// 更新后续元素的位置
updateSubsequentPositions() {
  for (let i = 1; i < this.positions.length; i++) {
    this.positions[i].top = this.positions[i - 1].bottom;
    this.positions[i].bottom = this.positions[i].top + this.positions[i].height;
  }
},

二、UniApp 特殊处理要点

1、平台差异处理

• 小程序：
  • 使用 scroll-view 替代原生滚动，需设置 scroll-y 和固定高度。
  • 动态高度测量需用 uni.createSelectorQuery()，而非浏览器 DOM API。
• H5：
  • 可直接使用 Web 的 IntersectionObserver 或 getBoundingClientRect。

2、性能优化

• 避免频繁更新：在 handleScroll 中使用防抖（如 lodash.throttle），限制滚动事件频率。
• 复用 DOM 节点：使用 v-for 的 :key 确保节点复用，减少渲染开销。

3、已知问题与解决方案

• 小程序闪屏问题：快速滚动时可能出现白屏，可通过增加缓冲区（多渲染 5-10 项）缓解。
• iOS 惯性滚动不触发事件：监听 scrolltoupper 和 scrolltolower 作为补充。

三、推荐方案

1、使用现成组件

• 官方推荐：
  UniApp 插件市场搜索 z-paging，支持虚拟列表 + 分页加载。
• 社区库：
  uvue-waterfall（类似瀑布流虚拟列表）。

2、手动实现建议

• 简单场景：固定高度 + scroll-view（代码见上文）。
• 复杂场景：动态高度 + z-paging 或基于 uni.createSelectorQuery() 的自定义实现。

四、完整示例（动态高度 + 小程序兼容）

<template>
  <scroll-view
    scroll-y
    :style="{ height: viewportHeight + 'px' }"
    @scroll="handleScroll"
  >
    <view :style="{ height: totalHeight + 'px' }"></view>
    <view
      class="visible-items"
      :style="{ transform: `translateY(${offsetY}px)` }"
    >
      <view
        v-for="item in visibleItems"
        :key="item.id"
        :id="`item-${item.id}`"
        class="list-item"
      >
        <!-- 动态内容，高度不固定 -->
        <text>{{ item.text }}</text>
        <image :src="item.image" mode="widthFix"></image>
      </view>
    </view>
  </scroll-view>
</template>

<script>
export default {
  data() {
    return {
      data: [],
      positions: [],
      scrollTop: 0,
      viewportHeight: 600,
    };
  },
  mounted() {
    this.initData();
  },
  methods: {
    initData() {
      // 模拟数据
      this.data = Array.from({ length: 100 }, (_, i) => ({
        id: i,
        text: `Item ${i + 1}`,
        image: "https://placeholder.com/200x" + (100 + Math.random() * 100),
      }));
      this.initPositions();
    },
    initPositions() {
      this.positions = this.data.map((_, i) => ({
        index: i,
        height: 100, // 预估高度
        top: i * 100,
        bottom: (i + 1) * 100,
      }));
    },
    handleScroll(e) {
      this.scrollTop = e.detail.scrollTop;
      this.$nextTick(this.measureItemHeights);
    },
    measureItemHeights() {
      // 测量逻辑（见上文）
    },
  },
  computed: {
    // ...（同固定高度示例，但基于 this.positions 计算）
  },
};
</script>

五、总结

在 UniApp 中实现虚拟列表需注意：

1. 平台差异：小程序用 scroll-view + createSelectorQuery，H5 可用 Web API。
2. 性能优化：防抖、缓冲区、DOM 复用。
3. 复杂场景：优先使用 z-paging 等成熟组件，动态高度需手动维护位置缓存。

更新日志

2025/8/24 08:17

查看所有更新日志

• e7112-1于 2025/8/24