组件概述
虚拟列表专为大型游戏和应用中展示大量数据列表而设计。通过动态节点管理与复用技术，相比原生 ScrollView 可大幅提升滚动性能和内存利用率。
立即检验
核心特性
- 节点动态复用，降低内存占用
- 视锥剔除优化，提升渲染性能
- 支持多种布局模式（垂直、水平、网格、嵌套）
- 分帧加载，避免卡顿
- 支持下拉刷新、上拉刷新
- 支持动态修改数据和尺寸
- 多个demo实践（背包，聊天，排行榜，卡牌）
API文档
开发环境
- 引擎版本：Cocos Creator 3.x/2.x
- 编程语言：TypeScript
全平台适配
| Cocos Creator版本 | 微信/抖音/快手小游戏 | HTML5 (Web) | Android | iOS |
|---|---|---|---|---|
| 3.x |  |
|
|
|
| 2.x | |
|
|
|
在线演示
节点复用与视锥剔除是虚拟列表的核心技术，确保高性能渲染与低内存占用。
针对同方向嵌套列表且需禁止滑动的场景，
VirtualCullingViewport组件提供独立剔除能力，挂载即生效，根据视野范围动态创建与回收 item 节点，保证嵌套列表性能优化。
插件优势
-
注释清晰，挂载即用
-
丰富的布局支持
-
自定义模板：支持任意数量
-
支持嵌套：触摸事件可传递，内部列表事件可作用于外部列表
-
分帧加载：避免一次性加载大量数据，保证界面流畅
-
节点池管理：复用节点，减少频繁创建与销毁开销
-
下拉 / 上拉刷新：传入回调，即可使用
-
防抖处理：滚动事件防抖，降低重复更新，提高性能
-
动态数据更新：支持实时修改列表项内容
-
动态尺寸调整：支持列表项尺寸变更并自动布局
-
高度复用：节点池与分帧加载结合，降低内存占用
-
低 DrawCall：优化渲染流程，减少 DrawCall 提升性能
常用接口
- ReloadData：重载数据，刷新列表
/**
* 重新加载数据源
* @param typeArray 类型数据
* @param customSize 自定义尺寸数组
* @returns
*/
public ReloadData(typeArray: Array<string | number>, customSize: number[] = []): void;
- InsertItemAt：指定位置插入Item
/**
* 在指定位置插入项目
* @param index 插入位置索引
* @param type 插入的类型
* @param animate 是否动画
* @param size 插入的尺寸
*/
public InsertItemAt(index: number, type: string | number, animate: boolean = false, size: number = 0): void
- RemoveItemAt：指定位置删除Item
/**
* 移除指定位置的项目
* @param index 要移除的项目索引
* @param animate 是否使用动画效果
*/
public RemoveItemAt(index: number, animate: boolean = false): void;
- RegisterTemplate: 注册Item模板
/**
* 注册模板类型
* @param type 模板类型标识符
* @param nodeOrGetter 模板节点或获取节点的函数
* @param isDefault 是否设为默认模板
*/
public RegisterTemplate(type: string | number, nodeOrGetter: Node | (() => Node), isDefault: boolean = false): void;
- ScrollToIndex：滚动到指定索引项，使该项出现在屏幕正中央
/**
* 滚动到指定单元格，使该单元格所在行（或单个项）居中显示
* @param index 目标单元格索引
* @param duration 滚动动画时长（秒）
* @param callback 滚动完成回调
*/
public ScrollToIndex(index: number, duration: number = 0.3, callback?: () => void);
- UpdateItemSize：更新指定索引项的尺寸
/**
* 更新指定单元格的尺寸（动态修改后重排）
* 暂不支持网格布局
*/
public UpdateItemSize(index: number, newSize: number);
- UpdateItemAt：更新指定索引项的数据
/**
* 更新指定单元格
* @param index 下标
* @param type 模版类型（可选参数）
* @returns 是否更新成功
*/
public UpdateItemAt(index: number, type?: string | number): boolean;
- Refresh：刷新列表数据或尺寸变化后调用
/**
* 刷新列表（数据或尺寸变化后调用）
*/
public Refresh();
- PreloadItems: 预加载方法
/**
* 预加载数据
*/
public PreloadItems(count: number = this.mAutoPreloadCount);
欢迎加入「星空丨菜鸟小栈」
- 认真讨论技术
- 吐槽引擎缺陷
- 愉快摸鱼聊股票
- 交友约饭嗨起来
限时福利放送，加群领取30元优惠券
联系作者
个人主页： 星空技术探索
作者微信： Chrass-
版本记录（持续更新中）
3.2.4 (2026年01月25日)
- 针对反向渲染代码进行了优化调整，提升渲染性能
- 在背包及聊天模块的 Demo 中，新增下拉与上拉提示
- 引擎升级至 3.8.8 版本
3.2.3（2026年01月09日）
- 新增批量数据操作方法：PrependData（前置追加）、AppendData（后置追加）及智能刷新方法 RefreshData
- 优化列表上下拉刷新逻辑，支持多尺寸 Item 动态刷新与异步回调，适配更多业务场景
- 聊天 Demo 新增下拉刷新历史记录功能
- 修复虚拟列表 Item 尺寸超过一屏时定位不准确的问题
省略中间版本记录
1.0.0（2025年3月6日）
- 初始版本发布
- 实现基本的虚拟列表功能
- 支持动态修改Item数据和尺寸
- 新增分帧加载功能
- 优化节点池管理机制
- 增加防抖动处理
