FxVirtualList 虚拟列表

大数据量列表 / 网格的虚拟滚动组件，只渲染可见窗口 + 预渲染项，避免万级 DOM 节点卡顿。采用 builder 工厂 + render 函数模式，4 个组件共享滚动/渲染逻辑，仅注入不同的尺寸计算函数。

组件	维度	尺寸	适用
FxFixedSizeList	一维	行高固定	长列表，项高度一致
FxDynamicSizeList	一维	行高按索引变化	长列表，项高度不等
FxFixedSizeGrid	二维	行高/列宽固定	表格 / 矩阵
FxDynamicSizeGrid	二维	行高/列宽按索引变化	不规则表格

FxVirtualList 属于 @fx/components。

何时使用

• 列表 / 表格项数 > 200，全量渲染出现卡顿
• 选择器 / 树形 / 表格内部需要长列表渲染

固定行高列表（FxFixedSizeList）

itemSize 为数字，total 指定总项数，容器需给固定 height。

<template>
  <div class="vl-demo">
    <FxFixedSizeList :total="1000" :item-size="40" :height="320" :width="420">
      <template #default="{ index, style }">
        <div :style="style" class="vl-item">
          <span class="vl-item__idx">#{{ index + 1 }}</span>
          <span class="vl-item__label">列表项 {{ index + 1 }}</span>
        </div>
      </template>
    </FxFixedSizeList>
  </div>
</template>

<script setup lang="ts">
// 固定行高虚拟列表：1000 项，每项 40px，仅渲染可见窗口 + cache 预渲染
</script>

<style scoped>
.vl-demo :deep(.fx-vl__window) {
  scrollbar-width: none; /* Firefox 隐藏原生滚动条 */
}
.vl-demo :deep(.fx-vl__window::-webkit-scrollbar) {
  display: none; /* webkit 隐藏原生滚动条 */
}
.vl-item {
  display: flex;
  align-items: center;
  gap: 12px;
  padding: 0 16px;
  border-bottom: 1px solid var(--fx-border-color);
  font-size: 14px;
}
.vl-item:hover {
  background-color: var(--fx-color-hover);
}
.vl-item__idx {
  width: 56px;
  color: var(--fx-text-color-secondary);
  font-variant-numeric: tabular-nums;
}
</style>

动态行高列表（FxDynamicSizeList）

itemSize 为函数 (idx) => number，estimatedItemSize 为未测量项的预估行高。内部用二分 + 指数搜索定位。

<template>
  <div class="vl-demo">
    <FxDynamicSizeList
      :total="500"
      :item-size="(i: number) => 40 + (i % 4) * 20"
      :estimated-item-size="50"
      :height="320"
      :width="420"
    >
      <template #default="{ index, style }">
        <div :style="style" class="vl-item">
          <span class="vl-item__idx">#{{ index + 1 }}</span>
          <span>
            动态高度项 {{ index + 1 }}
            <em class="vl-item__meta">高 {{ 40 + (index % 4) * 20 }}px</em>
          </span>
        </div>
      </template>
    </FxDynamicSizeList>
  </div>
</template>

<script setup lang="ts">
// 动态行高虚拟列表：500 项，行高按 idx 变化（40/60/80/100 循环）
</script>

<style scoped>
.vl-demo :deep(.fx-vl__window) {
  scrollbar-width: none;
}
.vl-demo :deep(.fx-vl__window::-webkit-scrollbar) {
  display: none;
}
.vl-item {
  display: flex;
  align-items: center;
  gap: 12px;
  padding: 0 16px;
  border-bottom: 1px solid var(--fx-border-color);
  font-size: 14px;
}
.vl-item:hover {
  background-color: var(--fx-color-hover);
}
.vl-item__idx {
  width: 56px;
  color: var(--fx-text-color-secondary);
  font-variant-numeric: tabular-nums;
}
.vl-item__meta {
  margin-left: 8px;
  color: var(--fx-text-color-secondary);
  font-style: normal;
  font-size: 12px;
}
</style>

横向列表（layout="horizontal"）

