VirtualList 虚拟列表

用于大数据量列表的视口窗口渲染：只渲染可见项（含上下缓冲），首尾 padding 占位撑起滚动高度，滚动事件按 rAF 节流。通用渲染原语，供 table / tree 复用。

基础用法

定高虚拟列表

示例代码

通过 items property（或 items 属性传 JSON 字符串）提供数据，height 定视口高度、item-height 定每项高度；未提供模板时默认渲染 String(item)。

自定义条目内容

oas-item 事件绑定内容

示例代码

每个可见项渲染后派发 oas-item，detail 携带 { index, item, element }，宿主据此填充条目内容；也可以在组件内放 <template slot="item"> 作为每项静态模板。

滚动事件

oas-scroll 窗口展示

可见窗口：0–0 · scrollTop：0

示例代码

滚动事件按 rAF 节流派发 oas-scroll，detail 为 { scrollTop, start, end }。

渲染缓冲

buffer 控制上下超出可视区的预渲染项数（默认 4）：buffer 越大，滚动时越少出现空白（白屏），代价是渲染的 DOM 节点更多。

渲染缓冲 buffer

buffer="0"：渲染项数 —，仅渲染可视窗口内的项。

buffer="8"：渲染项数 —，上下各多预渲染 8 项。

示例代码

自定义滚动容器

scroll-target 外部容器

示例代码

设置 scroll-target（CSS 选择器）后，组件不自带滚动条，改由外部容器滚动整段内容（如页面级滚动），窗口按外部容器的 scrollTop 计算。

API

属性

属性	说明	类型	默认值
buffer	上下预渲染项数（超出可视区提前渲染，减少滚动白屏）	string	4
height	视口高度（px）	string	320
item-height	每项固定高度（px）	string	36
items	数据数组（property 通道，优先于 items 属性）；数据 JSON 字符串（属性通道）	unknown[]	[]
scroll-target	外部滚动容器 CSS 选择器；设置后组件不自带滚动条，监听外部滚动	string	—

事件

事件	说明
oas-item	每个可见项渲染后派发，detail: { index, item, element }
oas-scroll	滚动事件（rAF 节流），detail: { scrollTop, start, end }

插槽

名称	说明
template[slot="item"]	每项静态模板，克隆到每个可见项容器（可选）

部件：::part(viewport) 滚动视口、::part(inner) 内容、::part(padding-top) / ::part(padding-bottom) 占位、::part(item) 单项。