Component & Props
This page summarises the role of VirtualViewList, its configuration options, and how it collaborates with helper managers and demos.
Overview
- Use case: high-volume scrollable lists in games or apps.
- Key techniques: node pooling, viewport culling, batched refresh.
- Main script:
assets/Script/Core/VirtualList/VirtualViewList.ts - Managers:
VirtualListDataManager: data source, size cache, offset lookup.VirtualListNodeManager: templates, pooling, animations.VirtualListPerformanceManager: frame monitoring, adaptive caching.
Highlights
- Node reuse keeps memory low even with thousands of items.
- Viewport-driven rendering reduces draw calls.
- Supports vertical, horizontal, grid and reverse directions.
- Frame-splitting avoids long stalls when loading huge datasets.
- Dynamic operations: insert, delete, update, resize items at runtime.
- Nested scroll friendly; optional
VirtualCullingViewportfor advanced culling.
Environment
- Engine: Cocos Creator 3.x / 2.x
- Language: TypeScript
- Targets: Web, mini games, Android, iOS
Platform Matrix
| Cocos Creator | Mini Games | HTML5 | Android | iOS |
|---|---|---|---|---|
| 3.x | ✔ | ✔ | ✔ | ✔ |
| 2.x | ✔ | ✔ | ✔ | ✔ |
Key Properties
| Property | Values | Description |
|---|---|---|
scrollView | ScrollView | Host scroll view component. |
layoutType | VERTICAL / HORIZONTAL / GRID | List layout mode. |
scrollDirection | VERTICAL / HORIZONTAL | Main axis for grid layout. |
verticalRenderDirection | TOP_TO_BOTTOM / BOTTOM_TO_TOP | Vertical rendering order. |
horizontalRenderDirection | LEFT_TO_RIGHT / RIGHT_TO_LEFT | Horizontal rendering order. |
itemSpacing | number (default 10) | Spacing in list mode. |
cols / rows | number (default 2) | Grid columns or rows. |
girdVertRowsSpacing | number (default 10) | Grid row spacing (vertical). |
girdVertColsSpacing | number (default 10) | Grid column spacing (vertical). |
girdHoriRowsSpacing | number (default 10) | Grid row spacing (horizontal). |
girdHoriColsSpacing | number (default 10) | Grid column spacing (horizontal). |
paddingTop / paddingBottom | number | Vertical padding. |
paddingLeft / paddingRight | number | Horizontal padding. |
enableNestedSupport | boolean | Enable nested scroll handling. |
autoOptimizePerformance | boolean | Auto adjust cache & batch size. |
cacheRatio | number (default 0.1) | Preload buffer multiplier. |
Frequently Used APIs
ReloadData(typeArray, customSize?)InsertItemAt(index, type, animate?, size?)RemoveItemAt(index, animate?)RegisterTemplate(type, nodeOrGetter, isDefault?)ScrollToIndex(index, duration?, callback?)UpdateItemAt(index, type?)UpdateItemSize(index, newSize)PreloadItems(count?)Refresh()
Callbacks
| Callback | Trigger | Usage |
|---|---|---|
onItemInit | Node first created | Initial binding, cache refs. |
onItemUpdate | Node becomes visible again | Refresh visuals with latest data. |
onScrolling | During scroll | Update progress bars, sticky headers etc. |
onLoadFinished | Initial load / refresh completed | Hide loaders, start follow-up logic. |
Release Notes
| Version | Date | Highlights |
|---|---|---|
| 3.2.1 | 2025-10-14 | Demo suite refreshed, polish tweaks. |
| 3.2.0 | 2025-09-29 | Chat text measurement optimised; adaptive demos. |
| 3.1.0 | 2025-09-23 | New chat & backpack demos; InsertItemAt size parameter; refactored demos. |
| 3.0.0 | 2025-09-09 | Reverse rendering support, ranking/chat/card demos added. |
| 1.0.0 | 2025-03-06 | Initial release with virtual list, pooling, frame-splitting. |