VirtualViewList API
本页汇总 VirtualViewList 组件的关键方法、属性与回调，帮助你在项目中更精确地控制虚拟列表行为。
属性总览
| 分类 | 成员 | 默认值 | 说明 |
|---|---|---|---|
| 布局 | layoutType | ViewLayoutType.VERTICAL | 列表布局类型。 |
| 布局 | scrollDirection | ScrollDirection.VERTICAL | 网格模式下的主轴滚动方向。 |
| 渲染方向 | verticalRenderDirection | TOP_TO_BOTTOM | 垂直布局渲染顺序。 |
| 渲染方向 | horizontalRenderDirection | LEFT_TO_RIGHT | 水平布局渲染顺序。 |
| 间距 | itemSpacing | 10 | 非网格模式的项间距。 |
| 网格 | cols | 2 | 垂直滚动时的列数。 |
| 网格 | rows | 2 | 水平滚动时的行数。 |
| 网格 | girdVertRowsSpacing | 10 | 垂直滚动网格的行间距。 |
| 网格 | girdVertColsSpacing | 10 | 垂直滚动网格的列间距。 |
| 网格 | girdHoriRowsSpacing | 10 | 水平滚动网格的行间距。 |
| 网格 | girdHoriColsSpacing | 10 | 水平滚动网格的列间距。 |
| 内边距 | paddingTop / paddingBottom | 0 | 垂直模式内容区内边距。 |
| 内边距 | paddingLeft / paddingRight | 0 | 水平模式内容区内边距。 |
| 高级 | enableNestedSupport | false | 是否启用嵌套触摸处理。 |
| 高级 | autoOptimizePerformance | true | 是否启用自动性能优化。 |
| 高级 | cacheRatio | 0.1 | 预加载缓冲区大小。 |
所有属性均可在 Cocos Creator 的检查器中配置，运行时也可通过脚本修改后调用
Refresh()重新计算布局。
模板与回调
| 方法 | 签名 | 说明 |
|---|---|---|
RegisterTemplate | (type, nodeOrGetter, isDefault = false) | 注册单个模板。nodeOrGetter 可为节点或返回节点的函数。 |
RegisterTemplates | (templates, defaultType?) | 批量注册模板并指定默认类型。 |
ClearTemplates | () | 清空所有模板与对象池。 |
SetCallbacks | (callbacks: IVirtualListCallbacks) | 设置渲染、滚动、加载完成、下拉刷新、上拉加载等回调。 |
IVirtualListCallbacks 接口
| 回调 | 签名 | 说明 |
|---|---|---|
onItemInit | (node: Node, index: number) => void | 节点首次创建时触发。适合初始化组件、绑定事件。 |
onItemUpdate | (node: Node, index: number) => void | 节点重新进入可见区域时触发。适合刷新数据显示。 |
onScrolling | (scrollRatio: number) => void | 滚动过程中持续触发，scrollRatio 为 0~1 的滚动进度。 |
onLoadFinished | () => void | 首次加载或刷新完成后调用。适合隐藏加载动画。 |
onPullDownRefresh | () => Promise<PullRefreshResult> | void | 下拉刷新触发（超过 50px 且间隔 > 1 秒）。可返回 Promise，自动调用 PrependData。 |
onPullUpLoad | () => Promise<PullRefreshResult> | void | 上拉加载触发（超过 50px 且间隔 > 1 秒）。可返回 Promise，自动调用 AppendData。 |
PullRefreshResult 接口：
ts
interface PullRefreshResult {
types: Array<string | number>; // 新数据的模板类型列表
sizes?: number[]; // 可选的自定义尺寸列表
}数据操作
| 方法 | 签名 | 说明 |
|---|---|---|
ReloadData | (typeArray, customSize?) | 重新加载全部数据，清空旧数据。typeArray 长度即列表长度，customSize 可指定每项尺寸。 |
PrependData | (newData, keepScrollPosition?, sizeList?) | 在列表顶部插入数据。keepScrollPosition=true 时保持当前可见内容不变（适合聊天刷新）。 |
AppendData | (newData, sizeList?) | 在列表底部追加数据。常用于分页加载、滚动到底部加载更多。 |
RefreshData | (newData, keepScrollPosition?, compareFunc?) | 增量刷新数据。通过 compareFunc 对比新旧数据，仅更新变化的项，未变化项保持原节点不重建。 |
InsertItemAt | (index, type, animate?, size?) | 在指定索引插入单项，支持动画效果和自定义尺寸。 |
RemoveItemAt | (index, animate?) | 移除指定索引项，支持动画。动画完成后自动回收节点。 |
UpdateItemAt | (index, type?) | 刷新单项内容，可选传入新模板类型切换样式。若不在可见区域则延迟更新。 |
UpdateItemSize | (index, newSize) | 非网格模式下更新单项尺寸，自动重新布局。适用于动态高度场景。 |
Clear | () | 清空所有数据与节点，重置为空列表状态。 |
Refresh | () | 手动触发重新布局。当修改配置属性后需要刷新时调用。 |
滚动控制
| 方法 | 说明 |
|---|---|
ScrollToIndex(index, duration = 0.3, callback?) | 平滑滚动至指定索引。duration = 0 时立即跳转。 |
ScrollToTop(duration = 0.3, callback?) | 滚动至顶部。 |
ScrollToBottom(duration = 0.3, callback?) | 滚动至底部。 |
GetItemNode(index) | 返回可见节点实例，若节点未显示则返回 null。 |
性能与调试
| 方法 | 说明 |
|---|---|
PreloadItems(count = mAutoPreloadCount) | 预创建一定数量的节点以缩短初次渲染时间。 |
EnableDebugMode(enabled = true) | 开启日志与性能统计输出。 |
GetTotalItemCount() | 返回数据源长度。 |
GetTotalItemNodeCount() | 返回当前内容节点下的子节点数量。 |
GetStatus() | 返回综合状态：itemCount、visibleCount、poolSize、isLowPerformanceMode、memoryUsage。 |
常见使用模式
ts
const list = scrollContent.getComponent(VirtualViewList)!;
list.RegisterTemplates([
{ type: 'item', node: () => createItemPrefab() },
{ type: 'banner', node: () => createBannerPrefab() }
], 'item');
list.SetCallbacks({
onItemInit: (node, index) => bindNode(node, data[index]),
onItemUpdate: (node, index) => refreshNode(node, data[index]),
onScrolling: ratio => progressBar.progress = ratio
});
list.ReloadData(data.map(entry => entry.type));如需深入了解内部算法，可阅读 VirtualListDataManager、VirtualListNodeManager 与 VirtualListPerformanceManager 的实现。