UviewUltra 4.0

Appearance

VirtualList 虚拟列表 4.4.0 ​

虚拟列表是一种高性能的列表渲染技术，适用于需要渲染大量数据的场景。它通过只渲染可视区域内的元素，大大减少了DOM节点数量，提升了页面性能。

平台差异说明 ​

|App（vue）|App（uvue/uni-app-x）|App（nvue）|H5|小程序| |:-😐:-😐:-😐:-😐:-😐:-😐 |√|√|√|√|

基本使用 ​

通过[listData]传入需要渲染的数据列表，通过插槽自定义列表项内容。

vue
<template>
  <view>
    <up-virtual-list
      :list-data="list"
      :item-height="60"
    >
      <template #item="{ item, index }">
        <view class="list-item">
          <text>Item {{ item.id }}: {{ item.name }}</text>
        </view>
      </template>
    </up-virtual-list>
  </view>
</template>
<style scoped>
.list-item {
  height: 60px;
  display: flex;
  align-items: center;
  padding: 0 15px;
  border-bottom: 1px solid #f0f0f0;
}
</style>
js
<script setup>
import { ref, onMounted } from 'vue';

const list = ref([]);

onMounted(() => {
  // 模拟大量数据
  list.value = Array.from({ length: 10000 }, (_, index) => ({
    id: index + 1,
    name: `Item ${index + 1}`
  }));
});
</script>

设置列表高度 ​

通过[height]设置虚拟列表容器的高度。

vue
<template>
  <view>
    <up-virtual-list
      :list-data="list"
      :height="400"
      :item-height="50"
    >
      <template #item="{ item }">
        <view class="list-item">
          <text>{{ item.name }}</text>
        </view>
      </template>
    </up-virtual-list>
  </view>
</template>
js
<script setup>
import { ref } from 'vue';

const list = ref(Array.from({ length: 1000 }, (_, index) => ({
  id: index,
  name: `Item ${index}`
})));
</script>

自定义缓冲区 ​

通过[buffer]设置可视区域外的缓冲区大小，提升滚动体验。

vue
<template>
  <view>
    <up-virtual-list
      :list-data="list"
      :item-height="60"
      :buffer="10"
    >
      <template #item="{ item }">
        <view class="list-item">
          <text>{{ item.name }}</text>
        </view>
      </template>
    </up-virtual-list>
  </view>
</template>
js
<script setup>
import { ref } from 'vue';

const list = ref(Array.from({ length: 5000 }, (_, index) => ({
  id: index,
  name: `Item ${index}`
})));
</script>

Props ​

参数说明类型默认值可选值
listData列表数据Array[]-
itemHeight列表项高度Number50-
height列表容器高度String | Number100%-
buffer缓冲区大小(可视区域外的渲染数量)Number4-
keyField唯一标识字段名Stringid-
scrollTop当前滚动位置Number0-

Events ​

事件名说明回调参数
update:scrollTop滚动时更新scrollTop值scrollTop
scroll滚动时触发scrollTop

Slots ​

名称说明SlotProps
default列表项内容

方法 ​

通过 ref 可以获取到虚拟列表实例并调用方法：

方法名说明参数
getVisibleRange()获取可见项范围-

监听滚动事件 ​

vue
<template>
  <view>
    <up-virtual-list
      :list-data="list"
      :item-height="60"
      :height="400"
      :scroll-top.sync="currentScrollTop"
      @scroll="handleScroll"
    >
      <template #default="{ item, index }">
        <view class="list-item">
          <text>{{ item.name }}</text>
        </view>
      </template>
    </up-virtual-list>
    
    <view class="scroll-info">
      <text>当前滚动位置: {{ currentScrollTop }}</text>
    </view>
  </view>
</template>
js
<script setup>
import { ref } from 'vue';

const list = ref(Array.from({ length: 3000 }, (_, index) => ({
  id: index,
  name: `Item ${index}`
})));

const currentScrollTop = ref(0);

const handleScroll = (scrollTop) => {
  console.log('滚动位置:', scrollTop);
};
</script>

### 注意事项

1. 每个列表项的高度必须固定且一致，通过`itemHeight`属性设置
2. 数据量越大，虚拟列表的性能优势越明显
3. 如果需要动态高度的列表项，请使用其他解决方案
4. 使用`keyField`指定唯一标识字段，避免渲染异常
5. 可通过[buffer]调整缓冲区大小以平衡性能和体验
6. 组件会自动测量容器高度，也可以通过[height]属性手动指定