VirtualList
虚拟滚动列表底座（泛型）：仅渲染可视区 + overscan 缓冲区高性能渲染超长列表。fixed 定高 O(1) 区间；dynamic 不定高（itemSize='auto'）用 estimatedItemSize 估算 + ResizeObserver 实测回填高度表，前缀和修正偏移/区间并做滚动偏移补偿。支持 vertical/horizontal（horizontal 仅 fixed 定宽，dynamic 退化为按 estimatedItemSize 的定宽）。scrollTarget='self'（默认）内部容器滚动；'window' 用窗口（document）滚动、容器撑高，适合整页长列表（纵向；horizontal 下退化为 self，fixed/dynamic 均复用窗口几何 windowScrollTop）。提供 scrollToIndex 命令式跳转 API。自身无视觉，行渲染由 renderItem 提供。
如何引入
import { VirtualList } from '@chenzy-design/svelte';基础虚拟列表
万行数据仅渲染视口行，固定行高模式
固定行高（1 万行，itemSize=36，仅渲染视口内行）
第 1 行
第 2 行
第 3 行
第 4 行
第 5 行
第 6 行
第 7 行
第 8 行
第 9 行
动态/不定高
itemSize='auto'，ResizeObserver 实测每行真实高度并修正偏移
动态/不定高（itemSize='auto'，估算 56px，实测后修正偏移）
第 1 条 — 虚拟列表只渲
第 2 条 — 虚拟列表只渲染
第 3 条 — 虚拟列表只渲染视
第 4 条 — 虚拟列表只渲染视口
第 5 条 — 虚拟列表只渲染视口内
第 6 条 — 虚拟列表只渲染视口内的
第 7 条 — 虚拟列表只渲染视口内的行
第 8 条 — 虚拟列表只渲染视口内的行，
滚动到指定项
通过 bind:this 拿组件实例，命令式调用 scrollToIndex(index, { align })
#0 — 第 1 行
#1 — 第 2 行
#2 — 第 3 行
#3 — 第 4 行
#4 — 第 5 行
#5 — 第 6 行
#6 — 第 7 行
#7 — 第 8 行
#8 — 第 9 行
横向虚拟化
horizontal 沿 x 轴排列，itemSize 作列宽（仅 fixed 定宽）
横向虚拟化（horizontal，列宽 80px，1 万列只渲染视口列）
1
2
3
自定义项渲染
renderItem 内组合 Tag 与富结构，渲染任务列表
自定义项渲染（renderItem 内组合 Tag + 富结构，固定行高 52px） 任务 1 已完成 任务 2 进行中 任务 3 进行中 任务 4 进行中 任务 5 已完成 任务 6 进行中 任务 7 进行中 任务 8 进行中
P0
P1
P2
P0
P1
P2
P0
P1
API 参考
VirtualList
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
data | 列表数据数组 | T[] | [] |
getKey | 行唯一标识，用于 each key | (item: T, index: number) => string | number | (_, i) => i |
itemSize | 固定行高（px，fixed 定高）；传 'auto' 启用 dynamic 不定高测量 | number | 'auto' | 40 |
estimatedItemSize | dynamic 模式初始估算行高（px），用于首屏占位与总高估算 | number | 40 |
overscan | 可视区上下缓冲行数，消除白屏 | number | 3 |
height | 视口主轴尺寸（vertical 为高度、horizontal 为宽度）；数字按 px，字符串/百分比时用 ResizeObserver 测量 | number | string | 400 |
horizontal | 横向虚拟化：沿 x 轴排列、itemSize 作列宽、读/写 scrollLeft（仅支持 fixed 定宽） | boolean | false |
scrollTarget | 滚动源：'self' 内部容器自身滚动（默认，向后兼容）；'window' 用窗口（document）滚动、容器撑开总高，适合整页长列表（纵向）。horizontal 在 window 下退化为 self。 | 'self' | 'window' | 'self' |
renderItem | 行渲染 Snippet（必填） | Snippet<[item: T, index: number]> | required |
class | 根类名透传 | string | '' |
Slots
| 名称 | 说明 |
|---|---|
renderItem | 行渲染（item, index） |
Methods
| 属性 | 类型 | 说明 |
|---|---|---|
scrollToIndex | (index: number, opts?: { align?: 'start' | 'center' | 'end' }) => void | 命令式滚动到指定索引项（bind:this 后调用）。align 默认 start；horizontal 时写 scrollLeft。index 自动 clamp。 |
Accessibility
| ARIA role | list |
- 视口 role=list，可见行 role=listitem
- 行带 aria-setsize（总数）与 aria-posinset（1 基序号）
- 滚动监听命令式 + rAF 节流，不读 render 期 DOM 几何
- dynamic 行高用 ResizeObserver 命令式实测，cleanup 时 disconnect
- scrollToIndex 为命令式 DOM 写（scrollTop/scrollLeft），放导出函数，不在 render 期
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-virtual-list-bg | var(--cd-color-bg-0) | 虚拟列表容器背景色 |
--cd-virtual-list-scrollbar | var(--cd-color-fill-1) | 虚拟列表滚动条颜色 |