更新记录

1.0.1（2026-03-30）

• 将 readme.md 中的 HTML 视频标签改为更通用的 Markdown 视频链接

1.0.0（2026-03-30）

• 初始化 hans-virtual-list uni_modules 组件目录

平台兼容性

uni-app(5.01)

hans-virtual-list

演示视频

Android

点击查看 Android 演示视频

iOS

点击查看 iOS 演示视频

hans-virtual-list 是一个用于 uni-app 的虚拟列表组件，适合长列表场景。

当前不兼容 uni-app x。

支持三种高度模式：

• fixed：固定行高
• estimate：使用估算高度
• dynamic：先估算，再按实际渲染结果回填高度

基础用法

<template>
  <hans-virtual-list
    :items="items"
    key-field="id"
    :height="560"
    height-mode="dynamic"
    :estimated-item-height="96"
    :overscan="8"
  >
    <template #default="{ item, index, height, measured }">
      <view class="row">
        <text>{{ index }}. {{ item.title }}</text>
        <text>{{ height }} / {{ measured ? 'measured' : 'estimated' }}</text>
      </view>
    </template>
  </hans-virtual-list>
</template>

<script>
import HansVirtualList from '@/uni_modules/hans-virtual-list/components/hans-virtual-list/hans-virtual-list.vue'

export default {
  components: {
    HansVirtualList,
  },
  data() {
    return {
      items: [],
    }
  },
}
</script>

Props

pretextOptions

启用 usePretext 时，可通过 pretextOptions 传入文本预测参数。常用字段：

示例：

pretextOptions: {
  font: '14px sans-serif',
  lineHeight: 22,
  width: 280,
  extraHeight: 48,
  getText(item) {
    return item && item.content ? item.content : ''
  },
}

插槽

默认插槽参数：

事件

使用建议

• 列表项高度稳定时优先用 fixed
• 高度不固定但可大致预估时用 estimate
• 高度依赖真实渲染结果时用 dynamic
• keyField 必须稳定且唯一，否则高度缓存会错位
• dynamic 模式下如果列表项内容会变化，建议提供 itemLayoutFingerprint