组件与属性

本节集中介绍 VirtualViewList 组件的核心作用、主要配置项以及与其它模块的协作方式，便于快速查阅与团队沟通。

组件概览

脚本路径：assets/Script/Core/VirtualList/VirtualViewList.ts
依赖管理器：
- VirtualListDataManager：负责数据源、尺寸计算、偏移查找。
- VirtualListNodeManager：负责模板注册、对象池、节点复用与动画。
- VirtualListPerformanceManager：负责性能监控、缓存策略、自适应调优。
适用场景：大数据量列表、聊天记录、排行榜、卡片网格等需要高性能滚动的 UI。

属性一览

属性	枚举 / 取值	说明
`scrollView`	`ScrollView` 组件	绑定宿主 `ScrollView`，控制滚动容器。
`layoutType`	`ViewLayoutType`： `VERTICAL`（垂直列表） `HORIZONTAL`（水平列表） `GRID`（网格列表）	选择列表布局方式。
`scrollDirection`	`ScrollDirection`： `VERTICAL`（纵向滚动） `HORIZONTAL`（横向滚动）	网格模式主轴方向。
`verticalRenderDirection`	`VerticalRenderDirection`： `TOP_TO_BOTTOM`（由上到下） `BOTTOM_TO_TOP`（由下到上）	垂直模式渲染顺序。
`horizontalRenderDirection`	`HorizontalRenderDirection`： `LEFT_TO_RIGHT`（由左到右） `RIGHT_TO_LEFT`（由右到左）	水平模式渲染顺序。
`itemSpacing`	数值（默认 `10`）	列表模式项间距。
`cols`	数值（默认 `2`）	垂直滚动网格的列数。
`rows`	数值（默认 `2`）	水平滚动网格的行数。
`girdVertRowsSpacing`	数值（默认 `10`）	垂直网格行间距。
`girdVertColsSpacing`	数值（默认 `10`）	垂直网格列间距。
`girdHoriRowsSpacing`	数值（默认 `10`）	水平网格行间距。
`girdHoriColsSpacing`	数值（默认 `10`）	水平网格列间距。
`paddingTop` / `paddingBottom`	数值（默认 `0`）	垂直模式上下内边距。
`paddingLeft` / `paddingRight`	数值（默认 `0`）	水平模式左右内边距。
`enableNestedSupport`	`boolean`： `true`（启用） `false`（禁用）	是否开启嵌套列表触摸支持。
`autoOptimizePerformance`	`boolean`： `true`（启用） `false`（禁用）	是否自动调节加载批次与缓存。
`cacheRatio`	数值（默认 `0.1`）	预加载缓冲比例，控制额外可见范围。

常用回调

回调	触发时机	用途
`onItemInit(node, index)`	节点首次创建	初始化节点、挂载组件、缓存引用。
`onItemUpdate(node, index)`	节点重新进入可见范围	根据数据刷新文本、图片等动态内容。
`onScrolling(scrollRatio)`	滚动进行中	结合 UI 进度条、吸顶元素等做联动。
`onLoadFinished()`	首次加载或刷新完成	隐藏加载动画、触发后续逻辑。

相关章节

快速开始：介绍如何挂载组件、注册模板并加载数据。
布局与渲染：讲解布局类型、渲染方向与间距配置。
事件与回调：补充触摸嵌套、滚动事件的细节。
性能优化：提供缓存、分帧、调试模式等策略。

需要了解底层实现，可进一步阅读 VirtualListDataManager.ts、VirtualListNodeManager.ts 与 VirtualListPerformanceManager.ts 的源码注释。