layout="horizontal" 时切换为横向虚拟滚动：itemSize 表示每项宽度，width 是可见宽，纵向滚动条自动切换为底部横向滚动条。

<template>
  <div class="vl-demo-h">
    <FxFixedSizeList
      :total="500"
      :item-size="140"
      layout="horizontal"
      :height="140"
      :width="520"
    >
      <template #default="{ index, style }">
        <div :style="style" class="h-card">
          <div class="h-card__avatar">
            {{ String.fromCharCode(65 + (index % 26)) }}
          </div>
          <div class="h-card__body">
            <div class="h-card__title">卡片 {{ index + 1 }}</div>
            <div class="h-card__sub">横向滚动</div>
          </div>
        </div>
      </template>
    </FxFixedSizeList>
  </div>
</template>

<script setup lang="ts">
// 横向列表：layout="horizontal"，横向虚拟滚动 + 底部自定义横向滚动条
// itemSize 在横向 layout 下表示每项宽度
</script>

<style scoped>
.h-card {
  display: flex;
  align-items: center;
  gap: 10px;
  padding: 0 14px;
  border-right: 1px solid var(--fx-border-color);
}
.h-card__avatar {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 40px;
  height: 40px;
  border-radius: 50%;
  background-color: var(--fx-color-hover);
  color: var(--fx-text-color-primary);
  font-size: 16px;
  font-weight: 600;
  flex-shrink: 0;
}
.h-card__body {
  display: flex;
  flex-direction: column;
  gap: 2px;
  overflow: hidden;
}
.h-card__title {
  font-size: 13px;
  color: var(--fx-text-color-primary);
}
.h-card__sub {
  font-size: 12px;
  color: var(--fx-text-color-secondary);
}
</style>

固定网格（FxFixedSizeGrid）

total-row × total-column 网格，row-height / column-width 为数字。Grid 容器 overflow: hidden，滚动靠 wheel / 触摸 / scrollTo，配套横向 + 纵向两条自定义滚动条。

<template>
  <div class="grid-demo">
    <FxFixedSizeGrid
      :total-row="1000"
      :total-column="50"
      :row-height="36"
      :column-width="100"
      :height="320"
      :width="520"
    >
      <template #default="{ rowIndex, columnIndex, style }">
        <div :style="style" class="grid-cell">
          R{{ rowIndex + 1 }} · C{{ columnIndex + 1 }}
        </div>
      </template>
    </FxFixedSizeGrid>
  </div>
</template>

<script setup lang="ts">
// 固定网格：1000 行 × 50 列，行高 36px、列宽 100px
// Grid 容器 overflow: hidden，滚动靠 wheel/触摸/scrollTo，不显示原生滚动条
</script>

<style scoped>
.grid-cell {
  display: flex;
  align-items: center;
  padding: 0 10px;
  border-right: 1px solid var(--fx-border-color);
  border-bottom: 1px solid var(--fx-border-color);
  font-size: 12px;
  color: var(--fx-text-color-secondary);
  font-variant-numeric: tabular-nums;
}
.grid-cell:hover {
  background-color: var(--fx-color-hover);
}
</style>

动态网格（FxDynamicSizeGrid）

row-height / column-width 为函数，按索引返回尺寸；estimated-row-height / estimated-column-width 为未测量项的预估值。

<template>
  <div class="grid-demo">
    <FxDynamicSizeGrid
      :total-row="500"
      :total-column="30"
      :row-height="(i: number) => 36 + (i % 3) * 12"
      :column-width="(i: number) => 80 + (i % 4) * 30"
      :estimated-row-height="48"
      :estimated-column-width="110"
      :height="320"
      :width="520"
    >
      <template #default="{ rowIndex, columnIndex, style }">
        <div :style="style" class="grid-cell">
          <span class="grid-cell__pos">{{ rowIndex + 1 }},{{ columnIndex + 1 }}</span>
        </div>
      </template>
    </FxDynamicSizeGrid>
  </div>
</template>

<script setup lang="ts">
// 动态网格：500 行 × 30 列，行高/列宽按索引变化
</script>

