xtf-virtual-list

组件说明

xtf-virtual-list 是虚拟列表组件，适用于大量数据渲染；仅挂载可视区条目，并支持动态高度和吸顶项。 核心能力以当前 xtf-virtual-list.vue 源码为准。

---

基础用法

1. 基础用法

最小配置下即可完成常见业务交互：

<template>
  <xtf-virtual-list :items="items" style="height: 400rpx">
    <template #default="{ item }"><xtf-cell :title="item.title" /></template>
  </xtf-virtual-list>
</template>

<script>
export default {
  data() {
    return {
      value: '',
      items: Array.from({ length: 80 }, (_, index) => ({
        id: index,
        title: '列表项 ' + (index + 1)
      }))
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

2. 核心交互

监听组件事件并维护页面状态：

<template>
  <xtf-virtual-list
    :items="items"
    dynamic
    auto-measure
    style="height: 400rpx"
    @visible-range-change="onEvent"
    ><template #default="{ item, measure }"
      ><xtf-cell :title="item.title" @tap="measure(88)"
    /></template>
  </xtf-virtual-list>
</template>

<script>
export default {
  data() {
    return {
      value: '',
      items: Array.from({ length: 80 }, (_, index) => ({
        id: index,
        title: '列表项 ' + (index + 1)
      }))
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

3. 进阶配置

组合布局、样式或插槽能力：

<template>
  <xtf-virtual-list
    ref="list"
    :items="items"
    :item-height="88"
    style="height: 400rpx"
    @scroll-to-lower="onEvent"
  >
    <template #default="{ item, isEven, itemHeight, isSticky }">
      <view
        :style="{
          height: itemHeight + 'px',
          padding: '24rpx 32rpx',
          boxSizing: 'border-box',
          background: isSticky ? '#e6f4ff' : isEven ? '#f7f8fa' : '#ffffff'
        }"
      >
        <text>{{ item.title }}</text>
      </view>
    </template>
  </xtf-virtual-list>
</template>

<script>
export default {
  data() {
    return {
      value: '',
      items: Array.from({ length: 80 }, (_, index) => ({
        id: index,
        title: '列表项 ' + (index + 1)
      }))
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
items	Array	function() {	控制组件的 items 行为。	按业务需要设置。
stickyItems	Array	function() {	控制组件的 stickyItems 行为。	按业务需要设置。
stickyField	String	''	控制组件的 stickyField 行为。	按业务需要设置。
stickyOffset	Number	0	控制组件的 stickyOffset 行为。	按业务需要设置。
itemHeight	[String, Number]	88	控制组件的 itemHeight 行为。	按业务需要设置。
dynamic	Boolean	false	控制组件的 dynamic 行为。	按业务需要设置。
minItemHeight	[String, Number]	88	控制组件的 minItemHeight 行为。	按业务需要设置。
getItemHeight	Function	null	控制组件的 getItemHeight 行为。	按业务需要设置。
autoMeasure	Boolean	false	控制组件的 autoMeasure 行为。	按业务需要设置。
bufferSize	[String, Number]	4	控制组件的 bufferSize 行为。	按业务需要设置。
keyField	String	'id'	控制组件的 keyField 行为。	按业务需要设置。
visibleCount	[String, Number]	0	控制组件的 visibleCount 行为。	按业务需要设置。
overscan	[String, Number]	2	控制组件的 overscan 行为。	按业务需要设置。
showScrollbar	Boolean	true	控制组件的 showScrollbar 行为。	按业务需要设置。
bounces	Boolean	true	控制组件的 bounces 行为。	按业务需要设置。
loadingMore	Boolean	false	控制组件的 loadingMore 行为。	按业务需要设置。
finished	Boolean	false	控制组件的 finished 行为。	按业务需要设置。
loadingText	String	''	控制组件的 loadingText 行为。	按业务需要设置。
finishedText	String	''	控制组件的 finishedText 行为。	按业务需要设置。
customClass	String	''	控制组件的 customClass 行为。	按业务需要设置。
customStyle	[String, Object]	''	控制组件的 customStyle 行为。	按业务需要设置。

数据项结构

字段	类型	默认值	说明
id/key	String | Number	index	稳定键；列表、轮播和瀑布流项目建议提供。
title/label/name	String	''	展示名称，具体读取字段见组件对应 prop。
disabled	Boolean	false	禁用可交互项目。

---

事件

事件名称	触发时机	回调参数	参数说明
scroll	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('scroll', ...) 为准。
scroll-to-lower	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('scroll-to-lower', ...) 为准。
height-change	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('height-change', ...) 为准。
visible-range-change	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('visible-range-change', ...) 为准。

事件使用示例

<template>
  <xtf-virtual-list @scroll="onEvent" />
</template>
<script>
export default {
  methods: {
    onEvent(payload) {
      console.log('收到事件', payload)
    }
  }
}
</script>

---

插槽

插槽名	说明	作用域参数
default	自定义可视区列表项。	item、index、isEven、itemHeight、isSticky、measure

---

方法

scrollToIndex(index)、scrollToTop()、scrollToKey(key)、refresh()、updateItemHeight(index, height)。

使用示例：

this.$refs.list.refresh()

---

主题说明

• var(--xtf-color-surface) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-text-secondary) 参与组件的颜色、背景、边框或动效呈现。
• 视觉变体的可选值以 variant、theme、layout 等属性在源码中的分支为准。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。