<style scoped>
.grid-cell {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 0 10px;
  border-right: 1px solid var(--fx-border-color);
  border-bottom: 1px solid var(--fx-border-color);
  font-size: 12px;
  color: var(--fx-text-color-secondary);
  font-variant-numeric: tabular-nums;
}
.grid-cell:hover {
  background-color: var(--fx-color-hover);
}
</style>

API

List props（FxFixedSizeList / FxDynamicSizeList）

属性	说明	类型	默认值
total	总项数	number	(必填)
itemSize	行高。FixedSize 传数字；DynamicSize 传函数	number | ((idx) => number)	(必填)
height	容器高	string | number	(必填)
width	容器宽（横向 layout 时必填）	string | number	—
layout	滚动方向	'vertical' | 'horizontal'	vertical
cache	上下预渲染项数	number	2
init-scroll-offset	初始滚动偏移	number	0
estimated-item-size	预估行高（仅 DynamicSize）	number	50
use-is-scrolling	向 slot 提供 isScrolling	boolean	false
direction	书写方向	'ltr' | 'rtl'	ltr
inner-width	内层宽（横向 layout）	string | number	—
scrollbar-always-on	自定义滚动条常驻	boolean	false

Grid props（FxFixedSizeGrid / FxDynamicSizeGrid）

属性	说明	类型	默认值
total-row	总行数	number	(必填)
total-column	总列数	number	(必填)
row-height	行高。FixedSize 数字；DynamicSize 函数	number | ((idx) => number)	(必填)
column-width	列宽。FixedSize 数字；DynamicSize 函数	number | ((idx) => number)	(必填)
height	容器高	string | number	(必填)
width	容器宽	string | number	(必填)
row-cache	行预渲染数	number	2
column-cache	列预渲染数	number	2
init-scroll-left	初始横向偏移	number	0
init-scroll-top	初始纵向偏移	number	0
estimated-row-height	预估行高（仅 DynamicSize）	number	50
estimated-column-width	预估列宽（仅 DynamicSize）	number	50
item-key	单元格 key 生成函数	(args) => string | number	${row}:${col}
use-is-scrolling	向 slot 提供 isScrolling	boolean	false
direction	书写方向	'ltr' | 'rtl'	ltr
h-scrollbar-size	横向滚动条尺寸（px）	number	6
v-scrollbar-size	纵向滚动条尺寸（px）	number	6
scrollbar-start-gap	滚动条起始间距	number	0
scrollbar-end-gap	滚动条末尾间距	number	2
role	aria role	string	—

Slots

List default：{ index, style, data?, isScrolling? }Grid default：{ rowIndex, columnIndex, style, data?, isScrolling? }

style 必须绑定到项根元素（组件靠 absolute 定位摆放每项）。

Events

事件名	说明	回调参数
item-rendered	可见区渲染变化	List: (cacheStart, cacheEnd, visibleStart, visibleEnd)；Grid: (params) 对象含行列的 cacheStart/End + visibleStart/End
scroll	滚动时	List: (scrollDir, scrollOffset, updateRequested)；Grid: (params) 对象含 xAxisScrollDir / yAxisScrollDir / scrollLeft / scrollTop / updateRequested

Exposes

List：scrollTo(offset) / scrollToItem(idx, alignment?) / states / windowRef / innerRef / getItemStyleCache / resetScrollTop

Grid：scrollTo({ scrollLeft?, scrollTop? }) / scrollToItem(rowIdx?, colIdx?, alignment?) / states / windowRef / innerRef / getItemStyleCache / touchStartX / touchStartY / handleTouchStart / handleTouchMove

alignment 取值：'auto' | 'smart' | 'start' | 'center' | 'end'

说明

• List 项 style 必须绑定：slot 根元素 :style="style"，组件靠 absolute 定位摆放每项。
• List 隐藏原生滚动条：List 用自定义滚动条，原生滚动条需自行隐藏（:deep(.fx-vl__window) { scrollbar-width: none }）。
• Grid 容器 overflow: hidden：不显示原生滚动条，滚动靠 wheel / 触摸 / scrollTo。